diff --git a/xml/FrameworksIndex/xamarinandroid-7.1.xml b/xml/FrameworksIndex/xamarinandroid-7.1.xml deleted file mode 100644 index f35c8b642b8..00000000000 --- a/xml/FrameworksIndex/xamarinandroid-7.1.xml +++ /dev/null @@ -1,44815 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/xml/FrameworksIndex/xamarinios-10.8.xml b/xml/FrameworksIndex/xamarinios-10.8.xml deleted file mode 100644 index e909d328352..00000000000 --- a/xml/FrameworksIndex/xamarinios-10.8.xml +++ /dev/null @@ -1,43421 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/xml/FrameworksIndex/xamarinmac-3.0.xml b/xml/FrameworksIndex/xamarinmac-3.0.xml deleted file mode 100644 index 7bcc8cdcb48..00000000000 --- a/xml/FrameworksIndex/xamarinmac-3.0.xml +++ /dev/null @@ -1,53832 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/xml/Microsoft.CSharp.RuntimeBinder/RuntimeBinderException.xml b/xml/Microsoft.CSharp.RuntimeBinder/RuntimeBinderException.xml index dcd83ecc529..f9cf590ca7c 100644 --- a/xml/Microsoft.CSharp.RuntimeBinder/RuntimeBinderException.xml +++ b/xml/Microsoft.CSharp.RuntimeBinder/RuntimeBinderException.xml @@ -37,11 +37,11 @@ Represents an error that occurs when a dynamic bind in the C# runtime binder is processed. - in that represents a failure to bind in the sense of a usual compiler error, whereas represents a malfunctioning of the runtime binder itself. - + in that represents a failure to bind in the sense of a usual compiler error, whereas represents a malfunctioning of the runtime binder itself. + ]]> @@ -82,18 +82,18 @@ Initializes a new instance of the class. - property of the new instance to a system-supplied message that describes the error, such as "DefaultMessageDisplayedByParameterlessCtorWriterMustSupply" This message takes into account the current system culture. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||`null`.| -||The localized error message string.| - + property of the new instance to a system-supplied message that describes the error, such as "DefaultMessageDisplayedByParameterlessCtorWriterMustSupply" This message takes into account the current system culture. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||`null`.| +||The localized error message string.| + ]]> Handling and Throwing Exceptions @@ -130,16 +130,16 @@ The message that describes the exception. The caller of this constructor is required to ensure that this string has been localized for the current system culture. Initializes a new instance of the class that has a specified error message. - . - -|Property|Value| -|--------------|-----------| -||`null`.| -||The error message string specified in `message`.| - + . + +|Property|Value| +|--------------|-----------| +||`null`.| +||The error message string specified in `message`.| + ]]> Handling and Throwing Exceptions @@ -181,19 +181,19 @@ - - + + The object that holds the serialized object data about the exception being thrown. The contextual information about the source or destination. Initializes a new instance of the class that has serialized data. - @@ -231,18 +231,18 @@ The exception that is the cause of the current exception, or a null reference if no inner exception is specified. Initializes a new instance of the class that has a specified error message and a reference to the inner exception that is the cause of this exception. - property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||`null`.| -||The error message string specified in `message`.| - + property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||`null`.| +||The error message string specified in `message`.| + ]]> diff --git a/xml/Microsoft.CSharp.RuntimeBinder/RuntimeBinderInternalCompilerException.xml b/xml/Microsoft.CSharp.RuntimeBinder/RuntimeBinderInternalCompilerException.xml index 026d097664c..358ae00e71e 100644 --- a/xml/Microsoft.CSharp.RuntimeBinder/RuntimeBinderInternalCompilerException.xml +++ b/xml/Microsoft.CSharp.RuntimeBinder/RuntimeBinderInternalCompilerException.xml @@ -37,11 +37,11 @@ Represents an error that occurs when a dynamic bind in the C# runtime binder is processed. - in that represents a failure to bind in the sense of a usual compiler error, whereas represents a malfunctioning of the runtime binder itself. - + in that represents a failure to bind in the sense of a usual compiler error, whereas represents a malfunctioning of the runtime binder itself. + ]]> @@ -82,18 +82,18 @@ Initializes a new instance of the class with a system-supplied message that describes the error. - property of the new instance to a system-supplied message that describes the error, such as "DefaultMessageDisplayedByParameterlessCtorWriterMustSupply" This message takes into account the current system culture. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||`null`.| -||The localized error message string.| - + property of the new instance to a system-supplied message that describes the error, such as "DefaultMessageDisplayedByParameterlessCtorWriterMustSupply" This message takes into account the current system culture. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||`null`.| +||The localized error message string.| + ]]> Handling and Throwing Exceptions @@ -130,16 +130,16 @@ The message that describes the exception. The caller of this constructor is required to ensure that this string has been localized for the current system culture. Initializes a new instance of the class with a specified message that describes the error. - . - -|Property|Value| -|--------------|-----------| -||`null`.| -||The error message string specified in `message`.| - + . + +|Property|Value| +|--------------|-----------| +||`null`.| +||The error message string specified in `message`.| + ]]> Handling and Throwing Exceptions @@ -181,19 +181,19 @@ - - + + The that holds the serialized object data about the exception being thrown. The that contains contextual information about the source or destination. Initializes a new instance of the class with serialized data. - @@ -231,18 +231,18 @@ The exception that is the cause of the current exception, or a null reference if no inner exception is specified. Initializes a new instance of the class that has a specified error message and a reference to the inner exception that is the cause of this exception. - property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||`null`.| -||The error message string specified in `message`.| - + property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||`null`.| +||The error message string specified in `message`.| + ]]> diff --git a/xml/Microsoft.SqlServer.Server/InvalidUdtException.xml b/xml/Microsoft.SqlServer.Server/InvalidUdtException.xml index ceca65882ee..305e7390a76 100644 --- a/xml/Microsoft.SqlServer.Server/InvalidUdtException.xml +++ b/xml/Microsoft.SqlServer.Server/InvalidUdtException.xml @@ -58,19 +58,19 @@ System.Void - - + + The object. The object. Streams all the properties into the class for the given . - class to make the class serializable. - + class to make the class serializable. + ]]> diff --git a/xml/Microsoft.Win32.SafeHandles/SafeMemoryMappedFileHandle.xml b/xml/Microsoft.Win32.SafeHandles/SafeMemoryMappedFileHandle.xml index 574cab22d24..0583130547e 100644 --- a/xml/Microsoft.Win32.SafeHandles/SafeMemoryMappedFileHandle.xml +++ b/xml/Microsoft.Win32.SafeHandles/SafeMemoryMappedFileHandle.xml @@ -53,14 +53,14 @@ Provides a safe handle that represents a memory-mapped file for sequential access. - property to obtain the safe handle. - + property to obtain the safe handle. + > [!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. + ]]> @@ -88,36 +88,6 @@ To be added. - - - - - - - - Constructor - - System.Core - 2.0.5.0 - 4.0.0.0 - - - System.IO.MemoryMappedFiles - - - netstandard - - - - - - - To be added. - To be added. - To be added. - To be added. - - diff --git a/xml/System.Collections.Generic/Dictionary`2.xml b/xml/System.Collections.Generic/Dictionary`2.xml index 415fedbce72..681ac00d3c5 100644 --- a/xml/System.Collections.Generic/Dictionary`2.xml +++ b/xml/System.Collections.Generic/Dictionary`2.xml @@ -131,62 +131,62 @@ The type of the values in the dictionary. Represents a collection of keys and values. - generic class provides a mapping from a set of keys to a set of values. Each addition to the dictionary consists of a value and its associated key. Retrieving a value by using its key is very fast, close to O(1), because the class is implemented as a hash table. - + generic class provides a mapping from a set of keys to a set of values. Each addition to the dictionary consists of a value and its associated key. Retrieving a value by using its key is very fast, close to O(1), because the class is implemented as a hash table. + > [!NOTE] -> The speed of retrieval depends on the quality of the hashing algorithm of the type specified for `TKey`. - - As long as an object is used as a key in the , it must not change in any way that affects its hash value. Every key in a must be unique according to the dictionary's equality comparer. A key cannot be `null`, but a value can be, if its type `TValue` is a reference type. - - requires an equality implementation to determine whether keys are equal. You can specify an implementation of the generic interface by using a constructor that accepts a `comparer` parameter; if you do not specify an implementation, the default generic equality comparer is used. If type `TKey` implements the generic interface, the default equality comparer uses that implementation. - +> The speed of retrieval depends on the quality of the hashing algorithm of the type specified for `TKey`. + + As long as an object is used as a key in the , it must not change in any way that affects its hash value. Every key in a must be unique according to the dictionary's equality comparer. A key cannot be `null`, but a value can be, if its type `TValue` is a reference type. + + requires an equality implementation to determine whether keys are equal. You can specify an implementation of the generic interface by using a constructor that accepts a `comparer` parameter; if you do not specify an implementation, the default generic equality comparer is used. If type `TKey` implements the generic interface, the default equality comparer uses that implementation. + > [!NOTE] -> For example, you can use the case-insensitive string comparers provided by the class to create dictionaries with case-insensitive string keys. - - The capacity of a is the number of elements the can hold. As elements are added to a , the capacity is automatically increased as required by reallocating the internal array. - - **.NET Framework only:** For very large objects, you can increase the maximum capacity to 2 billion elements on a 64-bit system by setting the `enabled` attribute of the [``](/dotnet/framework/configure-apps/file-schema/runtime/gcallowverylargeobjects-element) configuration element to `true` in the run-time environment. - - For purposes of enumeration, each item in the dictionary is treated as a structure representing a value and its key. The order in which the items are returned is undefined. - - The `foreach` statement of the C# language (`for each` in C++, `For Each` in Visual Basic) returns an object of the type of the elements in the collection. Since the is a collection of keys and values, the element type is not the type of the key or the type of the value. Instead, the element type is a of the key type and the value type. For example: - +> For example, you can use the case-insensitive string comparers provided by the class to create dictionaries with case-insensitive string keys. + + The capacity of a is the number of elements the can hold. As elements are added to a , the capacity is automatically increased as required by reallocating the internal array. + + **.NET Framework only:** For very large objects, you can increase the maximum capacity to 2 billion elements on a 64-bit system by setting the `enabled` attribute of the [``](/dotnet/framework/configure-apps/file-schema/runtime/gcallowverylargeobjects-element) configuration element to `true` in the run-time environment. + + For purposes of enumeration, each item in the dictionary is treated as a structure representing a value and its key. The order in which the items are returned is undefined. + + The `foreach` statement of the C# language (`for each` in C++, `For Each` in Visual Basic) returns an object of the type of the elements in the collection. Since the is a collection of keys and values, the element type is not the type of the key or the type of the value. Instead, the element type is a of the key type and the value type. For example: + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Generic.Dictionary/cpp/source2.cpp" id="Snippet11"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/DictionaryTKey,TValue/Overview/source2.cs" id="Snippet11"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary/VB/source2.vb" id="Snippet11"::: - - The `foreach` statement is a wrapper around the enumerator, which allows only reading from the collection, not writing to it. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary/VB/source2.vb" id="Snippet11"::: + + The `foreach` statement is a wrapper around the enumerator, which allows only reading from the collection, not writing to it. + > [!NOTE] -> Because keys can be inherited and their behavior changed, their absolute uniqueness cannot be guaranteed by comparisons using the method. - - - -## Examples - - The following code example creates an empty of strings with string keys and uses the method to add some elements. The example demonstrates that the method throws an when attempting to add a duplicate key. - - The example uses the property (the indexer in C#) to retrieve values, demonstrating that a is thrown when a requested key is not present, and showing that the value associated with a key can be replaced. - - The example shows how to use the method as a more efficient way to retrieve values if a program often must try key values that are not in the dictionary, and it shows how to use the method to test whether a key exists before calling the method. - - The example shows how to enumerate the keys and values in the dictionary and how to enumerate the keys and values alone using the property and the property. - - Finally, the example demonstrates the method. - +> Because keys can be inherited and their behavior changed, their absolute uniqueness cannot be guaranteed by comparisons using the method. + + + +## Examples + + The following code example creates an empty of strings with string keys and uses the method to add some elements. The example demonstrates that the method throws an when attempting to add a duplicate key. + + The example uses the property (the indexer in C#) to retrieve values, demonstrating that a is thrown when a requested key is not present, and showing that the value associated with a key can be replaced. + + The example shows how to use the method as a more efficient way to retrieve values if a program often must try key values that are not in the dictionary, and it shows how to use the method to test whether a key exists before calling the method. + + The example shows how to enumerate the keys and values in the dictionary and how to enumerate the keys and values alone using the property and the property. + + Finally, the example demonstrates the method. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Generic.Dictionary/cpp/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/DictionaryTKey,TValue/Overview/source.cs" interactive="try-dotnet-method" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary/VB/source.vb" id="Snippet1"::: + ]]> - A can support multiple readers concurrently, as long as the collection is not modified. Even so, enumerating through a collection is intrinsically not a thread-safe procedure. In the rare case where an enumeration contends with write accesses, the collection must be locked during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - - For thread-safe alternatives, see the class or class. - + A can support multiple readers concurrently, as long as the collection is not modified. Even so, enumerating through a collection is intrinsically not a thread-safe procedure. In the rare case where an enumeration contends with write accesses, the collection must be locked during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. + + For thread-safe alternatives, see the class or class. + Public static ( in Visual Basic) members of this type are thread safe. @@ -240,30 +240,30 @@ Initializes a new instance of the class that is empty, has the default initial capacity, and uses the default equality comparer for the key type. - must be unique according to the default equality comparer. - - requires an equality implementation to determine whether keys are equal. This constructor uses the default generic equality comparer, . If type `TKey` implements the generic interface, the default equality comparer uses that implementation. Alternatively, you can specify an implementation of the generic interface by using a constructor that accepts a `comparer` parameter. - + must be unique according to the default equality comparer. + + requires an equality implementation to determine whether keys are equal. This constructor uses the default generic equality comparer, . If type `TKey` implements the generic interface, the default equality comparer uses that implementation. Alternatively, you can specify an implementation of the generic interface by using a constructor that accepts a `comparer` parameter. + > [!NOTE] -> If you can estimate the size of the collection, using a constructor that specifies the initial capacity eliminates the need to perform a number of resizing operations while adding elements to the . - - This constructor is an O(1) operation. - - - -## Examples - - The following code example creates an empty of strings with string keys and uses the method to add some elements. The example demonstrates that the method throws an when attempting to add a duplicate key. - - This code example is part of a larger example provided for the class. - +> If you can estimate the size of the collection, using a constructor that specifies the initial capacity eliminates the need to perform a number of resizing operations while adding elements to the . + + This constructor is an O(1) operation. + + + +## Examples + + The following code example creates an empty of strings with string keys and uses the method to add some elements. The example demonstrates that the method throws an when attempting to add a duplicate key. + + This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Generic.Dictionary/cpp/source.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/DictionaryTKey,TValue/Overview/source.cs" interactive="try-dotnet-method" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary/VB/source.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary/VB/source.vb" id="Snippet2"::: + ]]> @@ -310,25 +310,25 @@ The whose elements are copied to the new . Initializes a new instance of the class that contains elements copied from the specified and uses the default equality comparer for the key type. - must be unique according to the default equality comparer; likewise, every key in the source `dictionary` must also be unique according to the default equality comparer. - - The initial capacity of the new is large enough to contain all the elements in `dictionary`. - - requires an equality implementation to determine whether keys are equal. This constructor uses the default generic equality comparer, . If type `TKey` implements the generic interface, the default equality comparer uses that implementation. Alternatively, you can specify an implementation of the generic interface by using a constructor that accepts a `comparer` parameter. - - This constructor is an O(n) operation, where n is the number of elements in `dictionary`. - - - -## Examples - The following code example shows how to use the constructor to initialize a with sorted content from another dictionary. The code example creates a and populates it with data in random order, then passes the to the constructor, creating a that is sorted. This is useful if you need to build a sorted dictionary that at some point becomes static; copying the data from a to a improves retrieval speed. - + must be unique according to the default equality comparer; likewise, every key in the source `dictionary` must also be unique according to the default equality comparer. + + The initial capacity of the new is large enough to contain all the elements in `dictionary`. + + requires an equality implementation to determine whether keys are equal. This constructor uses the default generic equality comparer, . If type `TKey` implements the generic interface, the default equality comparer uses that implementation. Alternatively, you can specify an implementation of the generic interface by using a constructor that accepts a `comparer` parameter. + + This constructor is an O(n) operation, where n is the number of elements in `dictionary`. + + + +## Examples + The following code example shows how to use the constructor to initialize a with sorted content from another dictionary. The code example creates a and populates it with data in random order, then passes the to the constructor, creating a that is sorted. This is useful if you need to build a sorted dictionary that at some point becomes static; copying the data from a to a improves retrieval speed. + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/DictionaryTKey,TValue/.ctor/source.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary.ctor_IDic/VB/source.vb" id="Snippet1"::: - + ]]> @@ -433,28 +433,28 @@ The implementation to use when comparing keys, or to use the default for the type of the key. Initializes a new instance of the class that is empty, has the default initial capacity, and uses the specified . - class to create dictionaries with case-insensitive string keys. - - Every key in a must be unique according to the specified comparer. - - requires an equality implementation to determine whether keys are equal. If `comparer` is `null`, this constructor uses the default generic equality comparer, . If type `TKey` implements the generic interface, the default equality comparer uses that implementation. - + class to create dictionaries with case-insensitive string keys. + + Every key in a must be unique according to the specified comparer. + + requires an equality implementation to determine whether keys are equal. If `comparer` is `null`, this constructor uses the default generic equality comparer, . If type `TKey` implements the generic interface, the default equality comparer uses that implementation. + > [!NOTE] -> If you can estimate the size of the collection, using a constructor that specifies the initial capacity eliminates the need to perform a number of resizing operations while adding elements to the . - - This constructor is an O(1) operation. - - - -## Examples - The following code example creates a with a case-insensitive equality comparer for the current culture. The example adds four elements, some with lower-case keys and some with upper-case keys. The example then attempts to add an element with a key that differs from an existing key only by case, catches the resulting exception, and displays an error message. Finally, the example displays the elements in the dictionary. - +> If you can estimate the size of the collection, using a constructor that specifies the initial capacity eliminates the need to perform a number of resizing operations while adding elements to the . + + This constructor is an O(1) operation. + + + +## Examples + The following code example creates a with a case-insensitive equality comparer for the current culture. The example adds four elements, some with lower-case keys and some with upper-case keys. The example then attempts to add an element with a key that differs from an existing key only by case, catches the resulting exception, and displays an error message. Finally, the example displays the elements in the dictionary. + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/DictionaryTKey,TValue/.ctor/source2.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary.ctor_IEqC/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary.ctor_IEqC/VB/source.vb" id="Snippet1"::: + ]]> @@ -501,27 +501,27 @@ The initial number of elements that the can contain. Initializes a new instance of the class that is empty, has the specified initial capacity, and uses the default equality comparer for the key type. - must be unique according to the default equality comparer. - - The capacity of a is the number of elements that can be added to the before resizing is necessary. As elements are added to a , the capacity is automatically increased as required by reallocating the internal array. - - If the size of the collection can be estimated, specifying the initial capacity eliminates the need to perform a number of resizing operations while adding elements to the . - - requires an equality implementation to determine whether keys are equal. This constructor uses the default generic equality comparer, . If type `TKey` implements the generic interface, the default equality comparer uses that implementation. Alternatively, you can specify an implementation of the generic interface by using a constructor that accepts a `comparer` parameter. - - This constructor is an O(1) operation. - - - -## Examples - The following code example creates a dictionary with an initial capacity of 4 and populates it with 4 entries. - + must be unique according to the default equality comparer. + + The capacity of a is the number of elements that can be added to the before resizing is necessary. As elements are added to a , the capacity is automatically increased as required by reallocating the internal array. + + If the size of the collection can be estimated, specifying the initial capacity eliminates the need to perform a number of resizing operations while adding elements to the . + + requires an equality implementation to determine whether keys are equal. This constructor uses the default generic equality comparer, . If type `TKey` implements the generic interface, the default equality comparer uses that implementation. Alternatively, you can specify an implementation of the generic interface by using a constructor that accepts a `comparer` parameter. + + This constructor is an O(1) operation. + + + +## Examples + The following code example creates a dictionary with an initial capacity of 4 and populates it with 4 entries. + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/DictionaryTKey,TValue/.ctor/source3.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary.ctor_Int32/VB/source.vb" id="Snippet1"::: - + ]]> @@ -579,33 +579,33 @@ The implementation to use when comparing keys, or to use the default for the type of the key. Initializes a new instance of the class that contains elements copied from the specified and uses the specified . - class to create dictionaries with case-insensitive string keys. - - Every key in a must be unique according to the specified comparer; likewise, every key in the source `dictionary` must also be unique according to the specified comparer. - + class to create dictionaries with case-insensitive string keys. + + Every key in a must be unique according to the specified comparer; likewise, every key in the source `dictionary` must also be unique according to the specified comparer. + > [!NOTE] -> For example, duplicate keys can occur if `comparer` is one of the case-insensitive string comparers provided by the class and `dictionary` does not use a case-insensitive comparer key. - - The initial capacity of the new is large enough to contain all the elements in `dictionary`. - - requires an equality implementation to determine whether keys are equal. If `comparer` is `null`, this constructor uses the default generic equality comparer, . If type `TKey` implements the generic interface, the default equality comparer uses that implementation. - - This constructor is an O(`n`) operation, where `n` is the number of elements in `dictionary`. - - - -## Examples - The following code example shows how to use the constructor to initialize a with case-insensitive sorted content from another dictionary. The code example creates a with a case-insensitive comparer and populates it with data in random order, then passes the to the constructor, along with a case-insensitive equality comparer, creating a that is sorted. This is useful if you need to build a sorted dictionary that at some point becomes static; copying the data from a to a improves retrieval speed. - +> For example, duplicate keys can occur if `comparer` is one of the case-insensitive string comparers provided by the class and `dictionary` does not use a case-insensitive comparer key. + + The initial capacity of the new is large enough to contain all the elements in `dictionary`. + + requires an equality implementation to determine whether keys are equal. If `comparer` is `null`, this constructor uses the default generic equality comparer, . If type `TKey` implements the generic interface, the default equality comparer uses that implementation. + + This constructor is an O(`n`) operation, where `n` is the number of elements in `dictionary`. + + + +## Examples + The following code example shows how to use the constructor to initialize a with case-insensitive sorted content from another dictionary. The code example creates a with a case-insensitive comparer and populates it with data in random order, then passes the to the constructor, along with a case-insensitive equality comparer, creating a that is sorted. This is useful if you need to build a sorted dictionary that at some point becomes static; copying the data from a to a improves retrieval speed. + > [!NOTE] -> When you create a new dictionary with a case-insensitive comparer and populate it with entries from a dictionary that uses a case-sensitive comparer, as in this example, an exception occurs if the input dictionary has keys that differ only by case. - +> When you create a new dictionary with a case-insensitive comparer and populate it with entries from a dictionary that uses a case-sensitive comparer, as in this example, an exception occurs if the input dictionary has keys that differ only by case. + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/DictionaryTKey,TValue/.ctor/source1.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary.ctor_IDicIEqC/VB/source.vb" id="Snippet1"::: - + ]]> @@ -723,29 +723,29 @@ The implementation to use when comparing keys, or to use the default for the type of the key. Initializes a new instance of the class that is empty, has the specified initial capacity, and uses the specified . - class to create dictionaries with case-insensitive string keys. - - Every key in a must be unique according to the specified comparer. - - The capacity of a is the number of elements that can be added to the before resizing is necessary. As elements are added to a , the capacity is automatically increased as required by reallocating the internal array. - - If the size of the collection can be estimated, specifying the initial capacity eliminates the need to perform a number of resizing operations while adding elements to the . - - requires an equality implementation to determine whether keys are equal. If `comparer` is `null`, this constructor uses the default generic equality comparer, . If type `TKey` implements the generic interface, the default equality comparer uses that implementation. - - This constructor is an O(1) operation. - - - -## Examples - The following code example creates a with an initial capacity of 5 and a case-insensitive equality comparer for the current culture. The example adds four elements, some with lower-case keys and some with upper-case keys. The example then attempts to add an element with a key that differs from an existing key only by case, catches the resulting exception, and displays an error message. Finally, the example displays the elements in the dictionary. - + class to create dictionaries with case-insensitive string keys. + + Every key in a must be unique according to the specified comparer. + + The capacity of a is the number of elements that can be added to the before resizing is necessary. As elements are added to a , the capacity is automatically increased as required by reallocating the internal array. + + If the size of the collection can be estimated, specifying the initial capacity eliminates the need to perform a number of resizing operations while adding elements to the . + + requires an equality implementation to determine whether keys are equal. If `comparer` is `null`, this constructor uses the default generic equality comparer, . If type `TKey` implements the generic interface, the default equality comparer uses that implementation. + + This constructor is an O(1) operation. + + + +## Examples + The following code example creates a with an initial capacity of 5 and a case-insensitive equality comparer for the current culture. The example adds four elements, some with lower-case keys and some with upper-case keys. The example then attempts to add an element with a key that differs from an existing key only by case, catches the resulting exception, and displays an error message. Finally, the example displays the elements in the dictionary. + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/DictionaryTKey,TValue/.ctor/source4.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary.ctor_Int32IEqC/VB/source.vb" id="Snippet1"::: - + ]]> @@ -796,19 +796,19 @@ - - + + A object containing the information required to serialize the . A structure containing the source and destination of the serialized stream associated with the . Initializes a new instance of the class with serialized data. - @@ -861,29 +861,29 @@ The value of the element to add. The value can be for reference types. Adds the specified key and value to the dictionary. - property to add new elements by setting the value of a key that does not exist in the ; for example, `myCollection[myKey] = myValue` (in Visual Basic, `myCollection(myKey) = myValue`). However, if the specified key already exists in the , setting the property overwrites the old value. In contrast, the method throws an exception if a value with the specified key already exists. - - If the property value already equals the capacity, the capacity of the is increased by automatically reallocating the internal array, and the existing elements are copied to the new array before the new element is added. - - A key cannot be `null`, but a value can be, if `TValue` is a reference type. - - If is less than the capacity, this method approaches an O(1) operation. If the capacity must be increased to accommodate the new element, this method becomes an O(`n`) operation, where `n` is . - - - -## Examples - - The following code example creates an empty of strings with string keys and uses the method to add some elements. The example demonstrates that the method throws an when attempting to add a duplicate key. - - This code example is part of a larger example provided for the class. - + property to add new elements by setting the value of a key that does not exist in the ; for example, `myCollection[myKey] = myValue` (in Visual Basic, `myCollection(myKey) = myValue`). However, if the specified key already exists in the , setting the property overwrites the old value. In contrast, the method throws an exception if a value with the specified key already exists. + + If the property value already equals the capacity, the capacity of the is increased by automatically reallocating the internal array, and the existing elements are copied to the new array before the new element is added. + + A key cannot be `null`, but a value can be, if `TValue` is a reference type. + + If is less than the capacity, this method approaches an O(1) operation. If the capacity must be increased to accommodate the new element, this method becomes an O(`n`) operation, where `n` is . + + + +## Examples + + The following code example creates an empty of strings with string keys and uses the method to add some elements. The example demonstrates that the method throws an when attempting to add a duplicate key. + + This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Generic.Dictionary/cpp/source.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/DictionaryTKey,TValue/Overview/source.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary/VB/source.vb" id="Snippet2"::: - + ]]> @@ -964,15 +964,15 @@ Removes all keys and values from the . - property is set to 0, and references to other objects from elements of the collection are also released. The capacity remains unchanged. - - This method is an O(`n`) operation, where `n` is the capacity of the dictionary. + property is set to 0, and references to other objects from elements of the collection are also released. The capacity remains unchanged. + + This method is an O(`n`) operation, where `n` is the capacity of the dictionary. .NET Core 3.0+ only: this mutating method may be safely called without invalidating active enumerators on the instance. This does not imply thread safety. - + ]]> @@ -1016,13 +1016,13 @@ Gets the that is used to determine equality of keys for the dictionary. The generic interface implementation that is used to determine equality of keys for the current and to provide hash values for the keys. - requires an equality implementation to determine whether keys are equal. You can specify an implementation of the generic interface by using a constructor that accepts a `comparer` parameter; if you do not specify one, the default generic equality comparer is used. - - Getting the value of this property is an O(1) operation. - + requires an equality implementation to determine whether keys are equal. You can specify an implementation of the generic interface by using a constructor that accepts a `comparer` parameter; if you do not specify one, the default generic equality comparer is used. + + Getting the value of this property is an O(1) operation. + ]]> @@ -1075,28 +1075,28 @@ if the contains an element with the specified key; otherwise, . - method to test whether a key exists prior to calling the method. It also shows how to use the method to retrieve values, which is an efficient way to retrieve values when a program frequently tries keys that are not in the dictionary. Finally, it shows the least efficient way to test whether keys exist, by using the property (the indexer in C#). - - This code example is part of a larger example provided for the class (`openWith` is the name of the Dictionary used in this example). - + method to test whether a key exists prior to calling the method. It also shows how to use the method to retrieve values, which is an efficient way to retrieve values when a program frequently tries keys that are not in the dictionary. Finally, it shows the least efficient way to test whether keys exist, by using the property (the indexer in C#). + + This code example is part of a larger example provided for the class (`openWith` is the name of the Dictionary used in this example). + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Generic.Dictionary/cpp/source.cpp" id="Snippet6"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/DictionaryTKey,TValue/Overview/source.cs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary/VB/source.vb" id="Snippet6"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary/VB/source.vb" id="Snippet6"::: :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Generic.Dictionary/cpp/source.cpp" id="Snippet5"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/DictionaryTKey,TValue/Overview/source.cs" id="Snippet5"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary/VB/source.vb" id="Snippet5"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary/VB/source.vb" id="Snippet5"::: :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Generic.Dictionary/cpp/source.cpp" id="Snippet4"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/DictionaryTKey,TValue/Overview/source.cs" id="Snippet4"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary/VB/source.vb" id="Snippet4"::: - +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary/VB/source.vb" id="Snippet4"::: + ]]> @@ -1148,13 +1148,13 @@ if the contains an element with the specified value; otherwise, . - for `TValue`, the type of values in the dictionary. - - This method performs a linear search; therefore, the average execution time is proportional to . That is, this method is an O(`n`) operation, where `n` is . - + for `TValue`, the type of values in the dictionary. + + This method performs a linear search; therefore, the average execution time is proportional to . That is, this method is an O(`n`) operation, where `n` is . + ]]> @@ -1205,15 +1205,15 @@ Gets the number of key/value pairs contained in the . The number of key/value pairs contained in the . - is the number of elements that the can store. The property is the number of elements that are actually in the . - - The capacity is always greater than or equal to . If exceeds the capacity while adding elements, the capacity is increased by automatically reallocating the internal array before copying the old elements and adding the new elements. - - Getting the value of this property is an O(1) operation. - + is the number of elements that the can store. The property is the number of elements that are actually in the . + + The capacity is always greater than or equal to . If exceeds the capacity while adding elements, the capacity is increased by automatically reallocating the internal array before copying the old elements and adding the new elements. + + Getting the value of this property is an O(1) operation. + ]]> @@ -1298,31 +1298,31 @@ Returns an enumerator that iterates through the . A structure for the . - structure representing a value and its key. - - The `foreach` statement of the C# language (`for each` in C++, `For Each` in Visual Basic) hides the complexity of enumerators. Therefore, using `foreach` is recommended, instead of directly manipulating the enumerator. - - 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. At this position, is undefined. You must call the method to advance the enumerator to the first element of the collection before reading the value of . - - The property returns the same element until the method 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. You cannot set to the first element of the collection again; you must create a new enumerator instance instead. - + structure representing a value and its key. + + The `foreach` statement of the C# language (`for each` in C++, `For Each` in Visual Basic) hides the complexity of enumerators. Therefore, using `foreach` is recommended, instead of directly manipulating the enumerator. + + 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. At this position, is undefined. You must call the method to advance the enumerator to the first element of the collection before reading the value of . + + The property returns the same element until the method 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. You cannot set to the first element of the collection again; you must create a new enumerator instance instead. + An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding elements or changing the capacity, the enumerator is irrecoverably invalidated and the next call to or throws an . .NET Core 3.0+ only: The only mutating methods which do not invalidate enumerators are and . - - The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - - Default implementations of collections in the namespace are not synchronized. - - This method is an O(1) operation. - + + The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. + + Default implementations of collections in the namespace are not synchronized. + + This method is an O(1) operation. + ]]> @@ -1380,19 +1380,19 @@ System.Void - - + + A object that contains the information required to serialize the instance. A structure that contains the source and destination of the serialized stream associated with the instance. Implements the interface and returns the data needed to serialize the instance. - . - + . + ]]> @@ -1449,42 +1449,42 @@ Gets or sets the value associated with the specified key. The value associated with the specified key. If the specified key is not found, a get operation throws a , and a set operation creates a new element with the specified key. - property to add new elements by setting the value of a key that does not exist in the . When you set the property value, if the key is in the , the value associated with that key is replaced by the assigned value. If the key is not in the , the key and value are added to the dictionary. In contrast, the method does not modify existing elements. - - A key cannot be `null`, but a value can be, if the value type `TValue` is a reference type. - - The C# language uses the [`this`](/dotnet/csharp/language-reference/keywords/this) keyword to define the indexers instead of implementing the property. Visual Basic implements as a default property, which provides the same indexing functionality. - - Getting or setting the value of this property approaches an O(1) operation. - - - -## Examples - - The following code example uses the property (the indexer in C#) to retrieve values, demonstrating that a is thrown when a requested key is not present, and showing that the value associated with a key can be replaced. - - The example also shows how to use the method as a more efficient way to retrieve values if a program often must try key values that are not in the dictionary. - - This code example is part of a larger example provided for the class. `openWith` is the name of the Dictionary used in this example. - + property to add new elements by setting the value of a key that does not exist in the . When you set the property value, if the key is in the , the value associated with that key is replaced by the assigned value. If the key is not in the , the key and value are added to the dictionary. In contrast, the method does not modify existing elements. + + A key cannot be `null`, but a value can be, if the value type `TValue` is a reference type. + + The C# language uses the [`this`](/dotnet/csharp/language-reference/keywords/this) keyword to define the indexers instead of implementing the property. Visual Basic implements as a default property, which provides the same indexing functionality. + + Getting or setting the value of this property approaches an O(1) operation. + + + +## Examples + + The following code example uses the property (the indexer in C#) to retrieve values, demonstrating that a is thrown when a requested key is not present, and showing that the value associated with a key can be replaced. + + The example also shows how to use the method as a more efficient way to retrieve values if a program often must try key values that are not in the dictionary. + + This code example is part of a larger example provided for the class. `openWith` is the name of the Dictionary used in this example. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Generic.Dictionary/cpp/source.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/DictionaryTKey,TValue/Overview/source.cs" interactive="try-dotnet-method" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary/VB/source.vb" id="Snippet2"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary/VB/source.vb" id="Snippet2"::: :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Generic.Dictionary/cpp/source.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/DictionaryTKey,TValue/Overview/source.cs" id="Snippet3"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary/VB/source.vb" id="Snippet3"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary/VB/source.vb" id="Snippet3"::: :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Generic.Dictionary/cpp/source.cpp" id="Snippet4"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/DictionaryTKey,TValue/Overview/source.cs" id="Snippet4"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary/VB/source.vb" id="Snippet4"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary/VB/source.vb" id="Snippet4"::: :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Generic.Dictionary/cpp/source.cpp" id="Snippet5"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/DictionaryTKey,TValue/Overview/source.cs" id="Snippet5"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary/VB/source.vb" id="Snippet5"::: - +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary/VB/source.vb" id="Snippet5"::: + ]]> @@ -1532,29 +1532,29 @@ Gets a collection containing the keys in the . A containing the keys in the . - is unspecified, but it is the same order as the associated values in the returned by the property. - - The returned is not a static copy; instead, the refers back to the keys in the original . Therefore, changes to the continue to be reflected in the . - - Getting the value of this property is an O(1) operation. - - - -## Examples - The following code example shows how to enumerate the keys in the dictionary using the property, and how to enumerate the keys and values in the dictionary. - - This code is part of a larger example that can be compiled and executed (`openWith` is the name of the Dictionary used in this example). See . - + is unspecified, but it is the same order as the associated values in the returned by the property. + + The returned is not a static copy; instead, the refers back to the keys in the original . Therefore, changes to the continue to be reflected in the . + + Getting the value of this property is an O(1) operation. + + + +## Examples + The following code example shows how to enumerate the keys in the dictionary using the property, and how to enumerate the keys and values in the dictionary. + + This code is part of a larger example that can be compiled and executed (`openWith` is the name of the Dictionary used in this example). See . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Generic.Dictionary/cpp/source.cpp" id="Snippet9"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/DictionaryTKey,TValue/Overview/source.cs" id="Snippet9"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary/VB/source.vb" id="Snippet9"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary/VB/source.vb" id="Snippet9"::: :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Generic.Dictionary/cpp/source.cpp" id="Snippet7"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/DictionaryTKey,TValue/Overview/source.cs" id="Snippet7"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary/VB/source.vb" id="Snippet7"::: - +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary/VB/source.vb" id="Snippet7"::: + ]]> @@ -1605,17 +1605,17 @@ System.Void - + The source of the deserialization event. Implements the interface and raises the deserialization event when the deserialization is complete. - . - + . + ]]> The object associated with the current instance is invalid. @@ -1672,24 +1672,24 @@ if the element is successfully found and removed; otherwise, . This method returns if is not found in the . - does not contain an element with the specified key, the remains unchanged. No exception is thrown. - - This method approaches an O(1) operation. - + does not contain an element with the specified key, the remains unchanged. No exception is thrown. + + This method approaches an O(1) operation. + .NET Core 3.0+ only: this mutating method may be safely called without invalidating active enumerators on the instance. This does not imply thread safety. - -## Examples - The following code example shows how to remove a key/value pair from a dictionary using the method. - - This code example is part of a larger example provided for the class (`openWith` is the name of the Dictionary used in this example). - + +## Examples + The following code example shows how to remove a key/value pair from a dictionary using the method. + + This code example is part of a larger example provided for the class (`openWith` is the name of the Dictionary used in this example). + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Generic.Dictionary/cpp/source.cpp" id="Snippet10"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/DictionaryTKey,TValue/Overview/source.cs" id="Snippet10"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary/VB/source.vb" id="Snippet10"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary/VB/source.vb" id="Snippet10"::: + ]]> @@ -2261,16 +2261,16 @@ The zero-based index in at which copying begins. Copies the elements of the to an array, starting at the specified array index. - is a structure representing a value and its key. - + is a structure representing a value and its key. + > [!NOTE] -> If the type of the source cannot be cast automatically to the type of the destination `array`, the nongeneric implementations of throw an , whereas the generic implementations throw an . - - This method is an O(`n`) operation, where `n` is . - +> If the type of the source cannot be cast automatically to the type of the destination `array`, the nongeneric implementations of throw an , whereas the generic implementations throw an . + + This method is an O(`n`) operation, where `n` is . + ]]> @@ -2278,18 +2278,18 @@ is less than 0. - is multidimensional. - - -or- - - does not have zero-based indexing. - - -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- + + does not have zero-based indexing. + + -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 . @@ -2336,17 +2336,17 @@ if access to the is synchronized (thread safe); otherwise, . In the default implementation of , this property always returns . - namespace are not synchronized. - - 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 can cause 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 property returns an object that can be used to synchronize access to the . Synchronization is effective only if all threads lock the object before accessing the collection. - - Getting the value of this property is an O(1) operation. - + namespace are not synchronized. + + 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 can cause 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 property returns an object that can be used to synchronize access to the . Synchronization is effective only if all threads lock the object before accessing the collection. + + Getting the value of this property is an O(1) operation. + ]]> @@ -2394,42 +2394,42 @@ Gets an object that can be used to synchronize access to the . An object that can be used to synchronize access to the . - namespace are not synchronized. - - Enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - - The property returns an object that can be used to synchronize access to the . Synchronization is effective only if all threads lock the object before accessing the collection. The following code shows the use of the property for C#, C++, and Visual Basic. - -```csharp -ICollection ic = ...; -lock (ic.SyncRoot) { - // Access the collection. -} -``` - -```vb -Dim ic As ICollection = ... -SyncLock ic.SyncRoot - ' Access the collection. -End SyncLock -``` - -```cpp -ICollection^ ic = ...; -try { - Monitor::Enter(ic->SyncRoot); - // Access the collection. -} -finally { - Monitor::Exit(ic->SyncRoot); -} -``` - - Getting the value of this property is an O(1) operation. - + namespace are not synchronized. + + Enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. + + The property returns an object that can be used to synchronize access to the . Synchronization is effective only if all threads lock the object before accessing the collection. The following code shows the use of the property for C#, C++, and Visual Basic. + +```csharp +ICollection ic = ...; +lock (ic.SyncRoot) { + // Access the collection. +} +``` + +```vb +Dim ic As ICollection = ... +SyncLock ic.SyncRoot + ' Access the collection. +End SyncLock +``` + +```cpp +ICollection^ ic = ...; +try { + Monitor::Enter(ic->SyncRoot); + // Access the collection. +} +finally { + Monitor::Exit(ic->SyncRoot); +} +``` + + Getting the value of this property is an O(1) operation. + ]]> @@ -2482,36 +2482,36 @@ finally { The object to use as the value. Adds the specified key and value to the dictionary. - 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 throws an exception if the specified key already exists. - - If is less than the capacity, this method approaches an O(1) operation. If the capacity needs to be increased to accommodate the new element, this method becomes an O(`n`) operation, where `n` is . - - - -## Examples - The following code example shows how to access the class through the interface. The code example creates an empty of strings with string keys and uses the method to add some elements. The example demonstrates that the method throws an when attempting to add a duplicate key, or when a key or value of the wrong data type is supplied. - - The code example demonstrates the use of several other members of the interface. - + 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 throws an exception if the specified key already exists. + + If is less than the capacity, this method approaches an O(1) operation. If the capacity needs to be increased to accommodate the new element, this method becomes an O(`n`) operation, where `n` is . + + + +## Examples + The following code example shows how to access the class through the interface. The code example creates an empty of strings with string keys and uses the method to add some elements. The example demonstrates that the method throws an when attempting to add a duplicate key, or when a key or value of the wrong data type is supplied. + + The code example demonstrates the use of several other members of the interface. + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/DictionaryTKey,TValue/System.Collections.IDictionary.Add/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary.IDictionary/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary.IDictionary/VB/source.vb" id="Snippet1"::: + ]]> is . - is of a type that is not assignable to the key type of the . - - -or- - - is of a type that is not assignable to , the type of values in the . - - -or- - + is of a type that is not assignable to the key type of the . + + -or- + + is of a type that is not assignable to , the type of values in the . + + -or- + A value with the same key already exists in the . @@ -2563,27 +2563,27 @@ finally { if the contains an element with the specified key; otherwise, . - . - - This method approaches an O(1) operation. - - - -## Examples - The following code example shows how to use the method of the interface with a . The example demonstrates that the method returns `false` if a key of the wrong data type is supplied. - - The code example is part of a larger example, including output, provided for the method. - + . + + This method approaches an O(1) operation. + + + +## Examples + The following code example shows how to use the method of the interface with a . The example demonstrates that the method returns `false` if a key of the wrong data type is supplied. + + The code example is part of a larger example, including output, provided for the method. + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/DictionaryTKey,TValue/System.Collections.IDictionary.Add/source.cs" id="Snippet31"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary.IDictionary/VB/source.vb" id="Snippet31"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary.IDictionary/VB/source.vb" id="Snippet31"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/DictionaryTKey,TValue/System.Collections.IDictionary.Add/source.cs" id="Snippet6"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary.IDictionary/VB/source.vb" id="Snippet6"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary.IDictionary/VB/source.vb" id="Snippet6"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/DictionaryTKey,TValue/System.Collections.IDictionary.Add/source.cs" id="Snippet32"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary.IDictionary/VB/source.vb" id="Snippet32"::: - +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary.IDictionary/VB/source.vb" id="Snippet32"::: + ]]> @@ -2633,45 +2633,45 @@ finally { Returns an for the . An for the . - structure. - - The `foreach` statement of the C# language (`for each` in C++, `For Each` in Visual Basic) hides the complexity of enumerators. Therefore, using `foreach` is recommended, instead of directly manipulating the enumerator. - - 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, is undefined. Therefore, you must call the method to advance the enumerator to the first element of the collection before reading the value of . - - The property returns the same element until either the or method 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 . - + structure. + + The `foreach` statement of the C# language (`for each` in C++, `For Each` in Visual Basic) hides the complexity of enumerators. Therefore, using `foreach` is recommended, instead of directly manipulating the enumerator. + + 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, is undefined. Therefore, you must call the method to advance the enumerator to the first element of the collection before reading the value of . + + The property returns the same element until either the or method 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 . + An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding elements or changing the capacity, the enumerator is irrecoverably invalidated and the next call to or throws an . .NET Core 3.0+ only: The only mutating methods which do not invalidate enumerators are and . - - The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - - Default implementations of collections in the namespace are not synchronized. - - This method is an O(1) operation. - - - -## Examples - The following code example shows how to enumerate the key/value pairs in the dictionary by using the `foreach` statement (`For Each` in Visual Basic, `for each` in C++), which hides the use of the enumerator. In particular, note that the enumerator for the interface returns objects rather than objects. - - The code example is part of a larger example, including output, provided for the method. - + + The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. + + Default implementations of collections in the namespace are not synchronized. + + This method is an O(1) operation. + + + +## Examples + The following code example shows how to enumerate the key/value pairs in the dictionary by using the `foreach` statement (`For Each` in Visual Basic, `for each` in C++), which hides the use of the enumerator. In particular, note that the enumerator for the interface returns objects rather than objects. + + The code example is part of a larger example, including output, provided for the method. + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/DictionaryTKey,TValue/System.Collections.IDictionary.Add/source.cs" id="Snippet31"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary.IDictionary/VB/source.vb" id="Snippet31"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary.IDictionary/VB/source.vb" id="Snippet31"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/DictionaryTKey,TValue/System.Collections.IDictionary.Add/source.cs" id="Snippet7"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary.IDictionary/VB/source.vb" id="Snippet7"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary.IDictionary/VB/source.vb" id="Snippet7"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/DictionaryTKey,TValue/System.Collections.IDictionary.Add/source.cs" id="Snippet32"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary.IDictionary/VB/source.vb" id="Snippet32"::: - +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary.IDictionary/VB/source.vb" id="Snippet32"::: + ]]> @@ -2721,15 +2721,15 @@ finally { if the has a fixed size; otherwise, . In the default implementation of , this property always returns . - @@ -2777,15 +2777,15 @@ finally { if the is read-only; otherwise, . In the default implementation of , this property always returns . - @@ -2843,43 +2843,43 @@ finally { Gets or sets the value with the specified key. The value associated with the specified key, or if is not in the dictionary or is of a type that is not assignable to the key type of 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. - - The C# language uses the [this](/dotnet/csharp/language-reference/keywords/this) keyword to define the indexers instead of implementing the property. Visual Basic implements as a default property, which provides the same indexing functionality. - - Getting or setting the value of this property approaches an O(1) operation. - - - -## Examples - The following code example shows how to use the property (the indexer in C#) of the interface with a , and ways the property differs from the property. - - The example shows that, like the property, the property can change the value associated with an existing key and can be used to add a new key/value pair if the specified key is not in the dictionary. The example also shows that unlike the property, the property does not throw an exception if `key` is not in the dictionary, returning a null reference instead. Finally, the example demonstrates that getting the property returns a null reference if `key` is not the correct data type, and that setting the property throws an exception if `key` is not the correct data type. - - The code example is part of a larger example, including output, provided for the method. - + 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. + + The C# language uses the [this](/dotnet/csharp/language-reference/keywords/this) keyword to define the indexers instead of implementing the property. Visual Basic implements as a default property, which provides the same indexing functionality. + + Getting or setting the value of this property approaches an O(1) operation. + + + +## Examples + The following code example shows how to use the property (the indexer in C#) of the interface with a , and ways the property differs from the property. + + The example shows that, like the property, the property can change the value associated with an existing key and can be used to add a new key/value pair if the specified key is not in the dictionary. The example also shows that unlike the property, the property does not throw an exception if `key` is not in the dictionary, returning a null reference instead. Finally, the example demonstrates that getting the property returns a null reference if `key` is not the correct data type, and that setting the property throws an exception if `key` is not the correct data type. + + The code example is part of a larger example, including output, provided for the method. + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/DictionaryTKey,TValue/System.Collections.IDictionary.Add/source.cs" id="Snippet31"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary.IDictionary/VB/source.vb" id="Snippet31"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary.IDictionary/VB/source.vb" id="Snippet31"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/DictionaryTKey,TValue/System.Collections.IDictionary.Add/source.cs" id="Snippet3"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary.IDictionary/VB/source.vb" id="Snippet3"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary.IDictionary/VB/source.vb" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/DictionaryTKey,TValue/System.Collections.IDictionary.Add/source.cs" id="Snippet4"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary.IDictionary/VB/source.vb" id="Snippet4"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary.IDictionary/VB/source.vb" id="Snippet4"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/DictionaryTKey,TValue/System.Collections.IDictionary.Add/source.cs" id="Snippet32"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary.IDictionary/VB/source.vb" id="Snippet32"::: - +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary.IDictionary/VB/source.vb" id="Snippet32"::: + ]]> is . - A value is being assigned, and is of a type that is not assignable to the key type of the . - - -or- - + A value is being assigned, and is of a type that is not assignable to the key type of the . + + -or- + A value is being assigned, and is of a type that is not assignable to the value type of the . @@ -2926,29 +2926,29 @@ finally { Gets an containing the keys of the . An containing the keys of the . - is unspecified, but it is guaranteed to be the same order as the corresponding values in the returned by the property. - - Getting the value of this property is an O(1) operation. - - - -## Examples - The following code example shows how to use the property of the interface with a , to list the keys in the dictionary. The example also shows how to enumerate the key/value pairs in the dictionary; note that the enumerator for the interface returns objects rather than objects. - - The code example is part of a larger example, including output, provided for the method. - + is unspecified, but it is guaranteed to be the same order as the corresponding values in the returned by the property. + + Getting the value of this property is an O(1) operation. + + + +## Examples + The following code example shows how to use the property of the interface with a , to list the keys in the dictionary. The example also shows how to enumerate the key/value pairs in the dictionary; note that the enumerator for the interface returns objects rather than objects. + + The code example is part of a larger example, including output, provided for the method. + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/DictionaryTKey,TValue/System.Collections.IDictionary.Add/source.cs" id="Snippet31"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary.IDictionary/VB/source.vb" id="Snippet31"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary.IDictionary/VB/source.vb" id="Snippet31"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/DictionaryTKey,TValue/System.Collections.IDictionary.Add/source.cs" id="Snippet9"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary.IDictionary/VB/source.vb" id="Snippet9"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary.IDictionary/VB/source.vb" id="Snippet9"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/DictionaryTKey,TValue/System.Collections.IDictionary.Add/source.cs" id="Snippet7"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary.IDictionary/VB/source.vb" id="Snippet7"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary.IDictionary/VB/source.vb" id="Snippet7"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/DictionaryTKey,TValue/System.Collections.IDictionary.Add/source.cs" id="Snippet32"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary.IDictionary/VB/source.vb" id="Snippet32"::: - +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary.IDictionary/VB/source.vb" id="Snippet32"::: + ]]> @@ -2999,25 +2999,25 @@ finally { The key of the element to remove. Removes the element with the specified key from the . - of the interface with a . - - The code example is part of a larger example, including output, provided for the method. - + of the interface with a . + + The code example is part of a larger example, including output, provided for the method. + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/DictionaryTKey,TValue/System.Collections.IDictionary.Add/source.cs" id="Snippet31"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary.IDictionary/VB/source.vb" id="Snippet31"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary.IDictionary/VB/source.vb" id="Snippet31"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/DictionaryTKey,TValue/System.Collections.IDictionary.Add/source.cs" id="Snippet10"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary.IDictionary/VB/source.vb" id="Snippet10"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary.IDictionary/VB/source.vb" id="Snippet10"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/DictionaryTKey,TValue/System.Collections.IDictionary.Add/source.cs" id="Snippet32"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary.IDictionary/VB/source.vb" id="Snippet32"::: - +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary.IDictionary/VB/source.vb" id="Snippet32"::: + ]]> @@ -3066,29 +3066,29 @@ finally { Gets an containing the values in the . An containing the values in the . - is unspecified, but it is guaranteed to be the same order as the corresponding keys in the returned by the property. - - Getting the value of this property is an O(1) operation. - - - -## Examples - The following code example shows how to use the property of the interface with a , to list the values in the dictionary. The example also shows how to enumerate the key/value pairs in the dictionary; note that the enumerator for the interface returns objects rather than objects. - - The code example is part of a larger example, including output, provided for the method. - + is unspecified, but it is guaranteed to be the same order as the corresponding keys in the returned by the property. + + Getting the value of this property is an O(1) operation. + + + +## Examples + The following code example shows how to use the property of the interface with a , to list the values in the dictionary. The example also shows how to enumerate the key/value pairs in the dictionary; note that the enumerator for the interface returns objects rather than objects. + + The code example is part of a larger example, including output, provided for the method. + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/DictionaryTKey,TValue/System.Collections.IDictionary.Add/source.cs" id="Snippet31"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary.IDictionary/VB/source.vb" id="Snippet31"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary.IDictionary/VB/source.vb" id="Snippet31"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/DictionaryTKey,TValue/System.Collections.IDictionary.Add/source.cs" id="Snippet8"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary.IDictionary/VB/source.vb" id="Snippet8"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary.IDictionary/VB/source.vb" id="Snippet8"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/DictionaryTKey,TValue/System.Collections.IDictionary.Add/source.cs" id="Snippet7"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary.IDictionary/VB/source.vb" id="Snippet7"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary.IDictionary/VB/source.vb" id="Snippet7"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/DictionaryTKey,TValue/System.Collections.IDictionary.Add/source.cs" id="Snippet32"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary.IDictionary/VB/source.vb" id="Snippet32"::: - +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary.IDictionary/VB/source.vb" id="Snippet32"::: + ]]> @@ -3137,30 +3137,30 @@ finally { Returns an enumerator that iterates through the collection. An that can be used to iterate through the collection. - 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 . - - The property returns the same element until either the or method 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 . - + 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 . + + The property returns the same element until either the or method 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 . + An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding elements or changing the capacity, the enumerator is irrecoverably invalidated and the next call to or throws an . .NET Core 3.0+ only: The only mutating methods which do not invalidate enumerators are and . - - The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - - Default implementations of collections in the namespace are not synchronized. - - This method is an O(1) operation. - + + The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. + + Default implementations of collections in the namespace are not synchronized. + + This method is an O(1) operation. + ]]> @@ -3198,7 +3198,7 @@ finally { Sets the capacity of this dictionary to what it would be if it had been originally initialized with all its entries. - if the key/value pair was added to the dictionary successfully; otherwise, . - method, this method doesn't throw an exception if the element with the given key exists in the dictionary. Unlike the Dictionary indexer, `TryAdd` doesn't override the element if the element with the given key exists in the dictionary. If the key already exists, `TryAdd` does nothing and returns `false`. @@ -3359,31 +3359,31 @@ Unlike the method, this if the contains an element with the specified key; otherwise, . - method and the property. - - If the key is not found, then the `value` parameter gets the appropriate default value for the type `TValue`; for example, 0 (zero) for integer types, `false` for Boolean types, and `null` for reference types. - - Use the method if your code frequently attempts to access keys that are not in the dictionary. Using this method is more efficient than catching the thrown by the property. - - This method approaches an O(1) operation. - - - -## Examples - The example shows how to use the method as a more efficient way to retrieve values in a program that frequently tries keys that are not in the dictionary. For contrast, the example also shows how the property (the indexer in C#) throws exceptions when attempting to retrieve nonexistent keys. - - This code example is part of a larger example provided for the class (`openWith` is the name of the Dictionary used in this example). - + method and the property. + + If the key is not found, then the `value` parameter gets the appropriate default value for the type `TValue`; for example, 0 (zero) for integer types, `false` for Boolean types, and `null` for reference types. + + Use the method if your code frequently attempts to access keys that are not in the dictionary. Using this method is more efficient than catching the thrown by the property. + + This method approaches an O(1) operation. + + + +## Examples + The example shows how to use the method as a more efficient way to retrieve values in a program that frequently tries keys that are not in the dictionary. For contrast, the example also shows how the property (the indexer in C#) throws exceptions when attempting to retrieve nonexistent keys. + + This code example is part of a larger example provided for the class (`openWith` is the name of the Dictionary used in this example). + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Generic.Dictionary/cpp/source.cpp" id="Snippet5"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/DictionaryTKey,TValue/Overview/source.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary/VB/source.vb" id="Snippet5"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary/VB/source.vb" id="Snippet5"::: :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Generic.Dictionary/cpp/source.cpp" id="Snippet4"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/DictionaryTKey,TValue/Overview/source.cs" id="Snippet4"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary/VB/source.vb" id="Snippet4"::: - +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary/VB/source.vb" id="Snippet4"::: + ]]> @@ -3431,29 +3431,29 @@ Unlike the method, this Gets a collection containing the values in the . A containing the values in the . - is unspecified, but it is the same order as the associated keys in the returned by the property. - - The returned is not a static copy; instead, the refers back to the values in the original . Therefore, changes to the continue to be reflected in the . - - Getting the value of this property is an O(1) operation. - - - -## Examples - This code example shows how to enumerate the values in the dictionary using the property, and how to enumerate the keys and values in the dictionary. - - This code example is part of a larger example provided for the class (`openWith` is the name of the Dictionary used in this example). - + is unspecified, but it is the same order as the associated keys in the returned by the property. + + The returned is not a static copy; instead, the refers back to the values in the original . Therefore, changes to the continue to be reflected in the . + + Getting the value of this property is an O(1) operation. + + + +## Examples + This code example shows how to enumerate the values in the dictionary using the property, and how to enumerate the keys and values in the dictionary. + + This code example is part of a larger example provided for the class (`openWith` is the name of the Dictionary used in this example). + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Generic.Dictionary/cpp/source.cpp" id="Snippet8"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/DictionaryTKey,TValue/Overview/source.cs" id="Snippet8"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary/VB/source.vb" id="Snippet8"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary/VB/source.vb" id="Snippet8"::: :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Generic.Dictionary/cpp/source.cpp" id="Snippet7"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/DictionaryTKey,TValue/Overview/source.cs" id="Snippet7"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary/VB/source.vb" id="Snippet7"::: - +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary/VB/source.vb" id="Snippet7"::: + ]]> diff --git a/xml/System.Collections.Generic/HashSet`1.xml b/xml/System.Collections.Generic/HashSet`1.xml index be5cc1530b9..509af9003b5 100644 --- a/xml/System.Collections.Generic/HashSet`1.xml +++ b/xml/System.Collections.Generic/HashSet`1.xml @@ -540,8 +540,8 @@ The following example demonstrates how to merge two disparate sets. This example - - + + A object that contains the information required to serialize the object. @@ -1378,8 +1378,8 @@ The following example demonstrates how to merge two disparate sets. This example System.Void - - + + A object that contains the information required to serialize the object. @@ -1820,7 +1820,7 @@ The following example demonstrates how to merge two disparate sets. This example System.Void - + The source of the deserialization event. diff --git a/xml/System.Collections.Generic/KeyNotFoundException.xml b/xml/System.Collections.Generic/KeyNotFoundException.xml index 00be10196ad..5bd58e7d422 100644 --- a/xml/System.Collections.Generic/KeyNotFoundException.xml +++ b/xml/System.Collections.Generic/KeyNotFoundException.xml @@ -77,15 +77,15 @@ The exception that is thrown when the key specified for accessing an element in a collection does not match any key in the collection. - is thrown when an operation attempts to retrieve an element from a collection using a key that does not exist in that collection. - - uses the HRESULT COR_E_KEYNOTFOUND, which has the value 0x80131577. - - For a list of initial property values for an instance of the class, see the constructors. - + is thrown when an operation attempts to retrieve an element from a collection using a key that does not exist in that collection. + + uses the HRESULT COR_E_KEYNOTFOUND, which has the value 0x80131577. + + For a list of initial property values for an instance of the class, see the constructors. + ]]> @@ -140,18 +140,18 @@ Initializes a new instance of the class using default property values. - property of the new instance to a system-supplied message that describes the error, such as "The given key was not present in the dictionary." This message takes into account the current system culture. - - The following table shows the initial property values for an instance of the class. - -|Property|Value| -|--------------|-----------| -||`null`.| -||The localized error message string.| - + property of the new instance to a system-supplied message that describes the error, such as "The given key was not present in the dictionary." This message takes into account the current system culture. + + The following table shows the initial property values for an instance of the class. + +|Property|Value| +|--------------|-----------| +||`null`.| +||The localized error message string.| + ]]> @@ -198,18 +198,18 @@ The message that describes the error. Initializes a new instance of the class with the specified error message. - class. - -|Property|Value| -|--------------|-----------| -||`null`.| -||The localized error message string.| - + class. + +|Property|Value| +|--------------|-----------| +||`null`.| +||The localized error message string.| + ]]> @@ -263,19 +263,19 @@ - - + + The that holds the serialized object data about the exception being thrown. The that contains contextual information about the source or destination. Initializes a new instance of the class with serialized data. - @@ -324,18 +324,18 @@ The exception that is the cause of the current exception. If the parameter is not , the current exception is raised in a block that handles the inner exception. Initializes a new instance of the class with the specified error message and a reference to the inner exception that is the cause of this exception. - property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. - - The following table shows the initial property values for an instance of the class. - -|Property|Value| -|--------------|-----------| -||The inner exception reference.| -||The localized error message string.| - + property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. + + The following table shows the initial property values for an instance of the class. + +|Property|Value| +|--------------|-----------| +||The inner exception reference.| +||The localized error message string.| + ]]> diff --git a/xml/System.Collections.Generic/LinkedList`1+Enumerator.xml b/xml/System.Collections.Generic/LinkedList`1+Enumerator.xml index 61c74382b15..ac7996835f4 100644 --- a/xml/System.Collections.Generic/LinkedList`1+Enumerator.xml +++ b/xml/System.Collections.Generic/LinkedList`1+Enumerator.xml @@ -87,25 +87,25 @@ Enumerates the elements of a . - 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 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. You cannot set to the first element of the collection again; you must create a new enumerator instance instead. - - 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 enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - - Default implementations of collections in are not synchronized. - + 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 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. You cannot set to the first element of the collection again; you must create a new enumerator instance instead. + + 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 enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. + + Default implementations of collections in are not synchronized. + ]]> @@ -168,19 +168,19 @@ Gets the element at the current position of the enumerator. The element in the at the current position of the enumerator. - is undefined under any of the following conditions: - -- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. - + is undefined under any of the following conditions: + +- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. + - The last call to returned `false`, which indicates the end of the collection and that the enumerator is positioned after the last element of the collection. - The enumerator is invalidated due to changes made in the collection, such as adding, modifying, or deleting elements. - does not move the position of the enumerator, and consecutive calls to return the same object until either or is called. - + does not move the position of the enumerator, and consecutive calls to return the same object until either or is called. + ]]> @@ -275,15 +275,15 @@ if the enumerator was successfully advanced to the next element; if the enumerator has passed the end of the collection. - advances the enumerator to the first element of the collection. - - 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`. - - 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 throws an . - + advances the enumerator to the first element of the collection. + + 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`. + + 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 throws an . + ]]> The collection was modified after the enumerator was created. @@ -339,19 +339,19 @@ Gets the element at the current position of the enumerator. The element in the collection at the current position of the enumerator. - is undefined under any of the following conditions: - -- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. - + is undefined under any of the following conditions: + +- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. + - The last call to returned `false`, which indicates the end of the collection and that the enumerator is positioned after the last element of the collection. - The enumerator is invalidated due to changes made in the collection, such as adding, modifying, or deleting elements. - does not move the position of the enumerator, and consecutive calls to return the same object until either or is called. - + does not move the position of the enumerator, and consecutive calls to return the same object until either or is called. + ]]> @@ -401,11 +401,11 @@ Sets the enumerator to its initial position, which is before the first element in the collection. This class cannot be inherited. - or throws an . - + or throws an . + ]]> The collection was modified after the enumerator was created. @@ -451,7 +451,7 @@ System.Void - + The source of the deserialization event. @@ -501,8 +501,8 @@ System.Void - - + + A object that contains the information required to serialize the instance. diff --git a/xml/System.Collections.Generic/LinkedList`1.xml b/xml/System.Collections.Generic/LinkedList`1.xml index 5e232459f75..52e3b2439b3 100644 --- a/xml/System.Collections.Generic/LinkedList`1.xml +++ b/xml/System.Collections.Generic/LinkedList`1.xml @@ -120,36 +120,36 @@ Specifies the element type of the linked list. Represents a doubly linked list. - is a general-purpose linked list. It supports enumerators and implements the interface, consistent with other collection classes in the .NET Framework. - - provides separate nodes of type , so insertion and removal are O(1) operations. - - You can remove nodes and reinsert them, either in the same list or in another list, which results in no additional objects allocated on the heap. Because the list also maintains an internal count, getting the property is an O(1) operation. - - Each node in a object is of the type . Because the is doubly linked, each node points forward to the node and backward to the node. - - Lists that contain reference types perform better when a node and its value are created at the same time. accepts `null` as a valid property for reference types and allows duplicate values. - - If the is empty, the and properties contain `null`. - - The class does not support chaining, splitting, cycles, or other features that can leave the list in an inconsistent state. The list remains consistent on a single thread. The only multithreaded scenario supported by is multithreaded read operations. - - - -## Examples - The following code example demonstrates many features of the class. - + is a general-purpose linked list. It supports enumerators and implements the interface, consistent with other collection classes in the .NET Framework. + + provides separate nodes of type , so insertion and removal are O(1) operations. + + You can remove nodes and reinsert them, either in the same list or in another list, which results in no additional objects allocated on the heap. Because the list also maintains an internal count, getting the property is an O(1) operation. + + Each node in a object is of the type . Because the is doubly linked, each node points forward to the node and backward to the node. + + Lists that contain reference types perform better when a node and its value are created at the same time. accepts `null` as a valid property for reference types and allows duplicate values. + + If the is empty, the and properties contain `null`. + + The class does not support chaining, splitting, cycles, or other features that can leave the list in an inconsistent state. The list remains consistent on a single thread. The only multithreaded scenario supported by is multithreaded read operations. + + + +## Examples + The following code example demonstrates many features of the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Generic.LinkedList/cpp/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/LinkedListT/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.LinkedList/vb/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Generic.LinkedList/vb/source.vb" id="Snippet1"::: + ]]> - This type is not thread safe. If the needs to be accessed by multiple threads, you will need to implement your own synchronization mechanism. - + This type is not thread safe. If the needs to be accessed by multiple threads, you will need to implement your own synchronization mechanism. + A can support multiple readers concurrently, as long as the collection is not modified. Even so, enumerating through a collection is intrinsically not a thread-safe procedure. In the rare case where an enumeration contends with write accesses, the collection must be locked during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. @@ -206,24 +206,24 @@ Initializes a new instance of the class that is empty. - accepts `null` as a valid for reference types and allows duplicate values. - - If the is empty, the and properties contain `null`. - - This constructor is an O(1) operation. - - - -## Examples - The following code example creates and initializes a of type , adds several nodes, and then displays its contents. - + accepts `null` as a valid for reference types and allows duplicate values. + + If the is empty, the and properties contain `null`. + + This constructor is an O(1) operation. + + + +## Examples + The following code example creates and initializes a of type , adds several nodes, and then displays its contents. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Collections.Generic.LinkedList.ctor/CPP/llctor.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/LinkedListT/.ctor/llctor.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Generic.LinkedList.ctor/VB/llctor.vb" id="Snippet1"::: - + ]]> @@ -267,20 +267,20 @@ The whose elements are copied to the new . Initializes a new instance of the class that contains elements copied from the specified and has sufficient capacity to accommodate the number of elements copied. - accepts `null` as a valid for reference types and allows duplicate values. - - If `collection` has no elements then the new is empty, and the and properties contain `null`. - - This constructor is an O(n) operation, where `n` is the number of elements in `collection`. - - - -## Examples - For an example that includes this constructor, see the class. - + accepts `null` as a valid for reference types and allows duplicate values. + + If `collection` has no elements then the new is empty, and the and properties contain `null`. + + This constructor is an O(n) operation, where `n` is the number of elements in `collection`. + + + +## Examples + For an example that includes this constructor, see the class. + ]]> @@ -332,23 +332,23 @@ - - + + A object containing the information required to serialize the . A object containing the source and destination of the serialized stream associated with the . Initializes a new instance of the class that is serializable with the specified and . - accepts `null` as a valid for reference types and allows duplicate values. - - If the is empty, the and properties contain `null`. - - This constructor is an O(n) operation. - + accepts `null` as a valid for reference types and allows duplicate values. + + If the is empty, the and properties contain `null`. + + This constructor is an O(n) operation. + ]]> @@ -409,31 +409,31 @@ The new to add to the . Adds the specified new node after the specified existing node in the . - accepts `null` as a valid for reference types and allows duplicate values. - - This method is an O(1) operation. - - - -## Examples - For an example that includes this method, see the class. - + accepts `null` as a valid for reference types and allows duplicate values. + + This method is an O(1) operation. + + + +## Examples + For an example that includes this method, see the class. + ]]> - is . - - -or- - + is . + + -or- + is . - is not in the current . - - -or- - + is not in the current . + + -or- + belongs to another . @@ -486,18 +486,18 @@ Adds a new node containing the specified value after the specified existing node in the . The new containing . - accepts `null` as a valid for reference types and allows duplicate values. - - This method is an O(1) operation. - - - -## Examples - For an example that includes this method, see the class. - + accepts `null` as a valid for reference types and allows duplicate values. + + This method is an O(1) operation. + + + +## Examples + For an example that includes this method, see the class. + ]]> @@ -565,31 +565,31 @@ The new to add to the . Adds the specified new node before the specified existing node in the . - accepts `null` as a valid for reference types and allows duplicate values. - - This method is an O(1) operation. - - - -## Examples - For an example that includes this method, see the class. - + accepts `null` as a valid for reference types and allows duplicate values. + + This method is an O(1) operation. + + + +## Examples + For an example that includes this method, see the class. + ]]> - is . - - -or- - + is . + + -or- + is . - is not in the current . - - -or- - + is not in the current . + + -or- + belongs to another . @@ -642,18 +642,18 @@ Adds a new node containing the specified value before the specified existing node in the . The new containing . - accepts `null` as a valid for reference types and allows duplicate values. - - This method is an O(1) operation. - - - -## Examples - For an example that includes this method, see the class. - + accepts `null` as a valid for reference types and allows duplicate values. + + This method is an O(1) operation. + + + +## Examples + For an example that includes this method, see the class. + ]]> @@ -719,20 +719,20 @@ The new to add at the start of the . Adds the specified new node at the start of the . - accepts `null` as a valid for reference types and allows duplicate values. - - If the is empty, the new node becomes the and the . - - This method is an O(1) operation. - - - -## Examples - For an example that includes this method, see the class. - + accepts `null` as a valid for reference types and allows duplicate values. + + If the is empty, the new node becomes the and the . + + This method is an O(1) operation. + + + +## Examples + For an example that includes this method, see the class. + ]]> @@ -788,20 +788,20 @@ Adds a new node containing the specified value at the start of the . The new containing . - accepts `null` as a valid for reference types and allows duplicate values. - - If the is empty, the new node becomes the and the . - - This method is an O(1) operation. - - - -## Examples - For an example that includes this method, see the class. - + accepts `null` as a valid for reference types and allows duplicate values. + + If the is empty, the new node becomes the and the . + + This method is an O(1) operation. + + + +## Examples + For an example that includes this method, see the class. + ]]> @@ -863,20 +863,20 @@ The new to add at the end of the . Adds the specified new node at the end of the . - accepts `null` as a valid for reference types and allows duplicate values. - - If the is empty, the new node becomes the and the . - - This method is an O(1) operation. - - - -## Examples - For an example that includes this method, see the class. - + accepts `null` as a valid for reference types and allows duplicate values. + + If the is empty, the new node becomes the and the . + + This method is an O(1) operation. + + + +## Examples + For an example that includes this method, see the class. + ]]> @@ -932,20 +932,20 @@ Adds a new node containing the specified value at the end of the . The new containing . - accepts `null` as a valid for reference types and allows duplicate values. - - If the is empty, the new node becomes the and the . - - This method is an O(1) operation. - - - -## Examples - For an example that includes this method, see the class. - + accepts `null` as a valid for reference types and allows duplicate values. + + If the is empty, the new node becomes the and the . + + This method is an O(1) operation. + + + +## Examples + For an example that includes this method, see the class. + ]]> @@ -996,18 +996,18 @@ Removes all nodes from the . - is set to zero, and references to other objects from elements of the collection are also released. and are set to `null`. - - This method is an O(`n`) operation, where `n` is . - - - -## Examples - For an example that includes this method, see the class. - + is set to zero, and references to other objects from elements of the collection are also released. and are set to `null`. + + This method is an O(`n`) operation, where `n` is . + + + +## Examples + For an example that includes this method, see the class. + ]]> @@ -1062,16 +1062,16 @@ if is found in the ; otherwise, . - . - - - -## Examples - For an example that includes this method, see the class. - + . + + + +## Examples + For an example that includes this method, see the class. + ]]> @@ -1126,18 +1126,18 @@ The zero-based index in at which copying begins. Copies the entire to a compatible one-dimensional , starting at the specified index of the target array. - in the same order in which the enumerator iterates through the . - - This method is an O(`n`) operation, where `n` is . - - - -## Examples - For an example that includes this method, see the class. - + in the same order in which the enumerator iterates through the . + + This method is an O(`n`) operation, where `n` is . + + + +## Examples + For an example that includes this method, see the class. + ]]> @@ -1197,16 +1197,16 @@ Gets the number of nodes actually contained in the . The number of nodes actually contained in the . - class. - + class. + ]]> @@ -1255,18 +1255,18 @@ Finds the first node that contains the specified value. The first that contains the specified value, if found; otherwise, . - is searched forward starting at and ending at . - - This method performs a linear search; therefore, this method is an O(`n`) operation, where `n` is . - - - -## Examples - For an example that includes this method, see the class. - + is searched forward starting at and ending at . + + This method performs a linear search; therefore, this method is an O(`n`) operation, where `n` is . + + + +## Examples + For an example that includes this method, see the class. + ]]> @@ -1318,18 +1318,18 @@ Finds the last node that contains the specified value. The last that contains the specified value, if found; otherwise, . - is searched backward starting at and ending at . - - This method performs a linear search; therefore, this method is an O(`n`) operation, where `n` is . - - - -## Examples - For an example that includes this method, see the class. - + is searched backward starting at and ending at . + + This method performs a linear search; therefore, this method is an O(`n`) operation, where `n` is . + + + +## Examples + For an example that includes this method, see the class. + ]]> @@ -1387,20 +1387,20 @@ Gets the first node of the . The first of the . - accepts `null` as a valid for reference types and allows duplicate values. - - If the is empty, the and properties contain `null`. - - Retrieving the value of this property is an O(1) operation. - - - -## Examples - For an example that includes this property, see the class. - + accepts `null` as a valid for reference types and allows duplicate values. + + If the is empty, the and properties contain `null`. + + Retrieving the value of this property is an O(1) operation. + + + +## Examples + For an example that includes this property, see the class. + ]]> @@ -1445,27 +1445,27 @@ Returns an enumerator that iterates through the . An for the . - 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 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. You cannot set to the first element of the collection again; you must create a new enumerator instance instead. - - 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 enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - - Default implementations of collections in are not synchronized. - - This method is an O(1) operation. - + 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 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. You cannot set to the first element of the collection again; you must create a new enumerator instance instead. + + 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 enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. + + Default implementations of collections in are not synchronized. + + This method is an O(1) operation. + ]]> @@ -1519,19 +1519,19 @@ System.Void - - + + A object that contains the information required to serialize the instance. A object that contains the source and destination of the serialized stream associated with the instance. Implements the interface and returns the data needed to serialize the instance. - . - + . + ]]> @@ -1588,20 +1588,20 @@ Gets the last node of the . The last of the . - accepts `null` as a valid for reference types and allows duplicate values. - - If the is empty, the and properties contain `null`. - - Retrieving the value of this property is an O(1) operation. - - - -## Examples - For an example that includes this property, see the class. - + accepts `null` as a valid for reference types and allows duplicate values. + + If the is empty, the and properties contain `null`. + + Retrieving the value of this property is an O(1) operation. + + + +## Examples + For an example that includes this property, see the class. + ]]> @@ -1650,17 +1650,17 @@ System.Void - + The source of the deserialization event. Implements the interface and raises the deserialization event when the deserialization is complete. - . - + . + ]]> The object associated with the current instance is invalid. @@ -1723,16 +1723,16 @@ The to remove from the . Removes the specified node from the . - class. - + class. + ]]> @@ -1795,16 +1795,16 @@ if the element containing is successfully removed; otherwise, . This method also returns if was not found in the original . - . - - - -## Examples - For an example that includes this method, see the class. - + . + + + +## Examples + For an example that includes this method, see the class. + ]]> @@ -1855,16 +1855,16 @@ Removes the node at the start of the . - class. - + class. + ]]> The is empty. @@ -1913,16 +1913,16 @@ Removes the node at the end of the . - class. - + class. + ]]> The is empty. @@ -1977,20 +1977,20 @@ The value to add at the end of the . Adds an item at the end of the . - accepts `null` as a valid for reference types and allows duplicate values. - - If the is empty, the new node becomes the and the . - - This method is an O(1) operation. - - - -## Examples - For an example that includes this method, see the class. - + accepts `null` as a valid for reference types and allows duplicate values. + + If the is empty, the new node becomes the and the . + + This method is an O(1) operation. + + + +## Examples + For an example that includes this method, see the class. + ]]> @@ -2039,15 +2039,15 @@ if the is read-only; otherwise, . In the default implementation of , this property always returns . - @@ -2095,27 +2095,27 @@ Returns an enumerator that iterates through a collection. An that can be used to iterate through the collection. - 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 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. You cannot set to the first element of the collection again; you must create a new enumerator instance instead. - - 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 enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - - Default implementations of collections in are not synchronized. - - This method is an O(1) operation. - + 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 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. You cannot set to the first element of the collection again; you must create a new enumerator instance instead. + + 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 enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. + + Default implementations of collections in are not synchronized. + + This method is an O(1) operation. + ]]> @@ -2168,15 +2168,15 @@ The zero-based index in at which copying begins. Copies the elements of the to an , starting at a particular index. - [!NOTE] -> If the type of the source cannot be cast automatically to the type of the destination `array`, the non-generic implementations of throw , whereas the generic implementations throw . - - This method is an O(`n`) operation, where `n` is . - +> If the type of the source cannot be cast automatically to the type of the destination `array`, the non-generic implementations of throw , whereas the generic implementations throw . + + This method is an O(`n`) operation, where `n` is . + ]]> @@ -2184,18 +2184,18 @@ is less than zero. - is multidimensional. - - -or- - - does not have zero-based indexing. - - -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- + + does not have zero-based indexing. + + -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 . @@ -2242,17 +2242,17 @@ if access to the is synchronized (thread safe); otherwise, . In the default implementation of , this property always returns . - are not synchronized. - - Enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - - returns an object that can be used to synchronize access to the . Synchronization is effective only if all threads lock this object before accessing the collection. - - Retrieving the value of this property is an O(1) operation. - + are not synchronized. + + Enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. + + returns an object that can be used to synchronize access to the . Synchronization is effective only if all threads lock this object before accessing the collection. + + Retrieving the value of this property is an O(1) operation. + ]]> @@ -2300,42 +2300,42 @@ Gets an object that can be used to synchronize access to the . An object that can be used to synchronize access to the . In the default implementation of , this property always returns the current instance. - are not synchronized. - - Enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - - returns an object that can be used to synchronize access to the . Synchronization is effective only if all threads lock this object before accessing the collection. The following code shows the use of the property for C#, C++, and Visual Basic. - -```csharp -ICollection ic = ...; -lock (ic.SyncRoot) { - // Access the collection. -} -``` - -```vb -Dim ic As ICollection = ... -SyncLock ic.SyncRoot - ' Access the collection. -End SyncLock -``` - -```cpp -ICollection^ ic = ...; -try { - Monitor::Enter(ic->SyncRoot); - // Access the collection. -} -finally { - Monitor::Exit(ic->SyncRoot); -} -``` - - Retrieving the value of this property is an O(1) operation. - + are not synchronized. + + Enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. + + returns an object that can be used to synchronize access to the . Synchronization is effective only if all threads lock this object before accessing the collection. The following code shows the use of the property for C#, C++, and Visual Basic. + +```csharp +ICollection ic = ...; +lock (ic.SyncRoot) { + // Access the collection. +} +``` + +```vb +Dim ic As ICollection = ... +SyncLock ic.SyncRoot + ' Access the collection. +End SyncLock +``` + +```cpp +ICollection^ ic = ...; +try { + Monitor::Enter(ic->SyncRoot); + // Access the collection. +} +finally { + Monitor::Exit(ic->SyncRoot); +} +``` + + Retrieving the value of this property is an O(1) operation. + ]]> @@ -2384,27 +2384,27 @@ finally { Returns an enumerator that iterates through the linked list as a collection. An that can be used to iterate through the linked list as a collection. - also brings the enumerator back to this position. At this position, 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. - - 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 the next call to or throws an . - - The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - - Default implementations of collections in are not synchronized. - - This method is an O(1) operation. - + also brings the enumerator back to this position. At this position, 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. + + 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 the next call to or throws an . + + The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. + + Default implementations of collections in are not synchronized. + + This method is an O(1) operation. + ]]> diff --git a/xml/System.Collections.Generic/List`1.xml b/xml/System.Collections.Generic/List`1.xml index 8b6e5a8e8ee..de829efea0b 100644 --- a/xml/System.Collections.Generic/List`1.xml +++ b/xml/System.Collections.Generic/List`1.xml @@ -111,8 +111,8 @@ The type of elements in the list. Represents a strongly typed list of objects that can be accessed by index. Provides methods to search, sort, and manipulate lists. For more information about this API, see Supplemental API remarks for List<T>. - Public static ( in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe. - + Public static ( in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe. + It is safe to perform multiple read operations on a , but issues can occur if the collection is modified while it's being read. To ensure thread safety, lock the collection during a read or write operation. To enable a collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. For collections with built-in synchronization, see the classes in the namespace. For an inherently thread-safe alternative, see the class. @@ -173,28 +173,28 @@ Initializes a new instance of the class that is empty and has the default initial capacity. - is the number of elements that the can hold. As elements are added to a , the capacity is automatically increased as required by reallocating the internal array. - - If the size of the collection can be estimated, using the constructor and specifying the initial capacity eliminates the need to perform a number of resizing operations while adding elements to the . - - The capacity can be decreased by calling the method or by setting the property explicitly. Decreasing the capacity reallocates memory and copies all the elements in the . - - This constructor is an O(1) operation. - -## Examples - - The following example demonstrates the parameterless constructor of the generic class. The parameterless constructor creates a list with the default capacity, as demonstrated by displaying the property. - - The example adds, inserts, and removes items, showing how the capacity changes as these methods are used. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_Class/cpp/source.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Overview/source.cs" interactive="try-dotnet-method" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_Class/vb/source.vb" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR/List`1_Class/fs/listclass.fs" id="Snippet1"::: - + is the number of elements that the can hold. As elements are added to a , the capacity is automatically increased as required by reallocating the internal array. + + If the size of the collection can be estimated, using the constructor and specifying the initial capacity eliminates the need to perform a number of resizing operations while adding elements to the . + + The capacity can be decreased by calling the method or by setting the property explicitly. Decreasing the capacity reallocates memory and copies all the elements in the . + + This constructor is an O(1) operation. + +## Examples + + The following example demonstrates the parameterless constructor of the generic class. The parameterless constructor creates a list with the default capacity, as demonstrated by displaying the property. + + The example adds, inserts, and removes items, showing how the capacity changes as these methods are used. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_Class/cpp/source.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Overview/source.cs" interactive="try-dotnet-method" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_Class/vb/source.vb" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR/List`1_Class/fs/listclass.fs" id="Snippet1"::: + ]]> @@ -238,20 +238,20 @@ The collection whose elements are copied to the new list. Initializes a new instance of the class that contains elements copied from the specified collection and has sufficient capacity to accommodate the number of elements copied. - in the same order they are read by the enumerator of the collection. - - This constructor is an O(*n*) operation, where *n* is the number of elements in `collection`. - -## Examples - The following example demonstrates the constructor and various methods of the class that act on ranges. An array of strings is created and passed to the constructor, populating the list with the elements of the array. The property is then displayed, to show that the initial capacity is exactly what is required to hold the input elements. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_Ranges/cpp/source.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/.ctor/source1.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_Ranges/vb/source.vb" id="Snippet1"::: - + in the same order they are read by the enumerator of the collection. + + This constructor is an O(*n*) operation, where *n* is the number of elements in `collection`. + +## Examples + The following example demonstrates the constructor and various methods of the class that act on ranges. An array of strings is created and passed to the constructor, populating the list with the elements of the array. The property is then displayed, to show that the initial capacity is exactly what is required to hold the input elements. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_Ranges/cpp/source.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/.ctor/source1.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_Ranges/vb/source.vb" id="Snippet1"::: + ]]> @@ -305,24 +305,24 @@ The number of elements that the new list can initially store. Initializes a new instance of the class that is empty and has the specified initial capacity. - is the number of elements that the can hold. As elements are added to a , the capacity is automatically increased as required by reallocating the internal array. - - If the size of the collection can be estimated, specifying the initial capacity eliminates the need to perform a number of resizing operations while adding elements to the . - - The capacity can be decreased by calling the method or by setting the property explicitly. Decreasing the capacity reallocates memory and copies all the elements in the . - - This constructor is an O(1) operation. - -## Examples - The following example demonstrates the constructor. A of strings with a capacity of 4 is created, because the ultimate size of the list is known to be exactly 4. The list is populated with four strings, and a read-only copy is created by using the method. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_AsReadOnly/cpp/source.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/.ctor/source.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_AsReadOnly/vb/source.vb" id="Snippet1"::: - + is the number of elements that the can hold. As elements are added to a , the capacity is automatically increased as required by reallocating the internal array. + + If the size of the collection can be estimated, specifying the initial capacity eliminates the need to perform a number of resizing operations while adding elements to the . + + The capacity can be decreased by calling the method or by setting the property explicitly. Decreasing the capacity reallocates memory and copies all the elements in the . + + This constructor is an O(1) operation. + +## Examples + The following example demonstrates the constructor. A of strings with a capacity of 4 is created, because the ultimate size of the list is known to be exactly 4. The list is populated with four strings, and a read-only copy is created by using the method. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_AsReadOnly/cpp/source.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/.ctor/source.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_AsReadOnly/vb/source.vb" id="Snippet1"::: + ]]> @@ -375,32 +375,32 @@ The object to be added to the end of the . The value can be for reference types. Adds an object to the end of the . - accepts `null` as a valid value for reference types and allows duplicate elements. - - If already equals , the capacity of the is increased by automatically reallocating the internal array, and the existing elements are copied to the new array before the new element is added. - - If is less than , this method is an O(1) operation. If the capacity needs to be increased to accommodate the new element, this method becomes an O(*n*) operation, where *n* is . - -## Examples - - The following example demonstrates how to add, remove, and insert a simple business object in a . - - :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Overview/program.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.list.addremoveinsert/vb/module1.vb" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.collections.generic.list.addremoveinsert/fs/addremoveinsert.fs" id="Snippet1"::: - - The following example demonstrates several properties and methods of the generic class, including the method. The parameterless constructor is used to create a list of strings with a capacity of 0. The property is displayed, and then the method is used to add several items. The items are listed, and the property is displayed again, along with the property, to show that the capacity has been increased as needed. - - Other properties and methods are used to search for, insert, and remove elements from the list, and finally to clear the list. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_Class/cpp/source.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Overview/source.cs" interactive="try-dotnet-method" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_Class/vb/source.vb" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR/List`1_Class/fs/listclass.fs" id="Snippet1"::: - + accepts `null` as a valid value for reference types and allows duplicate elements. + + If already equals , the capacity of the is increased by automatically reallocating the internal array, and the existing elements are copied to the new array before the new element is added. + + If is less than , this method is an O(1) operation. If the capacity needs to be increased to accommodate the new element, this method becomes an O(*n*) operation, where *n* is . + +## Examples + + The following example demonstrates how to add, remove, and insert a simple business object in a . + + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Overview/program.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.list.addremoveinsert/vb/module1.vb" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.collections.generic.list.addremoveinsert/fs/addremoveinsert.fs" id="Snippet1"::: + + The following example demonstrates several properties and methods of the generic class, including the method. The parameterless constructor is used to create a list of strings with a capacity of 0. The property is displayed, and then the method is used to add several items. The items are listed, and the property is displayed again, along with the property, to show that the capacity has been increased as needed. + + Other properties and methods are used to search for, insert, and remove elements from the list, and finally to clear the list. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_Class/cpp/source.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Overview/source.cs" interactive="try-dotnet-method" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_Class/vb/source.vb" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR/List`1_Class/fs/listclass.fs" id="Snippet1"::: + ]]> @@ -451,22 +451,22 @@ The collection whose elements should be added to the end of the . The collection itself cannot be , but it can contain elements that are , if type is a reference type. Adds the elements of the specified collection to the end of the . - . - - If the new (the current plus the size of the collection) will be greater than , the capacity of the is increased by automatically reallocating the internal array to accommodate the new elements, and the existing elements are copied to the new array before the new elements are added. - - If the can accommodate the new elements without increasing the , this method is an O(*n*) operation, where *n* is the number of elements to be added. If the capacity needs to be increased to accommodate the new elements, this method becomes an O(*n* + *m*) operation, where *n* is the number of elements to be added and *m* is . - -## Examples - The following example demonstrates the method and various other methods of the class that act on ranges. An array of strings is created and passed to the constructor, populating the list with the elements of the array. The method is called, with the list as its argument. The result is that the current elements of the list are added to the end of the list, duplicating all the elements. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_Ranges/cpp/source.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/.ctor/source1.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_Ranges/vb/source.vb" id="Snippet1"::: - + . + + If the new (the current plus the size of the collection) will be greater than , the capacity of the is increased by automatically reallocating the internal array to accommodate the new elements, and the existing elements are copied to the new array before the new elements are added. + + If the can accommodate the new elements without increasing the , this method is an O(*n*) operation, where *n* is the number of elements to be added. If the capacity needs to be increased to accommodate the new elements, this method becomes an O(*n* + *m*) operation, where *n* is the number of elements to be added and *m* is . + +## Examples + The following example demonstrates the method and various other methods of the class that act on ranges. An array of strings is created and passed to the constructor, populating the list with the elements of the array. The method is called, with the list as its argument. The result is that the current elements of the list are added to the end of the list, duplicating all the elements. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_Ranges/cpp/source.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/.ctor/source1.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_Ranges/vb/source.vb" id="Snippet1"::: + ]]> @@ -519,22 +519,22 @@ Returns a read-only wrapper for the current collection. An object that acts as a read-only wrapper around the current . - object, expose it only through this wrapper. A object does not expose methods that modify the collection. However, if changes are made to the underlying object, the read-only collection reflects those changes. - - This method is an O(1) operation. - -## Examples - The following example demonstrates the method. A of strings with a capacity of 4 is created, because the ultimate size of the list is known to be exactly 4. The list is populated with four strings, and the method is used to get a read-only generic interface implementation that wraps the original list. - - An element of the original list is set to "Coelophysis" using the property (the indexer in C#), and the contents of the read-only list are displayed again to demonstrate that it is just a wrapper for the original list. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_AsReadOnly/cpp/source.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/.ctor/source.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_AsReadOnly/vb/source.vb" id="Snippet1"::: - + object, expose it only through this wrapper. A object does not expose methods that modify the collection. However, if changes are made to the underlying object, the read-only collection reflects those changes. + + This method is an O(1) operation. + +## Examples + The following example demonstrates the method. A of strings with a capacity of 4 is created, because the ultimate size of the list is known to be exactly 4. The list is populated with four strings, and the method is used to get a read-only generic interface implementation that wraps the original list. + + An element of the original list is set to "Coelophysis" using the property (the indexer in C#), and the contents of the read-only list are displayed again to demonstrate that it is just a wrapper for the original list. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_AsReadOnly/cpp/source.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/.ctor/source.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_AsReadOnly/vb/source.vb" id="Snippet1"::: + ]]> @@ -593,30 +593,30 @@ Searches the entire sorted for an element using the default comparer and returns the zero-based index of the element. The zero-based index of in the sorted , if is found; otherwise, a negative number that is the bitwise complement of the index of the next element that is larger than or, if there is no larger element, the bitwise complement of . - for type `T` to determine the order of list elements. The property checks whether type `T` implements the generic interface and uses that implementation, if available. If not, checks whether type `T` implements the interface. If type `T` does not implement either interface, throws an . - - The must already be sorted according to the comparer implementation; otherwise, the result is incorrect. - - Comparing `null` with any reference type is allowed and does not generate an exception when using the generic interface. When sorting, `null` is considered to be less than any other object. - - If the contains more than one element with the same value, the method returns only one of the occurrences, and it might return any one of the occurrences, not necessarily the first one. - - If the does not contain the specified value, the method returns a negative integer. You can apply the bitwise complement operation (~) to this negative integer to get the index of the first element that is larger than the search value. When inserting the value into the , this index should be used as the insertion point to maintain the sort order. - - This method is an O(log *n*) operation, where *n* is the number of elements in the range. - -## Examples - The following example demonstrates the method overload and the method overload. A of strings is created and populated with four strings, in no particular order. The list is displayed, sorted, and displayed again. - - The method overload is then used to search for two strings that are not in the list, and the method is used to insert them. The return value of the method is negative in each case, because the strings are not in the list. Taking the bitwise complement (the ~ operator in C# and Visual C++, `Xor` -1 in Visual Basic) of this negative number produces the index of the first element in the list that is larger than the search string, and inserting at this location preserves the sort order. The second search string is larger than any element in the list, so the insertion position is at the end of the list. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_SortSearch/cpp/source.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/BinarySearch/source.cs" interactive="try-dotnet-method" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_SortSearch/vb/source.vb" id="Snippet1"::: - + for type `T` to determine the order of list elements. The property checks whether type `T` implements the generic interface and uses that implementation, if available. If not, checks whether type `T` implements the interface. If type `T` does not implement either interface, throws an . + + The must already be sorted according to the comparer implementation; otherwise, the result is incorrect. + + Comparing `null` with any reference type is allowed and does not generate an exception when using the generic interface. When sorting, `null` is considered to be less than any other object. + + If the contains more than one element with the same value, the method returns only one of the occurrences, and it might return any one of the occurrences, not necessarily the first one. + + If the does not contain the specified value, the method returns a negative integer. You can apply the bitwise complement operation (~) to this negative integer to get the index of the first element that is larger than the search value. When inserting the value into the , this index should be used as the insertion point to maintain the sort order. + + This method is an O(log *n*) operation, where *n* is the number of elements in the range. + +## Examples + The following example demonstrates the method overload and the method overload. A of strings is created and populated with four strings, in no particular order. The list is displayed, sorted, and displayed again. + + The method overload is then used to search for two strings that are not in the list, and the method is used to insert them. The return value of the method is negative in each case, because the strings are not in the list. Taking the bitwise complement (the ~ operator in C# and Visual C++, `Xor` -1 in Visual Basic) of this negative number produces the index of the first element in the list that is larger than the search string, and inserting at this location preserves the sort order. The second search string is larger than any element in the list, so the insertion position is at the end of the list. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_SortSearch/cpp/source.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/BinarySearch/source.cs" interactive="try-dotnet-method" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_SortSearch/vb/source.vb" id="Snippet1"::: + ]]> The default comparer cannot find an implementation of the generic interface or the interface for type . @@ -672,46 +672,46 @@ The object to locate. The value can be for reference types. - The implementation to use when comparing elements. - - -or- - + The implementation to use when comparing elements. + + -or- + to use the default comparer . Searches the entire sorted for an element using the specified comparer and returns the zero-based index of the element. The zero-based index of in the sorted , if is found; otherwise, a negative number that is the bitwise complement of the index of the next element that is larger than or, if there is no larger element, the bitwise complement of . - instance as the comparer to perform case-insensitive string searches. - - If `comparer` is provided, the elements of the are compared to the specified value using the specified implementation. - - If `comparer` is `null`, the default comparer checks whether type `T` implements the generic interface and uses that implementation, if available. If not, checks whether type `T` implements the interface. If type `T` does not implement either interface, throws . - - The must already be sorted according to the comparer implementation; otherwise, the result is incorrect. - - Comparing `null` with any reference type is allowed and does not generate an exception when using the generic interface. When sorting, `null` is considered to be less than any other object. - - If the contains more than one element with the same value, the method returns only one of the occurrences, and it might return any one of the occurrences, not necessarily the first one. - - If the does not contain the specified value, the method returns a negative integer. You can apply the bitwise complement operation (~) to this negative integer to get the index of the first element that is larger than the search value. When inserting the value into the , this index should be used as the insertion point to maintain the sort order. - - This method is an O(log *n*) operation, where *n* is the number of elements in the range. - -## Examples - The following example demonstrates the method overload and the method overload. - - The example defines an alternative comparer for strings named DinoCompare, which implements the `IComparer` (`IComparer(Of String)` in Visual Basic, `IComparer` in Visual C++) generic interface. The comparer works as follows: First, the comparands are tested for `null`, and a null reference is treated as less than a non-null. Second, the string lengths are compared, and the longer string is deemed to be greater. Third, if the lengths are equal, ordinary string comparison is used. - - A of strings is created and populated with four strings, in no particular order. The list is displayed, sorted using the alternate comparer, and displayed again. - - The method overload is then used to search for several strings that are not in the list, employing the alternate comparer. The method is used to insert the strings. These two methods are located in the function named `SearchAndInsert`, along with code to take the bitwise complement (the ~ operator in C# and Visual C++, `Xor` -1 in Visual Basic) of the negative number returned by and use it as an index for inserting the new string. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_SortSearchComparer/cpp/source.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/BinarySearch/source1.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_SortSearchComparer/vb/source.vb" id="Snippet1"::: - + instance as the comparer to perform case-insensitive string searches. + + If `comparer` is provided, the elements of the are compared to the specified value using the specified implementation. + + If `comparer` is `null`, the default comparer checks whether type `T` implements the generic interface and uses that implementation, if available. If not, checks whether type `T` implements the interface. If type `T` does not implement either interface, throws . + + The must already be sorted according to the comparer implementation; otherwise, the result is incorrect. + + Comparing `null` with any reference type is allowed and does not generate an exception when using the generic interface. When sorting, `null` is considered to be less than any other object. + + If the contains more than one element with the same value, the method returns only one of the occurrences, and it might return any one of the occurrences, not necessarily the first one. + + If the does not contain the specified value, the method returns a negative integer. You can apply the bitwise complement operation (~) to this negative integer to get the index of the first element that is larger than the search value. When inserting the value into the , this index should be used as the insertion point to maintain the sort order. + + This method is an O(log *n*) operation, where *n* is the number of elements in the range. + +## Examples + The following example demonstrates the method overload and the method overload. + + The example defines an alternative comparer for strings named DinoCompare, which implements the `IComparer` (`IComparer(Of String)` in Visual Basic, `IComparer` in Visual C++) generic interface. The comparer works as follows: First, the comparands are tested for `null`, and a null reference is treated as less than a non-null. Second, the string lengths are compared, and the longer string is deemed to be greater. Third, if the lengths are equal, ordinary string comparison is used. + + A of strings is created and populated with four strings, in no particular order. The list is displayed, sorted using the alternate comparer, and displayed again. + + The method overload is then used to search for several strings that are not in the list, employing the alternate comparer. The method is used to insert the strings. These two methods are located in the function named `SearchAndInsert`, along with code to take the bitwise complement (the ~ operator in C# and Visual C++, `Xor` -1 in Visual Basic) of the negative number returned by and use it as an index for inserting the new string. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_SortSearchComparer/cpp/source.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/BinarySearch/source1.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_SortSearchComparer/vb/source.vb" id="Snippet1"::: + ]]> @@ -776,45 +776,45 @@ Searches a range of elements in the sorted for an element using the specified comparer and returns the zero-based index of the element. The zero-based index of in the sorted , if is found; otherwise, a negative number that is the bitwise complement of the index of the next element that is larger than or, if there is no larger element, the bitwise complement of . - instance as the comparer to perform case-insensitive string searches. - - If `comparer` is provided, the elements of the are compared to the specified value using the specified implementation. - - If `comparer` is `null`, the default comparer checks whether type `T` implements the generic interface and uses that implementation, if available. If not, checks whether type `T` implements the interface. If type `T` does not implement either interface, throws . - - The must already be sorted according to the comparer implementation; otherwise, the result is incorrect. - - Comparing `null` with any reference type is allowed and does not generate an exception when using the generic interface. When sorting, `null` is considered to be less than any other object. - - If the contains more than one element with the same value, the method returns only one of the occurrences, and it might return any one of the occurrences, not necessarily the first one. - - If the does not contain the specified value, the method returns a negative integer. You can apply the bitwise complement operation (~) to this negative integer to get the index of the first element that is larger than the search value. When inserting the value into the , this index should be used as the insertion point to maintain the sort order. - - This method is an O(log *n*) operation, where *n* is the number of elements in the range. - -## Examples - The following example demonstrates the method overload and the method overload. - - The example defines an alternative comparer for strings named DinoCompare, which implements the `IComparer` (`IComparer(Of String)` in Visual Basic, `IComparer` in Visual C++) generic interface. The comparer works as follows: First, the comparands are tested for `null`, and a null reference is treated as less than a non-null. Second, the string lengths are compared, and the longer string is deemed to be greater. Third, if the lengths are equal, ordinary string comparison is used. - - A of strings is created and populated with the names of five herbivorous dinosaurs and three carnivorous dinosaurs. Within each of the two groups, the names are not in any particular sort order. The list is displayed, the range of herbivores is sorted using the alternate comparer, and the list is displayed again. - - The method overload is then used to search only the range of herbivores for "Brachiosaurus". The string is not found, and the bitwise complement (the ~ operator in C# and Visual C++, `Xor` -1 in Visual Basic) of the negative number returned by the method is used as an index for inserting the new string. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_SortSearchComparerRange/cpp/source.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/BinarySearch/source2.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_SortSearchComparerRange/vb/source.vb" id="Snippet1"::: - + instance as the comparer to perform case-insensitive string searches. + + If `comparer` is provided, the elements of the are compared to the specified value using the specified implementation. + + If `comparer` is `null`, the default comparer checks whether type `T` implements the generic interface and uses that implementation, if available. If not, checks whether type `T` implements the interface. If type `T` does not implement either interface, throws . + + The must already be sorted according to the comparer implementation; otherwise, the result is incorrect. + + Comparing `null` with any reference type is allowed and does not generate an exception when using the generic interface. When sorting, `null` is considered to be less than any other object. + + If the contains more than one element with the same value, the method returns only one of the occurrences, and it might return any one of the occurrences, not necessarily the first one. + + If the does not contain the specified value, the method returns a negative integer. You can apply the bitwise complement operation (~) to this negative integer to get the index of the first element that is larger than the search value. When inserting the value into the , this index should be used as the insertion point to maintain the sort order. + + This method is an O(log *n*) operation, where *n* is the number of elements in the range. + +## Examples + The following example demonstrates the method overload and the method overload. + + The example defines an alternative comparer for strings named DinoCompare, which implements the `IComparer` (`IComparer(Of String)` in Visual Basic, `IComparer` in Visual C++) generic interface. The comparer works as follows: First, the comparands are tested for `null`, and a null reference is treated as less than a non-null. Second, the string lengths are compared, and the longer string is deemed to be greater. Third, if the lengths are equal, ordinary string comparison is used. + + A of strings is created and populated with the names of five herbivorous dinosaurs and three carnivorous dinosaurs. Within each of the two groups, the names are not in any particular sort order. The list is displayed, the range of herbivores is sorted using the alternate comparer, and the list is displayed again. + + The method overload is then used to search only the range of herbivores for "Brachiosaurus". The string is not found, and the bitwise complement (the ~ operator in C# and Visual C++, `Xor` -1 in Visual Basic) of the negative number returned by the method is used as an index for inserting the new string. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_SortSearchComparerRange/cpp/source.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/BinarySearch/source2.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_SortSearchComparerRange/vb/source.vb" id="Snippet1"::: + ]]> - is less than 0. - - -or- - + is less than 0. + + -or- + is less than 0. and do not denote a valid range in the . @@ -870,33 +870,33 @@ Gets or sets the total number of elements the internal data structure can hold without resizing. The number of elements that the can contain before resizing is required. - is the number of elements that the can store before resizing is required, whereas is the number of elements that are actually in the . - - is always greater than or equal to . If exceeds while adding elements, the capacity is increased by automatically reallocating the internal array before copying the old elements and adding the new elements. - - If the capacity is significantly larger than the count and you want to reduce the memory used by the , you can decrease capacity by calling the method or by setting the property explicitly to a lower value. When the value of is set explicitly, the internal array is also reallocated to accommodate the specified capacity, and all the elements are copied. - - Retrieving the value of this property is an O(1) operation; setting the property is an O(*n*) operation, where *n* is the new capacity. - -## Examples - - The following example demonstrates how to check the capacity and count of a that contains a simple business object, and illustrates using the method to remove extra capacity. - - :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Capacity/program.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.list.capacitycount/vb/module1.vb" id="Snippet1"::: - - The following example shows the property at several points in the life of a list. The parameterless constructor is used to create a list of strings with a capacity of 0, and the property is displayed to demonstrate this. After the method has been used to add several items, the items are listed, and then the property is displayed again, along with the property, to show that the capacity has been increased as needed. - - The property is displayed again after the method is used to reduce the capacity to match the count. Finally, the method is used to remove all items from the list, and the and properties are displayed again. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_Class/cpp/source.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Overview/source.cs" interactive="try-dotnet-method" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_Class/vb/source.vb" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR/List`1_Class/fs/listclass.fs" id="Snippet1"::: - + is the number of elements that the can store before resizing is required, whereas is the number of elements that are actually in the . + + is always greater than or equal to . If exceeds while adding elements, the capacity is increased by automatically reallocating the internal array before copying the old elements and adding the new elements. + + If the capacity is significantly larger than the count and you want to reduce the memory used by the , you can decrease capacity by calling the method or by setting the property explicitly to a lower value. When the value of is set explicitly, the internal array is also reallocated to accommodate the specified capacity, and all the elements are copied. + + Retrieving the value of this property is an O(1) operation; setting the property is an O(*n*) operation, where *n* is the new capacity. + +## Examples + + The following example demonstrates how to check the capacity and count of a that contains a simple business object, and illustrates using the method to remove extra capacity. + + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Capacity/program.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.list.capacitycount/vb/module1.vb" id="Snippet1"::: + + The following example shows the property at several points in the life of a list. The parameterless constructor is used to create a list of strings with a capacity of 0, and the property is displayed to demonstrate this. After the method has been used to add several items, the items are listed, and then the property is displayed again, along with the property, to show that the capacity has been increased as needed. + + The property is displayed again after the method is used to reduce the capacity to match the count. Finally, the method is used to remove all items from the list, and the and properties are displayed again. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_Class/cpp/source.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Overview/source.cs" interactive="try-dotnet-method" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_Class/vb/source.vb" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR/List`1_Class/fs/listclass.fs" id="Snippet1"::: + ]]> @@ -948,24 +948,24 @@ Removes all elements from the . - is set to 0, and references to other objects from elements of the collection are also released. - - remains unchanged. To reset the capacity of the , call the method or set the property directly. Decreasing the capacity reallocates memory and copies all the elements in the . Trimming an empty sets the capacity of the to the default capacity. - - This method is an O(*n*) operation, where *n* is . - -## Examples - - The following example demonstrates the method and various other properties and methods of the generic class. The method is used at the end of the program, to remove all items from the list, and the and properties are then displayed. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_Class/cpp/source.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Overview/source.cs" interactive="try-dotnet-method" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_Class/vb/source.vb" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR/List`1_Class/fs/listclass.fs" id="Snippet1"::: - + is set to 0, and references to other objects from elements of the collection are also released. + + remains unchanged. To reset the capacity of the , call the method or set the property directly. Decreasing the capacity reallocates memory and copies all the elements in the . Trimming an empty sets the capacity of the to the default capacity. + + This method is an O(*n*) operation, where *n* is . + +## Examples + + The following example demonstrates the method and various other properties and methods of the generic class. The method is used at the end of the program, to remove all items from the list, and the and properties are then displayed. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_Class/cpp/source.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Overview/source.cs" interactive="try-dotnet-method" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_Class/vb/source.vb" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR/List`1_Class/fs/listclass.fs" id="Snippet1"::: + ]]> @@ -1020,24 +1020,24 @@ if is found in the ; otherwise, . - method for `T` (the type of values in the list). - - This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is . - -## Examples - The following example demonstrates the and methods on a that contains a simple business object that implements . - - :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Contains/program1.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.list.containsexists/vb/module1.vb" id="Snippet1"::: - - The following example contains a list of complex objects of type `Cube`. The `Cube` class implements the method so that two cubes are considered equal if their dimensions are the same. In this example, the method returns `true`, because a cube that has the specified dimensions is already in the collection. - - :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Contains/program.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.list.contains/vb/program.vb" id="Snippet1"::: - + method for `T` (the type of values in the list). + + This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is . + +## Examples + The following example demonstrates the and methods on a that contains a simple business object that implements . + + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Contains/program1.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.list.containsexists/vb/module1.vb" id="Snippet1"::: + + The following example contains a list of complex objects of type `Cube`. The `Cube` class implements the method so that two cubes are considered equal if their dimensions are the same. In this example, the method returns `true`, because a cube that has the specified dimensions is already in the collection. + + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Contains/program.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.list.contains/vb/program.vb" id="Snippet1"::: + ]]> @@ -1089,7 +1089,7 @@ - + The type of the elements of the target array. @@ -1097,22 +1097,22 @@ Converts the elements in the current to another type, and returns a list containing the converted elements. A of the target type containing the converted elements from the current . - is a delegate to a method that converts an object to the target type. The elements of the current are individually passed to the delegate, and the converted elements are saved in the new . - - The current remains unchanged. - - This method is an O(*n*) operation, where *n* is . - -## Examples - The following example defines a method named `PointFToPoint` that converts a structure to a structure. The example then creates a of structures, creates a `Converter\` delegate (`Converter(Of PointF, Point)` in Visual Basic) to represent the `PointFToPoint` method, and passes the delegate to the method. The method passes each element of the input list to the `PointFToPoint` method and puts the converted elements into a new list of structures. Both lists are displayed. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_ConvertAll/cpp/source.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/ConverterTInput,TOutput/Overview/source.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_ConvertAll/vb/source.vb" id="Snippet1"::: - + is a delegate to a method that converts an object to the target type. The elements of the current are individually passed to the delegate, and the converted elements are saved in the new . + + The current remains unchanged. + + This method is an O(*n*) operation, where *n* is . + +## Examples + The following example defines a method named `PointFToPoint` that converts a structure to a structure. The example then creates a of structures, creates a `Converter\` delegate (`Converter(Of PointF, Point)` in Visual Basic) to represent the `PointFToPoint` method, and passes the delegate to the method. The method passes each element of the input list to the `PointFToPoint` method and puts the converted elements into a new list of structures. Both lists are displayed. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_ConvertAll/cpp/source.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System/ConverterTInput,TOutput/Overview/source.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_ConvertAll/vb/source.vb" id="Snippet1"::: + ]]> @@ -1130,15 +1130,15 @@ Copies the or a portion of it to an array. - method. A of strings is created and populated with 5 strings. An empty string array of 15 elements is created, and the method overload is used to copy all the elements of the list to the array beginning at the first element of the array. The method overload is used to copy all the elements of the list to the array beginning at array index 6 (leaving index 5 empty). Finally, the method overload is used to copy 3 elements from the list, beginning with index 2, to the array beginning at array index 12 (leaving index 11 empty). The contents of the array are then displayed. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_CopyTo/cpp/source.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/CopyTo/source.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_CopyTo/vb/source.vb" id="Snippet1"::: - + method. A of strings is created and populated with 5 strings. An empty string array of 15 elements is created, and the method overload is used to copy all the elements of the list to the array beginning at the first element of the array. The method overload is used to copy all the elements of the list to the array beginning at array index 6 (leaving index 5 empty). Finally, the method overload is used to copy 3 elements from the list, beginning with index 2, to the array beginning at array index 12 (leaving index 11 empty). The contents of the array are then displayed. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_CopyTo/cpp/source.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/CopyTo/source.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_CopyTo/vb/source.vb" id="Snippet1"::: + ]]> @@ -1191,15 +1191,15 @@ The one-dimensional that is the destination of the elements copied from . The must have zero-based indexing. Copies the entire to a compatible one-dimensional array, starting at the beginning of the target array. - to copy the elements. - - The elements are copied to the in the same order in which the enumerator iterates through the . - - This method is an O(*n*) operation, where *n* is . - + to copy the elements. + + The elements are copied to the in the same order in which the enumerator iterates through the . + + This method is an O(*n*) operation, where *n* is . + ]]> @@ -1254,15 +1254,15 @@ The zero-based index in at which copying begins. Copies the entire to a compatible one-dimensional array, starting at the specified index of the target array. - to copy the elements. - - The elements are copied to the in the same order in which the enumerator iterates through the . - - This method is an O(*n*) operation, where *n* is . - + to copy the elements. + + The elements are copied to the in the same order in which the enumerator iterates through the . + + This method is an O(*n*) operation, where *n* is . + ]]> @@ -1320,34 +1320,34 @@ The number of elements to copy. Copies a range of elements from the to a compatible one-dimensional array, starting at the specified index of the target array. - to copy the elements. - - The elements are copied to the in the same order in which the enumerator iterates through the . - - This method is an O(*n*) operation, where *n* is `count`. - + to copy the elements. + + The elements are copied to the in the same order in which the enumerator iterates through the . + + This method is an O(*n*) operation, where *n* is `count`. + ]]> is . - is less than 0. - - -or- - - is less than 0. - - -or- - + is less than 0. + + -or- + + is less than 0. + + -or- + is less than 0. - is equal to or greater than the of the source . - - -or- - + is equal to or greater than the of the source . + + -or- + The number of elements from to the end of the source is greater than the available space from to the end of the destination . @@ -1395,29 +1395,29 @@ Gets the number of elements contained in the . The number of elements contained in the . - is the number of elements that the can store before resizing is required. is the number of elements that are actually in the . - - is always greater than or equal to . If exceeds while adding elements, the capacity is increased by automatically reallocating the internal array before copying the old elements and adding the new elements. - - Retrieving the value of this property is an O(1) operation. - -## Examples - - The following example demonstrates how to check the capacity and count of a that contains a simple business object, and illustrates using the method to remove extra capacity. - - :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Capacity/program.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.list.capacitycount/vb/module1.vb" id="Snippet1"::: - - The following example shows the value of the property at various points in the life of a list. After the list has been created and populated and its elements displayed, the and properties are displayed. These properties are displayed again after the method has been called, and again after the contents of the list are cleared. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_Class/cpp/source.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Overview/source.cs" interactive="try-dotnet-method" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_Class/vb/source.vb" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR/List`1_Class/fs/listclass.fs" id="Snippet1"::: - + is the number of elements that the can store before resizing is required. is the number of elements that are actually in the . + + is always greater than or equal to . If exceeds while adding elements, the capacity is increased by automatically reallocating the internal array before copying the old elements and adding the new elements. + + Retrieving the value of this property is an O(1) operation. + +## Examples + + The following example demonstrates how to check the capacity and count of a that contains a simple business object, and illustrates using the method to remove extra capacity. + + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Capacity/program.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.list.capacitycount/vb/module1.vb" id="Snippet1"::: + + The following example shows the value of the property at various points in the life of a list. After the list has been created and populated and its elements displayed, the and properties are displayed. These properties are displayed again after the method has been called, and again after the contents of the list are cleared. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_Class/cpp/source.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Overview/source.cs" interactive="try-dotnet-method" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_Class/vb/source.vb" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR/List`1_Class/fs/listclass.fs" id="Snippet1"::: + ]]> @@ -1501,34 +1501,34 @@ if the contains one or more elements that match the conditions defined by the specified predicate; otherwise, . - is a delegate to a method that returns `true` if the object passed to it matches the conditions defined in the delegate. The elements of the current are individually passed to the delegate, and processing is stopped when a match is found. - - This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is . - -## Examples - The following example demonstrates the and methods on a that contains a simple business object that implements . - - :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Contains/program1.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.list.containsexists/vb/module1.vb" id="Snippet1"::: - - The following example demonstrates the method and several other methods that use the generic delegate. - - A of strings is created, containing 8 dinosaur names, two of which (at positions 1 and 5) end with "saurus". The example also defines a search predicate method named `EndsWithSaurus`, which accepts a string parameter and returns a Boolean value indicating whether the input string ends in "saurus". - - The , , and methods are used to search the list with the search predicate method, and then the method is used to remove all entries ending with "saurus". - - Finally, the method is called. It traverses the list from the beginning, passing each element in turn to the `EndsWithSaurus` method. The search stops and the method returns `true` if the `EndsWithSaurus` method returns `true` for any element. The method returns `false` because all such elements have been removed. - -> [!NOTE] -> In C# and Visual Basic, it is not necessary to create the `Predicate` delegate (`Predicate(Of String)` in Visual Basic) explicitly. These languages infer the correct delegate from context and create it automatically. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_FindEtAl/cpp/source.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Exists/source.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_FindEtAl/vb/source.vb" id="Snippet1"::: - + is a delegate to a method that returns `true` if the object passed to it matches the conditions defined in the delegate. The elements of the current are individually passed to the delegate, and processing is stopped when a match is found. + + This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is . + +## Examples + The following example demonstrates the and methods on a that contains a simple business object that implements . + + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Contains/program1.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.list.containsexists/vb/module1.vb" id="Snippet1"::: + + The following example demonstrates the method and several other methods that use the generic delegate. + + A of strings is created, containing 8 dinosaur names, two of which (at positions 1 and 5) end with "saurus". The example also defines a search predicate method named `EndsWithSaurus`, which accepts a string parameter and returns a Boolean value indicating whether the input string ends in "saurus". + + The , , and methods are used to search the list with the search predicate method, and then the method is used to remove all entries ending with "saurus". + + Finally, the method is called. It traverses the list from the beginning, passing each element in turn to the `EndsWithSaurus` method. The search stops and the method returns `true` if the `EndsWithSaurus` method returns `true` for any element. The method returns `false` because all such elements have been removed. + +> [!NOTE] +> In C# and Visual Basic, it is not necessary to create the `Predicate` delegate (`Predicate(Of String)` in Visual Basic) explicitly. These languages infer the correct delegate from context and create it automatically. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_FindEtAl/cpp/source.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Exists/source.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_FindEtAl/vb/source.vb" id="Snippet1"::: + ]]> @@ -1589,39 +1589,39 @@ Searches for an element that matches the conditions defined by the specified predicate, and returns the first occurrence within the entire . The first element that matches the conditions defined by the specified predicate, if found; otherwise, the default value for type . - is a delegate to a method that returns `true` if the object passed to it matches the conditions defined in the delegate. The elements of the current are individually passed to the delegate, moving forward in the , starting with the first element and ending with the last element. Processing is stopped when a match is found. - -> [!IMPORTANT] -> When searching a list containing value types, make sure the default value for the type does not satisfy the search predicate. Otherwise, there is no way to distinguish between a default value indicating that no match was found and a list element that happens to have the default value for the type. If the default value satisfies the search predicate, use the method instead. - - This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is . - -## Examples - The following example demonstrates the method on a that contains a simple complex object. - - :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Contains/program1.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.list.containsexists/vb/module1.vb" id="Snippet1"::: - - The following example demonstrates the find methods for the class. The example for the class contains `book` objects, of class `Book`, using the data from the [Sample XML File: Books (LINQ to XML)](/dotnet/standard/linq/sample-xml-file-books). The `FillList` method in the example uses [LINQ to XML](/dotnet/standard/linq/linq-xml-overview) to parse the values from the XML to property values of the `book` objects. - - The following table describes the examples provided for the find methods. - -|Method|Example| -|------------|-------------| -||Finds a book by an ID using the `IDToFind` predicate delegate.

C# example uses an anonymous delegate.| -||Find all books that whose `Genre` property is "Computer" using the `FindComputer` predicate delegate.| -||Finds the last book in the collection that has a publish date before 2001, using the `PubBefore2001` predicate delegate.

C# example uses an anonymous delegate.| -||Finds the index of first computer book using the `FindComputer` predicate delegate.| -||Finds the index of the last computer book using the `FindComputer` predicate delegate.| -||Finds the index of first computer book in the second half of the collection, using the `FindComputer` predicate delegate.| -||Finds the index of last computer book in the second half of the collection, using the `FindComputer` predicate delegate.| - - :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Find/program.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/list`1_find_methods/vb/module1.vb" id="Snippet1"::: - + is a delegate to a method that returns `true` if the object passed to it matches the conditions defined in the delegate. The elements of the current are individually passed to the delegate, moving forward in the , starting with the first element and ending with the last element. Processing is stopped when a match is found. + +> [!IMPORTANT] +> When searching a list containing value types, make sure the default value for the type does not satisfy the search predicate. Otherwise, there is no way to distinguish between a default value indicating that no match was found and a list element that happens to have the default value for the type. If the default value satisfies the search predicate, use the method instead. + + This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is . + +## Examples + The following example demonstrates the method on a that contains a simple complex object. + + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Contains/program1.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.list.containsexists/vb/module1.vb" id="Snippet1"::: + + The following example demonstrates the find methods for the class. The example for the class contains `book` objects, of class `Book`, using the data from the [Sample XML File: Books (LINQ to XML)](/dotnet/standard/linq/sample-xml-file-books). The `FillList` method in the example uses [LINQ to XML](/dotnet/standard/linq/linq-xml-overview) to parse the values from the XML to property values of the `book` objects. + + The following table describes the examples provided for the find methods. + +|Method|Example| +|------------|-------------| +||Finds a book by an ID using the `IDToFind` predicate delegate.

C# example uses an anonymous delegate.| +||Find all books that whose `Genre` property is "Computer" using the `FindComputer` predicate delegate.| +||Finds the last book in the collection that has a publish date before 2001, using the `PubBefore2001` predicate delegate.

C# example uses an anonymous delegate.| +||Finds the index of first computer book using the `FindComputer` predicate delegate.| +||Finds the index of the last computer book using the `FindComputer` predicate delegate.| +||Finds the index of first computer book in the second half of the collection, using the `FindComputer` predicate delegate.| +||Finds the index of last computer book in the second half of the collection, using the `FindComputer` predicate delegate.| + + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Find/program.cs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/list`1_find_methods/vb/module1.vb" id="Snippet1"::: + ]]>
@@ -1680,31 +1680,31 @@ Retrieves all the elements that match the conditions defined by the specified predicate. A containing all the elements that match the conditions defined by the specified predicate, if found; otherwise, an empty . - is a delegate to a method that returns `true` if the object passed to it matches the conditions defined in the delegate. The elements of the current are individually passed to the delegate, and the elements that match the conditions are saved in the returned . - - This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is . - -## Examples - The following example demonstrates the find methods for the class. The example for the class contains `book` objects, of class `Book`, using the data from the [Sample XML File: Books (LINQ to XML)](/dotnet/standard/linq/sample-xml-file-books). The `FillList` method in the example uses [LINQ to XML](/dotnet/standard/linq/linq-xml-overview) to parse the values from the XML to property values of the `book` objects. - - The following table describes the examples provided for the find methods. - -|Method|Example| -|------------|-------------| -||Finds a book by an ID using the `IDToFind` predicate delegate.

C# example uses an anonymous delegate.| -||Find all books that whose `Genre` property is "Computer" using the `FindComputer` predicate delegate.| -||Finds the last book in the collection that has a publish date before 2001, using the `PubBefore2001` predicate delegate.

C# example uses an anonymous delegate.| -||Finds the index of first computer book using the `FindComputer` predicate delegate.| -||Finds the index of the last computer book using the `FindComputer` predicate delegate.| -||Finds the index of first computer book in the second half of the collection, using the `FindComputer` predicate delegate.| -||Finds the index of last computer book in the second half of the collection, using the `FindComputer` predicate delegate.| - - :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Find/program.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/list`1_find_methods/vb/module1.vb" id="Snippet1"::: - + is a delegate to a method that returns `true` if the object passed to it matches the conditions defined in the delegate. The elements of the current are individually passed to the delegate, and the elements that match the conditions are saved in the returned . + + This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is . + +## Examples + The following example demonstrates the find methods for the class. The example for the class contains `book` objects, of class `Book`, using the data from the [Sample XML File: Books (LINQ to XML)](/dotnet/standard/linq/sample-xml-file-books). The `FillList` method in the example uses [LINQ to XML](/dotnet/standard/linq/linq-xml-overview) to parse the values from the XML to property values of the `book` objects. + + The following table describes the examples provided for the find methods. + +|Method|Example| +|------------|-------------| +||Finds a book by an ID using the `IDToFind` predicate delegate.

C# example uses an anonymous delegate.| +||Find all books that whose `Genre` property is "Computer" using the `FindComputer` predicate delegate.| +||Finds the last book in the collection that has a publish date before 2001, using the `PubBefore2001` predicate delegate.

C# example uses an anonymous delegate.| +||Finds the index of first computer book using the `FindComputer` predicate delegate.| +||Finds the index of the last computer book using the `FindComputer` predicate delegate.| +||Finds the index of first computer book in the second half of the collection, using the `FindComputer` predicate delegate.| +||Finds the index of last computer book in the second half of the collection, using the `FindComputer` predicate delegate.| + + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Find/program.cs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/list`1_find_methods/vb/module1.vb" id="Snippet1"::: + ]]>
@@ -1774,39 +1774,39 @@ Searches for an element that matches the conditions defined by the specified predicate, and returns the zero-based index of the first occurrence within the entire . The zero-based index of the first occurrence of an element that matches the conditions defined by , if found; otherwise, -1. - is searched forward starting at the first element and ending at the last element. - - The is a delegate to a method that returns `true` if the object passed to it matches the conditions defined in the delegate. The elements of the current are individually passed to the delegate. The delegate has the signature: - -```csharp -public bool methodName(T obj) -``` - -```vb -Public Function methodName(obj As T) As Boolean -``` - - This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is . - -## Examples - The following example defines an `Employee` class with two fields, `Name` and `Id`. It also defines an `EmployeeSearch` class with a single method, `StartsWith`, that indicates whether the `Employee.Name` field starts with a specified substring that is supplied to the `EmployeeSearch` class constructor. Note the signature of this method - -```csharp -public bool StartsWith(Employee e) -``` - -```vb -Public Function StartsWith(e As Employee) As Boolean -``` - - corresponds to the signature of the delegate that can be passed to the method. The example instantiates a `List` object, adds a number of `Employee` objects to it, and then calls the method twice to search the entire collection, the first time for the first `Employee` object whose `Name` field begins with "J", and the second time for the first `Employee` object whose `Name` field begins with "Ju". - - :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/FindIndex/FindIndex2.cs" interactive="try-dotnet" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/System.Collections.Generic.List.FindIndex/vb/FindIndex2.vb" id="Snippet2"::: - + is searched forward starting at the first element and ending at the last element. + + The is a delegate to a method that returns `true` if the object passed to it matches the conditions defined in the delegate. The elements of the current are individually passed to the delegate. The delegate has the signature: + +```csharp +public bool methodName(T obj) +``` + +```vb +Public Function methodName(obj As T) As Boolean +``` + + This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is . + +## Examples + The following example defines an `Employee` class with two fields, `Name` and `Id`. It also defines an `EmployeeSearch` class with a single method, `StartsWith`, that indicates whether the `Employee.Name` field starts with a specified substring that is supplied to the `EmployeeSearch` class constructor. Note the signature of this method + +```csharp +public bool StartsWith(Employee e) +``` + +```vb +Public Function StartsWith(e As Employee) As Boolean +``` + + corresponds to the signature of the delegate that can be passed to the method. The example instantiates a `List` object, adds a number of `Employee` objects to it, and then calls the method twice to search the entire collection, the first time for the first `Employee` object whose `Name` field begins with "J", and the second time for the first `Employee` object whose `Name` field begins with "Ju". + + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/FindIndex/FindIndex2.cs" interactive="try-dotnet" id="Snippet2"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/System.Collections.Generic.List.FindIndex/vb/FindIndex2.vb" id="Snippet2"::: + ]]> @@ -1867,39 +1867,39 @@ Public Function StartsWith(e As Employee) As Boolean Searches for an element that matches the conditions defined by the specified predicate, and returns the zero-based index of the first occurrence within the range of elements in the that extends from the specified index to the last element. The zero-based index of the first occurrence of an element that matches the conditions defined by , if found; otherwise, -1. - is searched forward starting at `startIndex` and ending at the last element. - - The is a delegate to a method that returns `true` if the object passed to it matches the conditions defined in the delegate. The elements of the current are individually passed to the delegate. The delegate has the signature: - -```csharp -public bool methodName(T obj) -``` - -```vb -Public Function methodName(obj As T) As Boolean -``` - - This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is the number of elements from `startIndex` to the end of the . - -## Examples - The following example defines an `Employee` class with two fields, `Name` and `Id`. It also defines an `EmployeeSearch` class with a single method, `StartsWith`, that indicates whether the `Employee.Name` field starts with a specified substring that is supplied to the `EmployeeSearch` class constructor. Note the signature of this method - -```csharp -public bool StartsWith(Employee e) -``` - -```vb -Public Function StartsWith(e As Employee) As Boolean -``` - - corresponds to the signature of the delegate that can be passed to the method. The example instantiates a `List` object, adds a number of `Employee` objects to it, and then calls the method twice to search the collection starting with its fifth member (that is, the member at index 4). The first time, it searches for the first `Employee` object whose `Name` field begins with "J"; the second time, it searches for the first `Employee` object whose `Name` field begins with "Ju". - - :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/FindIndex/FindIndex3.cs" interactive="try-dotnet" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/System.Collections.Generic.List.FindIndex/vb/FindIndex3.vb" id="Snippet3"::: - + is searched forward starting at `startIndex` and ending at the last element. + + The is a delegate to a method that returns `true` if the object passed to it matches the conditions defined in the delegate. The elements of the current are individually passed to the delegate. The delegate has the signature: + +```csharp +public bool methodName(T obj) +``` + +```vb +Public Function methodName(obj As T) As Boolean +``` + + This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is the number of elements from `startIndex` to the end of the . + +## Examples + The following example defines an `Employee` class with two fields, `Name` and `Id`. It also defines an `EmployeeSearch` class with a single method, `StartsWith`, that indicates whether the `Employee.Name` field starts with a specified substring that is supplied to the `EmployeeSearch` class constructor. Note the signature of this method + +```csharp +public bool StartsWith(Employee e) +``` + +```vb +Public Function StartsWith(e As Employee) As Boolean +``` + + corresponds to the signature of the delegate that can be passed to the method. The example instantiates a `List` object, adds a number of `Employee` objects to it, and then calls the method twice to search the collection starting with its fifth member (that is, the member at index 4). The first time, it searches for the first `Employee` object whose `Name` field begins with "J"; the second time, it searches for the first `Employee` object whose `Name` field begins with "Ju". + + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/FindIndex/FindIndex3.cs" interactive="try-dotnet" id="Snippet3"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/System.Collections.Generic.List.FindIndex/vb/FindIndex3.vb" id="Snippet3"::: + ]]> @@ -1964,52 +1964,52 @@ Public Function StartsWith(e As Employee) As Boolean Searches for an element that matches the conditions defined by the specified predicate, and returns the zero-based index of the first occurrence within the range of elements in the that starts at the specified index and contains the specified number of elements. The zero-based index of the first occurrence of an element that matches the conditions defined by , if found; otherwise, -1. - is searched forward starting at `startIndex` and ending at `startIndex` plus `count` minus 1, if `count` is greater than 0. - - The is a delegate to a method that returns `true` if the object passed to it matches the conditions defined in the delegate. The elements of the current are individually passed to the delegate. The delegate has the signature: - -```csharp -public bool methodName(T obj) -``` - -```vb -Public Function methodName(obj As T) As Boolean -``` - - This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is `count`. - -## Examples - The following example defines an `Employee` class with two fields, `Name` and `Id`. It also defines an `EmployeeSearch` class with a single method, `StartsWith`, that indicates whether the `Employee.Name` field starts with a specified substring that is supplied to the `EmployeeSearch` class constructor. Note the signature of this method - -```csharp -public bool StartsWith(Employee e) -``` - -```vb -Public Function StartsWith(e As Employee) As Boolean -``` - - corresponds to the signature of the delegate that can be passed to the method. The example instantiates a `List` object, adds a number of `Employee` objects to it, and then calls the method twice to search the entire collection (that is, the members from index 0 to index - 1). The first time, it searches for the first `Employee` object whose `Name` field begins with "J"; the second time, it searches for the first `Employee` object whose `Name` field begins with "Ju". - - :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/FindIndex/FindIndex1.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/System.Collections.Generic.List.FindIndex/vb/FindIndex1.vb" id="Snippet1"::: - + is searched forward starting at `startIndex` and ending at `startIndex` plus `count` minus 1, if `count` is greater than 0. + + The is a delegate to a method that returns `true` if the object passed to it matches the conditions defined in the delegate. The elements of the current are individually passed to the delegate. The delegate has the signature: + +```csharp +public bool methodName(T obj) +``` + +```vb +Public Function methodName(obj As T) As Boolean +``` + + This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is `count`. + +## Examples + The following example defines an `Employee` class with two fields, `Name` and `Id`. It also defines an `EmployeeSearch` class with a single method, `StartsWith`, that indicates whether the `Employee.Name` field starts with a specified substring that is supplied to the `EmployeeSearch` class constructor. Note the signature of this method + +```csharp +public bool StartsWith(Employee e) +``` + +```vb +Public Function StartsWith(e As Employee) As Boolean +``` + + corresponds to the signature of the delegate that can be passed to the method. The example instantiates a `List` object, adds a number of `Employee` objects to it, and then calls the method twice to search the entire collection (that is, the members from index 0 to index - 1). The first time, it searches for the first `Employee` object whose `Name` field begins with "J"; the second time, it searches for the first `Employee` object whose `Name` field begins with "Ju". + + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/FindIndex/FindIndex1.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/System.Collections.Generic.List.FindIndex/vb/FindIndex1.vb" id="Snippet1"::: + ]]> is . - is outside the range of valid indexes for the . - - -or- - - is less than 0. - - -or- - + is outside the range of valid indexes for the . + + -or- + + is less than 0. + + -or- + and do not specify a valid section in the . @@ -2066,34 +2066,34 @@ Public Function StartsWith(e As Employee) As Boolean Searches for an element that matches the conditions defined by the specified predicate, and returns the last occurrence within the entire . The last element that matches the conditions defined by the specified predicate, if found; otherwise, the default value for type . - is a delegate to a method that returns `true` if the object passed to it matches the conditions defined in the delegate. The elements of the current are individually passed to the delegate, moving backward in the , starting with the last element and ending with the first element. Processing is stopped when a match is found. - -> [!IMPORTANT] -> When searching a list containing value types, make sure the default value for the type does not satisfy the search predicate. Otherwise, there is no way to distinguish between a default value indicating that no match was found and a list element that happens to have the default value for the type. If the default value satisfies the search predicate, use the method instead. - - This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is . - -## Examples - The following example demonstrates the find methods for the class. The example for the class contains `book` objects, of class `Book`, using the data from the [Sample XML File: Books (LINQ to XML)](/dotnet/standard/linq/sample-xml-file-books). The `FillList` method in the example uses [LINQ to XML](/dotnet/standard/linq/linq-xml-overview) to parse the values from the XML to property values of the `book` objects. - - The following table describes the examples provided for the find methods. - -|Method|Example| -|------------|-------------| -||Finds a book by an ID using the `IDToFind` predicate delegate.

C# example uses an anonymous delegate.| -||Find all books that whose `Genre` property is "Computer" using the `FindComputer` predicate delegate.| -||Finds the last book in the collection that has a publish date before 2001, using the `PubBefore2001` predicate delegate.

C# example uses an anonymous delegate.| -||Finds the index of first computer book using the `FindComputer` predicate delegate.| -||Finds the index of the last computer book using the `FindComputer` predicate delegate.| -||Finds the index of first computer book in the second half of the collection, using the `FindComputer` predicate delegate.| -||Finds the index of last computer book in the second half of the collection, using the `FindComputer` predicate delegate.| - - :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Find/program.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/list`1_find_methods/vb/module1.vb" id="Snippet1"::: - + is a delegate to a method that returns `true` if the object passed to it matches the conditions defined in the delegate. The elements of the current are individually passed to the delegate, moving backward in the , starting with the last element and ending with the first element. Processing is stopped when a match is found. + +> [!IMPORTANT] +> When searching a list containing value types, make sure the default value for the type does not satisfy the search predicate. Otherwise, there is no way to distinguish between a default value indicating that no match was found and a list element that happens to have the default value for the type. If the default value satisfies the search predicate, use the method instead. + + This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is . + +## Examples + The following example demonstrates the find methods for the class. The example for the class contains `book` objects, of class `Book`, using the data from the [Sample XML File: Books (LINQ to XML)](/dotnet/standard/linq/sample-xml-file-books). The `FillList` method in the example uses [LINQ to XML](/dotnet/standard/linq/linq-xml-overview) to parse the values from the XML to property values of the `book` objects. + + The following table describes the examples provided for the find methods. + +|Method|Example| +|------------|-------------| +||Finds a book by an ID using the `IDToFind` predicate delegate.

C# example uses an anonymous delegate.| +||Find all books that whose `Genre` property is "Computer" using the `FindComputer` predicate delegate.| +||Finds the last book in the collection that has a publish date before 2001, using the `PubBefore2001` predicate delegate.

C# example uses an anonymous delegate.| +||Finds the index of first computer book using the `FindComputer` predicate delegate.| +||Finds the index of the last computer book using the `FindComputer` predicate delegate.| +||Finds the index of first computer book in the second half of the collection, using the `FindComputer` predicate delegate.| +||Finds the index of last computer book in the second half of the collection, using the `FindComputer` predicate delegate.| + + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Find/program.cs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/list`1_find_methods/vb/module1.vb" id="Snippet1"::: + ]]>
@@ -2163,33 +2163,33 @@ Public Function StartsWith(e As Employee) As Boolean Searches for an element that matches the conditions defined by the specified predicate, and returns the zero-based index of the last occurrence within the entire . The zero-based index of the last occurrence of an element that matches the conditions defined by , if found; otherwise, -1. - is searched backward starting at the last element and ending at the first element. - - The is a delegate to a method that returns `true` if the object passed to it matches the conditions defined in the delegate. The elements of the current are individually passed to the delegate. - - This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is . - -## Examples - The following example demonstrates the find methods for the class. The example for the class contains `book` objects, of class `Book`, using the data from the [Sample XML File: Books (LINQ to XML)](/dotnet/standard/linq/sample-xml-file-books). The `FillList` method in the example uses [LINQ to XML](/dotnet/standard/linq/linq-xml-overview) to parse the values from the XML to property values of the `book` objects. - - The following table describes the examples provided for the find methods. - -|Method|Example| -|------------|-------------| -||Finds a book by an ID using the `IDToFind` predicate delegate.

C# example uses an anonymous delegate.| -||Find all books that whose `Genre` property is "Computer" using the `FindComputer` predicate delegate.| -||Finds the last book in the collection that has a publish date before 2001, using the `PubBefore2001` predicate delegate.

C# example uses an anonymous delegate.| -||Finds the index of first computer book using the `FindComputer` predicate delegate.| -||Finds the index of the last computer book using the `FindComputer` predicate delegate.| -||Finds the index of first computer book in the second half of the collection, using the `FindComputer` predicate delegate.| -||Finds the index of last computer book in the second half of the collection, using the `FindComputer` predicate delegate.| - - :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Find/program.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/list`1_find_methods/vb/module1.vb" id="Snippet1"::: - + is searched backward starting at the last element and ending at the first element. + + The is a delegate to a method that returns `true` if the object passed to it matches the conditions defined in the delegate. The elements of the current are individually passed to the delegate. + + This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is . + +## Examples + The following example demonstrates the find methods for the class. The example for the class contains `book` objects, of class `Book`, using the data from the [Sample XML File: Books (LINQ to XML)](/dotnet/standard/linq/sample-xml-file-books). The `FillList` method in the example uses [LINQ to XML](/dotnet/standard/linq/linq-xml-overview) to parse the values from the XML to property values of the `book` objects. + + The following table describes the examples provided for the find methods. + +|Method|Example| +|------------|-------------| +||Finds a book by an ID using the `IDToFind` predicate delegate.

C# example uses an anonymous delegate.| +||Find all books that whose `Genre` property is "Computer" using the `FindComputer` predicate delegate.| +||Finds the last book in the collection that has a publish date before 2001, using the `PubBefore2001` predicate delegate.

C# example uses an anonymous delegate.| +||Finds the index of first computer book using the `FindComputer` predicate delegate.| +||Finds the index of the last computer book using the `FindComputer` predicate delegate.| +||Finds the index of first computer book in the second half of the collection, using the `FindComputer` predicate delegate.| +||Finds the index of last computer book in the second half of the collection, using the `FindComputer` predicate delegate.| + + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Find/program.cs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/list`1_find_methods/vb/module1.vb" id="Snippet1"::: + ]]>
@@ -2250,15 +2250,15 @@ Public Function StartsWith(e As Employee) As Boolean Searches for an element that matches the conditions defined by the specified predicate, and returns the zero-based index of the last occurrence within the range of elements in the that extends from the first element to the specified index. The zero-based index of the last occurrence of an element that matches the conditions defined by , if found; otherwise, -1. - is searched backward starting at `startIndex` and ending at the first element. - - The is a delegate to a method that returns `true` if the object passed to it matches the conditions defined in the delegate. The elements of the current are individually passed to the delegate. - - This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is the number of elements from the beginning of the to `startIndex`. - + is searched backward starting at `startIndex` and ending at the first element. + + The is a delegate to a method that returns `true` if the object passed to it matches the conditions defined in the delegate. The elements of the current are individually passed to the delegate. + + This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is the number of elements from the beginning of the to `startIndex`. + ]]> @@ -2323,46 +2323,46 @@ Public Function StartsWith(e As Employee) As Boolean Searches for an element that matches the conditions defined by the specified predicate, and returns the zero-based index of the last occurrence within the range of elements in the that contains the specified number of elements and ends at the specified index. The zero-based index of the last occurrence of an element that matches the conditions defined by , if found; otherwise, -1. - is searched backward starting at `startIndex` and ending at `startIndex` minus `count` plus 1, if `count` is greater than 0. - - The is a delegate to a method that returns `true` if the object passed to it matches the conditions defined in the delegate. The elements of the current are individually passed to the delegate. - - This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is `count`. - -## Examples - The following example demonstrates the find methods for the class. The example for the class contains `book` objects, of class `Book`, using the data from the [Sample XML File: Books (LINQ to XML)](/dotnet/standard/linq/sample-xml-file-books). The `FillList` method in the example uses [LINQ to XML](/dotnet/standard/linq/linq-xml-overview) to parse the values from the XML to property values of the `book` objects. - - The following table describes the examples provided for the find methods. - -|Method|Example| -|------------|-------------| -||Finds a book by an ID using the `IDToFind` predicate delegate.

C# example uses an anonymous delegate.| -||Find all books that whose `Genre` property is "Computer" using the `FindComputer` predicate delegate.| -||Finds the last book in the collection that has a publish date before 2001, using the `PubBefore2001` predicate delegate.

C# example uses an anonymous delegate.| -||Finds the index of first computer book using the `FindComputer` predicate delegate.| -||Finds the index of the last computer book using the `FindComputer` predicate delegate.| -||Finds the index of first computer book in the second half of the collection, using the `FindComputer` predicate delegate.| -||Finds the index of last computer book in the second half of the collection, using the `FindComputer` predicate delegate.| - - :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Find/program.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/list`1_find_methods/vb/module1.vb" id="Snippet1"::: - + is searched backward starting at `startIndex` and ending at `startIndex` minus `count` plus 1, if `count` is greater than 0. + + The is a delegate to a method that returns `true` if the object passed to it matches the conditions defined in the delegate. The elements of the current are individually passed to the delegate. + + This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is `count`. + +## Examples + The following example demonstrates the find methods for the class. The example for the class contains `book` objects, of class `Book`, using the data from the [Sample XML File: Books (LINQ to XML)](/dotnet/standard/linq/sample-xml-file-books). The `FillList` method in the example uses [LINQ to XML](/dotnet/standard/linq/linq-xml-overview) to parse the values from the XML to property values of the `book` objects. + + The following table describes the examples provided for the find methods. + +|Method|Example| +|------------|-------------| +||Finds a book by an ID using the `IDToFind` predicate delegate.

C# example uses an anonymous delegate.| +||Find all books that whose `Genre` property is "Computer" using the `FindComputer` predicate delegate.| +||Finds the last book in the collection that has a publish date before 2001, using the `PubBefore2001` predicate delegate.

C# example uses an anonymous delegate.| +||Finds the index of first computer book using the `FindComputer` predicate delegate.| +||Finds the index of the last computer book using the `FindComputer` predicate delegate.| +||Finds the index of first computer book in the second half of the collection, using the `FindComputer` predicate delegate.| +||Finds the index of last computer book in the second half of the collection, using the `FindComputer` predicate delegate.| + + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Find/program.cs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/list`1_find_methods/vb/module1.vb" id="Snippet1"::: + ]]>
is . - is outside the range of valid indexes for the . - - -or- - - is less than 0. - - -or- - + is outside the range of valid indexes for the . + + -or- + + is less than 0. + + -or- + and do not specify a valid section in the . @@ -2416,24 +2416,24 @@ Public Function StartsWith(e As Employee) As Boolean The delegate to perform on each element of the . Performs the specified action on each element of the . - is a delegate to a method that performs an action on the object passed to it. The elements of the current are individually passed to the delegate. - - This method is an O(*n*) operation, where *n* is . - - Modifying the underlying collection in the body of the delegate is not supported and causes undefined behavior. - -## Examples - The following example demonstrates the use of the delegate to print the contents of a object. In this example the `Print` method is used to display the contents of the list to the console. - -> [!NOTE] -> In addition to displaying the contents using the `Print` method, the C# example demonstrates the use of [anonymous methods](/dotnet/csharp/programming-guide/statements-expressions-operators/anonymous-methods) to display the results to the console. - - :::code language="csharp" source="~/snippets/csharp/System/ActionT/Overview/action.cs" interactive="try-dotnet-method" id="Snippet01"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Action_PrintExample/vb/action.vb" id="Snippet01"::: - + is a delegate to a method that performs an action on the object passed to it. The elements of the current are individually passed to the delegate. + + This method is an O(*n*) operation, where *n* is . + + Modifying the underlying collection in the body of the delegate is not supported and causes undefined behavior. + +## Examples + The following example demonstrates the use of the delegate to print the contents of a object. In this example the `Print` method is used to display the contents of the list to the console. + +> [!NOTE] +> In addition to displaying the contents using the `Print` method, the C# example demonstrates the use of [anonymous methods](/dotnet/csharp/programming-guide/statements-expressions-operators/anonymous-methods) to display the results to the console. + + :::code language="csharp" source="~/snippets/csharp/System/ActionT/Overview/action.cs" interactive="try-dotnet-method" id="Snippet01"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Action_PrintExample/vb/action.vb" id="Snippet01"::: + ]]> @@ -2488,27 +2488,27 @@ Public Function StartsWith(e As Employee) As Boolean Returns an enumerator that iterates through the . A for 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 . - - The property returns the same object until 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. You cannot set to the first element of the collection again; you must create a new enumerator instance instead. - - 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 enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - - Default implementations of collections in the namespace are not synchronized. - - This method is an O(1) operation. - + 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 . + + The property returns the same object until 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. You cannot set to the first element of the collection again; you must create a new enumerator instance instead. + + 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 enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. + + Default implementations of collections in the namespace are not synchronized. + + This method is an O(1) operation. + ]]> @@ -2560,31 +2560,31 @@ Public Function StartsWith(e As Employee) As Boolean Creates a shallow copy of a range of elements in the source . A shallow copy of a range of elements in the source . - method and other methods of the class that act on ranges. At the end of the example, the method is used to get three items from the list, beginning with index location 2. The method is called on the resulting , creating an array of three elements. The elements of the array are displayed. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_Ranges/cpp/source.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/.ctor/source1.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_Ranges/vb/source.vb" id="Snippet1"::: - + method and other methods of the class that act on ranges. At the end of the example, the method is used to get three items from the list, beginning with index location 2. The method is called on the resulting , creating an array of three elements. The elements of the array are displayed. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_Ranges/cpp/source.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/.ctor/source1.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_Ranges/vb/source.vb" id="Snippet1"::: + ]]> - is less than 0. - - -or- - + is less than 0. + + -or- + is less than 0. and do not denote a valid range of elements in the . @@ -2603,15 +2603,15 @@ Public Function StartsWith(e As Employee) As Boolean Returns the zero-based index of the first occurrence of a value in the or in a portion of it. - method. A of strings is created, with one entry that appears twice, at index location 0 and index location 5. The method overload searches the list from the beginning, and finds the first occurrence of the string. The method overload is used to search the list beginning with index location 3 and continuing to the end of the list, and finds the second occurrence of the string. Finally, the method overload is used to search a range of two entries, beginning at index location two; it returns -1 because there are no instances of the search string in that range. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_IndexOf/cpp/source.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/IndexOf/source.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_IndexOf/vb/source.vb" id="Snippet1"::: - + method. A of strings is created, with one entry that appears twice, at index location 0 and index location 5. The method overload searches the list from the beginning, and finds the first occurrence of the string. The method overload is used to search the list beginning with index location 3 and continuing to the end of the list, and finds the second occurrence of the string. Finally, the method overload is used to search a range of two entries, beginning at index location two; it returns -1 because there are no instances of the search string in that range. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_IndexOf/cpp/source.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/IndexOf/source.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_IndexOf/vb/source.vb" id="Snippet1"::: + ]]> @@ -2668,15 +2668,15 @@ Public Function StartsWith(e As Employee) As Boolean Searches for the specified object and returns the zero-based index of the first occurrence within the entire . The zero-based index of the first occurrence of within the entire , if found; otherwise, -1. - is searched forward starting at the first element and ending at the last element. - - This method determines equality using the default equality comparer for `T`, the type of values in the list. - - This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is . - + is searched forward starting at the first element and ending at the last element. + + This method determines equality using the default equality comparer for `T`, the type of values in the list. + + This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is . + ]]> @@ -2729,15 +2729,15 @@ Public Function StartsWith(e As Employee) As Boolean Searches for the specified object and returns the zero-based index of the first occurrence within the range of elements in the that extends from the specified index to the last element. The zero-based index of the first occurrence of within the range of elements in the that extends from to the last element, if found; otherwise, -1. - is searched forward starting at `index` and ending at the last element. - - This method determines equality using the default equality comparer for `T`, the type of values in the list. - - This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is the number of elements from `index` to the end of the . - + is searched forward starting at `index` and ending at the last element. + + This method determines equality using the default equality comparer for `T`, the type of values in the list. + + This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is the number of elements from `index` to the end of the . + ]]> @@ -2794,26 +2794,26 @@ Public Function StartsWith(e As Employee) As Boolean Searches for the specified object and returns the zero-based index of the first occurrence within the range of elements in the that starts at the specified index and contains the specified number of elements. The zero-based index of the first occurrence of within the range of elements in the that starts at and contains number of elements, if found; otherwise, -1. - is searched forward starting at `index` and ending at `index` plus `count` minus 1, if `count` is greater than 0. - - This method determines equality using the default equality comparer for `T`, the type of values in the list. - - This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is `count`. - + is searched forward starting at `index` and ending at `index` plus `count` minus 1, if `count` is greater than 0. + + This method determines equality using the default equality comparer for `T`, the type of values in the list. + + This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is `count`. + ]]> - is outside the range of valid indexes for the . - - -or- - - is less than 0. - - -or- - + is outside the range of valid indexes for the . + + -or- + + is less than 0. + + -or- + and do not specify a valid section in the . @@ -2867,39 +2867,39 @@ Public Function StartsWith(e As Employee) As Boolean The object to insert. The value can be for reference types. Inserts an element into the at the specified index. - accepts `null` as a valid value for reference types and allows duplicate elements. - - If already equals , the capacity of the is increased by automatically reallocating the internal array, and the existing elements are copied to the new array before the new element is added. - - If `index` is equal to , `item` is added to the end of . - - This method is an O(*n*) operation, where *n* is . - -## Examples - - The following example demonstrates how to add, remove, and insert a simple business object in a . - - :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Overview/program.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.list.addremoveinsert/vb/module1.vb" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.collections.generic.list.addremoveinsert/fs/addremoveinsert.fs" id="Snippet1"::: - - The following example demonstrates the method, along with various other properties and methods of the generic class. After the list is created, elements are added. The method is used to insert an item into the middle of the list. The item inserted is a duplicate, which is later removed using the method. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_Class/cpp/source.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Overview/source.cs" interactive="try-dotnet-method" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_Class/vb/source.vb" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR/List`1_Class/fs/listclass.fs" id="Snippet1"::: - + accepts `null` as a valid value for reference types and allows duplicate elements. + + If already equals , the capacity of the is increased by automatically reallocating the internal array, and the existing elements are copied to the new array before the new element is added. + + If `index` is equal to , `item` is added to the end of . + + This method is an O(*n*) operation, where *n* is . + +## Examples + + The following example demonstrates how to add, remove, and insert a simple business object in a . + + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Overview/program.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.list.addremoveinsert/vb/module1.vb" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.collections.generic.list.addremoveinsert/fs/addremoveinsert.fs" id="Snippet1"::: + + The following example demonstrates the method, along with various other properties and methods of the generic class. After the list is created, elements are added. The method is used to insert an item into the middle of the list. The item inserted is a duplicate, which is later removed using the method. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_Class/cpp/source.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Overview/source.cs" interactive="try-dotnet-method" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_Class/vb/source.vb" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR/List`1_Class/fs/listclass.fs" id="Snippet1"::: + ]]> - is less than 0. - - -or- - + is less than 0. + + -or- + is greater than . @@ -2950,35 +2950,35 @@ Public Function StartsWith(e As Employee) As Boolean The collection whose elements should be inserted into the . The collection itself cannot be , but it can contain elements that are , if type is a reference type. Inserts the elements of a collection into the at the specified index. - accepts `null` as a valid value for reference types and allows duplicate elements. - - If the new (the current plus the size of the collection) will be greater than , the capacity of the is increased by automatically reallocating the internal array to accommodate the new elements, and the existing elements are copied to the new array before the new elements are added. - - If `index` is equal to , the elements are added to the end of . - - The order of the elements in the collection is preserved in the . - - This method is an O(*n* * *m*) operation, where *n* is the number of elements to be added and *m* is . - -## Examples - The following example demonstrates method and various other methods of the class that act on ranges. After the list has been created and populated with the names of several peaceful plant-eating dinosaurs, the method is used to insert an array of three ferocious meat-eating dinosaurs into the list, beginning at index location 3. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_Ranges/cpp/source.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/.ctor/source1.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_Ranges/vb/source.vb" id="Snippet1"::: - + accepts `null` as a valid value for reference types and allows duplicate elements. + + If the new (the current plus the size of the collection) will be greater than , the capacity of the is increased by automatically reallocating the internal array to accommodate the new elements, and the existing elements are copied to the new array before the new elements are added. + + If `index` is equal to , the elements are added to the end of . + + The order of the elements in the collection is preserved in the . + + This method is an O(*n* * *m*) operation, where *n* is the number of elements to be added and *m* is . + +## Examples + The following example demonstrates method and various other methods of the class that act on ranges. After the list has been created and populated with the names of several peaceful plant-eating dinosaurs, the method is used to insert an array of three ferocious meat-eating dinosaurs into the list, beginning at index location 3. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_Ranges/cpp/source.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/.ctor/source1.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_Ranges/vb/source.vb" id="Snippet1"::: + ]]> is . - is less than 0. - - -or- - + is less than 0. + + -or- + is greater than . @@ -3042,35 +3042,35 @@ Public Function StartsWith(e As Employee) As Boolean Gets or sets the element at the specified index. The element at the specified index. - accepts `null` as a valid value for reference types and allows duplicate elements. - - This property provides the ability to access a specific element in the collection by using the following syntax: `myCollection[index]`. - - Retrieving the value of this property is an O(1) operation; setting the property is also an O(1) operation. - -## Examples - The example in this section demonstrates the property (the indexer in C#) and various other properties and methods of the generic class. After the list has been created and populated using the method, an element is retrieved and displayed using the property. (For an example that uses the property to set the value of a list element, see .) - -> [!NOTE] -> Visual Basic, C#, and C++ all have syntax for accessing the property without using its name. Instead, the variable containing the is used as if it were an array. - - The C# language uses the [`this`](/dotnet/csharp/language-reference/keywords/this) keyword to define the indexers instead of implementing the property. Visual Basic implements as a default property, which provides the same indexing functionality. - - :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Overview/source.cs" interactive="try-dotnet-method" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_Class/vb/source.vb" id="Snippet2"::: - :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Overview/source.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_Class/vb/source.vb" id="Snippet3"::: - + accepts `null` as a valid value for reference types and allows duplicate elements. + + This property provides the ability to access a specific element in the collection by using the following syntax: `myCollection[index]`. + + Retrieving the value of this property is an O(1) operation; setting the property is also an O(1) operation. + +## Examples + The example in this section demonstrates the property (the indexer in C#) and various other properties and methods of the generic class. After the list has been created and populated using the method, an element is retrieved and displayed using the property. (For an example that uses the property to set the value of a list element, see .) + +> [!NOTE] +> Visual Basic, C#, and C++ all have syntax for accessing the property without using its name. Instead, the variable containing the is used as if it were an array. + + The C# language uses the [`this`](/dotnet/csharp/language-reference/keywords/this) keyword to define the indexers instead of implementing the property. Visual Basic implements as a default property, which provides the same indexing functionality. + + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Overview/source.cs" interactive="try-dotnet-method" id="Snippet2"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_Class/vb/source.vb" id="Snippet2"::: + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Overview/source.cs" id="Snippet3"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_Class/vb/source.vb" id="Snippet3"::: + ]]> - is less than 0. - - -or- - + is less than 0. + + -or- + is equal to or greater than .
@@ -3085,15 +3085,15 @@ Public Function StartsWith(e As Employee) As Boolean Returns the zero-based index of the last occurrence of a value in the or in a portion of it. - method. A of strings is created, with one entry that appears twice, at index location 0 and index location 5. The method overload searches the entire list from the end, and finds the second occurrence of the string. The method overload is used to search the list backward beginning with index location 3 and continuing to the beginning of the list, so it finds the first occurrence of the string in the list. Finally, the method overload is used to search a range of four entries, beginning at index location 4 and extending backward (that is, it searches the items at locations 4, 3, 2, and 1); this search returns -1 because there are no instances of the search string in that range. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_LastIndexOf/cpp/source.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/LastIndexOf/source.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_LastIndexOf/vb/source.vb" id="Snippet1"::: - + method. A of strings is created, with one entry that appears twice, at index location 0 and index location 5. The method overload searches the entire list from the end, and finds the second occurrence of the string. The method overload is used to search the list backward beginning with index location 3 and continuing to the beginning of the list, so it finds the first occurrence of the string in the list. Finally, the method overload is used to search a range of four entries, beginning at index location 4 and extending backward (that is, it searches the items at locations 4, 3, 2, and 1); this search returns -1 because there are no instances of the search string in that range. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_LastIndexOf/cpp/source.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/LastIndexOf/source.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_LastIndexOf/vb/source.vb" id="Snippet1"::: + ]]> @@ -3141,15 +3141,15 @@ Public Function StartsWith(e As Employee) As Boolean Searches for the specified object and returns the zero-based index of the last occurrence within the entire . The zero-based index of the last occurrence of within the entire the , if found; otherwise, -1. - is searched backward starting at the last element and ending at the first element. - - This method determines equality using the default equality comparer for `T`, the type of values in the list. - - This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is . - + is searched backward starting at the last element and ending at the first element. + + This method determines equality using the default equality comparer for `T`, the type of values in the list. + + This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is . + ]]> @@ -3202,15 +3202,15 @@ Public Function StartsWith(e As Employee) As Boolean Searches for the specified object and returns the zero-based index of the last occurrence within the range of elements in the that extends from the first element to the specified index. The zero-based index of the last occurrence of within the range of elements in the that extends from the first element to , if found; otherwise, -1. - is searched backward starting at `index` and ending at the first element. - - This method determines equality using the default equality comparer for `T`, the type of values in the list. - - This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is the number of elements from the beginning of the to `index`. - + is searched backward starting at `index` and ending at the first element. + + This method determines equality using the default equality comparer for `T`, the type of values in the list. + + This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is the number of elements from the beginning of the to `index`. + ]]> @@ -3267,26 +3267,26 @@ Public Function StartsWith(e As Employee) As Boolean Searches for the specified object and returns the zero-based index of the last occurrence within the range of elements in the that contains the specified number of elements and ends at the specified index. The zero-based index of the last occurrence of within the range of elements in the that contains number of elements and ends at , if found; otherwise, -1. - is searched backward starting at `index` and ending at `index` minus `count` plus 1, if `count` is greater than 0. - - This method determines equality using the default equality comparer for `T`, the type of values in the list. - - This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is `count`. - + is searched backward starting at `index` and ending at `index` minus `count` plus 1, if `count` is greater than 0. + + This method determines equality using the default equality comparer for `T`, the type of values in the list. + + This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is `count`. + ]]> - is outside the range of valid indexes for the . - - -or- - - is less than 0. - - -or- - + is outside the range of valid indexes for the . + + -or- + + is less than 0. + + -or- + and do not specify a valid section in the . @@ -3346,28 +3346,28 @@ Public Function StartsWith(e As Employee) As Boolean if is successfully removed; otherwise, . This method also returns if was not found in the . - generic interface, the equality comparer is the method of that interface; otherwise, the default equality comparer is . - - This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is . - -## Examples - - The following example demonstrates how to add, remove, and insert a simple business object in a . - - :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Overview/program.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.list.addremoveinsert/vb/module1.vb" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.collections.generic.list.addremoveinsert/fs/addremoveinsert.fs" id="Snippet1"::: - - The following example demonstrates method. Several properties and methods of the generic class are used to add, insert, and search the list. After these operations, the list contains a duplicate. The method is used to remove the first instance of the duplicate item, and the contents are displayed. The method always removes the first instance it encounters. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_Class/cpp/source.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Overview/source.cs" interactive="try-dotnet-method" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_Class/vb/source.vb" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR/List`1_Class/fs/listclass.fs" id="Snippet1"::: - + generic interface, the equality comparer is the method of that interface; otherwise, the default equality comparer is . + + This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is . + +## Examples + + The following example demonstrates how to add, remove, and insert a simple business object in a . + + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Overview/program.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.list.addremoveinsert/vb/module1.vb" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.collections.generic.list.addremoveinsert/fs/addremoveinsert.fs" id="Snippet1"::: + + The following example demonstrates method. Several properties and methods of the generic class are used to add, insert, and search the list. After these operations, the list contains a duplicate. The method is used to remove the first instance of the duplicate item, and the contents are displayed. The method always removes the first instance it encounters. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_Class/cpp/source.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Overview/source.cs" interactive="try-dotnet-method" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_Class/vb/source.vb" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR/List`1_Class/fs/listclass.fs" id="Snippet1"::: + ]]> @@ -3420,31 +3420,31 @@ Public Function StartsWith(e As Employee) As Boolean Removes all the elements that match the conditions defined by the specified predicate. The number of elements removed from the . - is a delegate to a method that returns `true` if the object passed to it matches the conditions defined in the delegate. The elements of the current are individually passed to the delegate, and the elements that match the conditions are removed from the . - - This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is . - -## Examples - The following example demonstrates the method and several other methods that use the generic delegate. - - A of strings is created, containing 8 dinosaur names, two of which (at positions 1 and 5) end with "saurus". The example also defines a search predicate method named `EndsWithSaurus`, which accepts a string parameter and returns a Boolean value indicating whether the input string ends in "saurus". - - The , , and methods are used to search the list with the search predicate method. - - The method is used to remove all entries ending with "saurus". It traverses the list from the beginning, passing each element in turn to the `EndsWithSaurus` method. The element is removed if the `EndsWithSaurus` method returns `true`. - -> [!NOTE] -> In C# and Visual Basic, it is not necessary to create the `Predicate` delegate (`Predicate(Of String)` in Visual Basic) explicitly. These languages infer the correct delegate from context, and create it automatically. - - Finally, the method verifies that there are no strings in the list that end with "saurus". - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_FindEtAl/cpp/source.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Exists/source.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_FindEtAl/vb/source.vb" id="Snippet1"::: - + is a delegate to a method that returns `true` if the object passed to it matches the conditions defined in the delegate. The elements of the current are individually passed to the delegate, and the elements that match the conditions are removed from the . + + This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is . + +## Examples + The following example demonstrates the method and several other methods that use the generic delegate. + + A of strings is created, containing 8 dinosaur names, two of which (at positions 1 and 5) end with "saurus". The example also defines a search predicate method named `EndsWithSaurus`, which accepts a string parameter and returns a Boolean value indicating whether the input string ends in "saurus". + + The , , and methods are used to search the list with the search predicate method. + + The method is used to remove all entries ending with "saurus". It traverses the list from the beginning, passing each element in turn to the `EndsWithSaurus` method. The element is removed if the `EndsWithSaurus` method returns `true`. + +> [!NOTE] +> In C# and Visual Basic, it is not necessary to create the `Predicate` delegate (`Predicate(Of String)` in Visual Basic) explicitly. These languages infer the correct delegate from context, and create it automatically. + + Finally, the method verifies that there are no strings in the list that end with "saurus". + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_FindEtAl/cpp/source.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Exists/source.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_FindEtAl/vb/source.vb" id="Snippet1"::: + ]]> @@ -3502,27 +3502,27 @@ Public Function StartsWith(e As Employee) As Boolean The zero-based index of the element to remove. Removes the element at the specified index of the . - to remove an item, the remaining items in the list are renumbered to replace the removed item. For example, if you remove the item at index 3, the item at index 4 is moved to the 3 position. In addition, the number of items in the list (as represented by the property) is reduced by 1. - - This method is an O(*n*) operation, where *n* is ( - `index`). - -## Examples - The following example demonstrates how to add, remove, and insert a simple business object in a . - - :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Overview/program.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.list.addremoveinsert/vb/module1.vb" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.collections.generic.list.addremoveinsert/fs/addremoveinsert.fs" id="Snippet1"::: - + to remove an item, the remaining items in the list are renumbered to replace the removed item. For example, if you remove the item at index 3, the item at index 4 is moved to the 3 position. In addition, the number of items in the list (as represented by the property) is reduced by 1. + + This method is an O(*n*) operation, where *n* is ( - `index`). + +## Examples + The following example demonstrates how to add, remove, and insert a simple business object in a . + + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Overview/program.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.list.addremoveinsert/vb/module1.vb" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.collections.generic.list.addremoveinsert/fs/addremoveinsert.fs" id="Snippet1"::: + ]]> - is less than 0. - - -or- - + is less than 0. + + -or- + is equal to or greater than . @@ -3574,27 +3574,27 @@ Public Function StartsWith(e As Employee) As Boolean The number of elements to remove. Removes a range of elements from the . - have their indexes reduced by `count`. - - This method is an O(*n*) operation, where *n* is . - -## Examples - The following example demonstrates the method and various other methods of the class that act on ranges. After the list has been created and modified, the method is used to remove two elements from the list, beginning at index location 2. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_Ranges/cpp/source.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/.ctor/source1.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_Ranges/vb/source.vb" id="Snippet1"::: - + have their indexes reduced by `count`. + + This method is an O(*n*) operation, where *n* is . + +## Examples + The following example demonstrates the method and various other methods of the class that act on ranges. After the list has been created and modified, the method is used to remove two elements from the list, beginning at index location 2. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_Ranges/cpp/source.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/.ctor/source1.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_Ranges/vb/source.vb" id="Snippet1"::: + ]]> - is less than 0. - - -or- - + is less than 0. + + -or- + is less than 0. and do not denote a valid range of elements in the . @@ -3615,15 +3615,15 @@ Public Function StartsWith(e As Employee) As Boolean Reverses the order of the elements in the or a portion of it. - method. The example creates a of strings and adds six strings. The method overload is used to reverse the list, and then the method overload is used to reverse the middle of the list, beginning with element 1 and encompassing four elements. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_Reverse/cpp/source.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Reverse/source.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_Reverse/vb/source.vb" id="Snippet1"::: - + method. The example creates a of strings and adds six strings. The method overload is used to reverse the list, and then the method overload is used to reverse the middle of the list, beginning with element 1 and encompassing four elements. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_Reverse/cpp/source.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Reverse/source.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_Reverse/vb/source.vb" id="Snippet1"::: + ]]> @@ -3667,13 +3667,13 @@ Public Function StartsWith(e As Employee) As Boolean Reverses the order of the elements in the entire . - to reverse the order of the elements. - - This method is an O(*n*) operation, where *n* is . - + to reverse the order of the elements. + + This method is an O(*n*) operation, where *n* is . + ]]> @@ -3722,20 +3722,20 @@ Public Function StartsWith(e As Employee) As Boolean The number of elements in the range to reverse. Reverses the order of the elements in the specified range. - to reverse the order of the elements. - - This method is an O(*n*) operation, where *n* is . - + to reverse the order of the elements. + + This method is an O(*n*) operation, where *n* is . + ]]> - is less than 0. - - -or- - + is less than 0. + + -or- + is less than 0. and do not denote a valid range of elements in the . @@ -3774,10 +3774,10 @@ Public Function StartsWith(e As Employee) As Boolean A shallow copy of a range of elements in the source . To be added. - is less than 0. - --or- - + is less than 0. + +-or- + is less than 0. and do not denote a valid range of elements in the . @@ -3832,43 +3832,43 @@ Public Function StartsWith(e As Employee) As Boolean Sorts the elements in the entire using the default comparer. - for type `T` to determine the order of list elements. The property checks whether type `T` implements the generic interface and uses that implementation, if available. If not, checks whether type `T` implements the interface. If type `T` does not implement either interface, throws an . - - This method uses the method, which applies the introspective sort as follows: - -- If the partition size is less than or equal to 16 elements, it uses an insertion sort algorithm. - -- If the number of partitions exceeds 2 log *n*, where *n* is the range of the input array, it uses a Heapsort algorithm. - -- Otherwise, it uses a Quicksort algorithm. - - This implementation performs an unstable sort; that is, if two elements are equal, their order might not be preserved. In contrast, a stable sort preserves the order of elements that are equal. - - This method is an O(*n* log *n*) operation, where *n* is . - -## Examples - - The following example adds some names to a `List` object, displays the list in unsorted order, calls the method, and then displays the sorted list. - - :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Sort/Sort1.cs" interactive="try-dotnet-method" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.list.sort/vb/Sort1.vb" id="Snippet2"::: - - The following code demonstrates the and method overloads on a simple business object. Calling the method results in the use of the default comparer for the Part type, and the method is implemented by using an anonymous method. - - :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Sort/program.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.list.sort/vb/module1.vb" id="Snippet1"::: - - The following example demonstrates the method overload and the method overload. A of strings is created and populated with four strings, in no particular order. The list is displayed, sorted, and displayed again. - - The method overload is then used to search for two strings that are not in the list, and the method is used to insert them. The return value of the method is negative in each case, because the strings are not in the list. Taking the bitwise complement (the ~ operator in C# and Visual C++, `Xor` -1 in Visual Basic) of this negative number produces the index of the first element in the list that is larger than the search string, and inserting at this location preserves the sort order. The second search string is larger than any element in the list, so the insertion position is at the end of the list. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_SortSearch/cpp/source.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/BinarySearch/source.cs" interactive="try-dotnet-method" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_SortSearch/vb/source.vb" id="Snippet1"::: - + for type `T` to determine the order of list elements. The property checks whether type `T` implements the generic interface and uses that implementation, if available. If not, checks whether type `T` implements the interface. If type `T` does not implement either interface, throws an . + + This method uses the method, which applies the introspective sort as follows: + +- If the partition size is less than or equal to 16 elements, it uses an insertion sort algorithm. + +- If the number of partitions exceeds 2 log *n*, where *n* is the range of the input array, it uses a Heapsort algorithm. + +- Otherwise, it uses a Quicksort algorithm. + + This implementation performs an unstable sort; that is, if two elements are equal, their order might not be preserved. In contrast, a stable sort preserves the order of elements that are equal. + + This method is an O(*n* log *n*) operation, where *n* is . + +## Examples + + The following example adds some names to a `List` object, displays the list in unsorted order, calls the method, and then displays the sorted list. + + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Sort/Sort1.cs" interactive="try-dotnet-method" id="Snippet2"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.list.sort/vb/Sort1.vb" id="Snippet2"::: + + The following code demonstrates the and method overloads on a simple business object. Calling the method results in the use of the default comparer for the Part type, and the method is implemented by using an anonymous method. + + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Sort/program.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.list.sort/vb/module1.vb" id="Snippet1"::: + + The following example demonstrates the method overload and the method overload. A of strings is created and populated with four strings, in no particular order. The list is displayed, sorted, and displayed again. + + The method overload is then used to search for two strings that are not in the list, and the method is used to insert them. The return value of the method is negative in each case, because the strings are not in the list. Taking the bitwise complement (the ~ operator in C# and Visual C++, `Xor` -1 in Visual Basic) of this negative number produces the index of the first element in the list that is larger than the search string, and inserting at this location preserves the sort order. The second search string is larger than any element in the list, so the insertion position is at the end of the list. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_SortSearch/cpp/source.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/BinarySearch/source.cs" interactive="try-dotnet-method" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_SortSearch/vb/source.vb" id="Snippet1"::: + ]]> The default comparer cannot find an implementation of the generic interface or the interface for type . @@ -3925,38 +3925,38 @@ Public Function StartsWith(e As Employee) As Boolean The implementation to use when comparing elements, or to use the default comparer . Sorts the elements in the entire using the specified comparer. - are sorted using the specified implementation. - - If `comparer` is `null`, the default comparer checks whether type `T` implements the generic interface and uses that implementation, if available. If not, checks whether type `T` implements the interface. If type `T` does not implement either interface, throws an . - - This method uses the method, which applies the introspective sort as follows: - -- If the partition size is less than or equal to 16 elements, it uses an insertion sort algorithm. - -- If the number of partitions exceeds 2 log *n*, where *n* is the range of the input array, it uses a Heapsort algorithm. - -- Otherwise, it uses a Quicksort algorithm. - - This implementation performs an unstable sort; that is, if two elements are equal, their order might not be preserved. In contrast, a stable sort preserves the order of elements that are equal. - - This method is an O(*n* log *n*) operation, where *n* is . - -## Examples - The following example demonstrates the method overload and the method overload. - - The example defines an alternative comparer for strings named DinoCompare, which implements the `IComparer` (`IComparer(Of String)` in Visual Basic, `IComparer` in Visual C++) generic interface. The comparer works as follows: First, the comparands are tested for `null`, and a null reference is treated as less than a non-null. Second, the string lengths are compared, and the longer string is deemed to be greater. Third, if the lengths are equal, ordinary string comparison is used. - - A of strings is created and populated with four strings, in no particular order. The list is displayed, sorted using the alternate comparer, and displayed again. - - The method overload is then used to search for several strings that are not in the list, employing the alternate comparer. The method is used to insert the strings. These two methods are located in the function named `SearchAndInsert`, along with code to take the bitwise complement (the ~ operator in C# and Visual C++, `Xor` -1 in Visual Basic) of the negative number returned by and use it as an index for inserting the new string. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_SortSearchComparer/cpp/source.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/BinarySearch/source1.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_SortSearchComparer/vb/source.vb" id="Snippet1"::: - + are sorted using the specified implementation. + + If `comparer` is `null`, the default comparer checks whether type `T` implements the generic interface and uses that implementation, if available. If not, checks whether type `T` implements the interface. If type `T` does not implement either interface, throws an . + + This method uses the method, which applies the introspective sort as follows: + +- If the partition size is less than or equal to 16 elements, it uses an insertion sort algorithm. + +- If the number of partitions exceeds 2 log *n*, where *n* is the range of the input array, it uses a Heapsort algorithm. + +- Otherwise, it uses a Quicksort algorithm. + + This implementation performs an unstable sort; that is, if two elements are equal, their order might not be preserved. In contrast, a stable sort preserves the order of elements that are equal. + + This method is an O(*n* log *n*) operation, where *n* is . + +## Examples + The following example demonstrates the method overload and the method overload. + + The example defines an alternative comparer for strings named DinoCompare, which implements the `IComparer` (`IComparer(Of String)` in Visual Basic, `IComparer` in Visual C++) generic interface. The comparer works as follows: First, the comparands are tested for `null`, and a null reference is treated as less than a non-null. Second, the string lengths are compared, and the longer string is deemed to be greater. Third, if the lengths are equal, ordinary string comparison is used. + + A of strings is created and populated with four strings, in no particular order. The list is displayed, sorted using the alternate comparer, and displayed again. + + The method overload is then used to search for several strings that are not in the list, employing the alternate comparer. The method is used to insert the strings. These two methods are located in the function named `SearchAndInsert`, along with code to take the bitwise complement (the ~ operator in C# and Visual C++, `Xor` -1 in Visual Basic) of the negative number returned by and use it as an index for inserting the new string. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_SortSearchComparer/cpp/source.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/BinarySearch/source1.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_SortSearchComparer/vb/source.vb" id="Snippet1"::: + ]]> @@ -4007,41 +4007,41 @@ Public Function StartsWith(e As Employee) As Boolean The to use when comparing elements. Sorts the elements in the entire using the specified . - are sorted using the method represented by the delegate. - - If `comparison` is `null`, an is thrown. - - This method uses , which applies the introspective sort as follows: - -- If the partition size is less than or equal to 16 elements, it uses an insertion sort algorithm - -- If the number of partitions exceeds 2 log *n*, where *n* is the range of the input array, it uses a [Heapsort](https://en.wikipedia.org/wiki/Heapsort) algorithm. - -- Otherwise, it uses a Quicksort algorithm. - - This implementation performs an unstable sort; that is, if two elements are equal, their order might not be preserved. In contrast, a stable sort preserves the order of elements that are equal. - - This method is an O(*n* log *n*) operation, where *n* is . - -## Examples - The following code demonstrates the and method overloads on a simple business object. Calling the method results in the use of the default comparer for the Part type, and the method is implemented using an anonymous method. - - :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Sort/program.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.list.sort/vb/module1.vb" id="Snippet1"::: - - The following example demonstrates the method overload. - - The example defines an alternative comparison method for strings, named `CompareDinosByLength`. This method works as follows: First, the comparands are tested for `null`, and a null reference is treated as less than a non-null. Second, the string lengths are compared, and the longer string is deemed to be greater. Third, if the lengths are equal, ordinary string comparison is used. - - A of strings is created and populated with four strings, in no particular order. The list also includes an empty string and a null reference. The list is displayed, sorted using a generic delegate representing the `CompareDinosByLength` method, and displayed again. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_SortComparison/cpp/source.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/ComparisonT/Overview/source.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_SortComparison/vb/source.vb" id="Snippet1"::: - + are sorted using the method represented by the delegate. + + If `comparison` is `null`, an is thrown. + + This method uses , which applies the introspective sort as follows: + +- If the partition size is less than or equal to 16 elements, it uses an insertion sort algorithm + +- If the number of partitions exceeds 2 log *n*, where *n* is the range of the input array, it uses a [Heapsort](https://en.wikipedia.org/wiki/Heapsort) algorithm. + +- Otherwise, it uses a Quicksort algorithm. + + This implementation performs an unstable sort; that is, if two elements are equal, their order might not be preserved. In contrast, a stable sort preserves the order of elements that are equal. + + This method is an O(*n* log *n*) operation, where *n* is . + +## Examples + The following code demonstrates the and method overloads on a simple business object. Calling the method results in the use of the default comparer for the Part type, and the method is implemented using an anonymous method. + + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Sort/program.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.list.sort/vb/module1.vb" id="Snippet1"::: + + The following example demonstrates the method overload. + + The example defines an alternative comparison method for strings, named `CompareDinosByLength`. This method works as follows: First, the comparands are tested for `null`, and a null reference is treated as less than a non-null. Second, the string lengths are compared, and the longer string is deemed to be greater. Third, if the lengths are equal, ordinary string comparison is used. + + A of strings is created and populated with four strings, in no particular order. The list also includes an empty string and a null reference. The list is displayed, sorted using a generic delegate representing the `CompareDinosByLength` method, and displayed again. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_SortComparison/cpp/source.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System/ComparisonT/Overview/source.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_SortComparison/vb/source.vb" id="Snippet1"::: + ]]> @@ -4105,51 +4105,51 @@ Public Function StartsWith(e As Employee) As Boolean The implementation to use when comparing elements, or to use the default comparer . Sorts the elements in a range of elements in using the specified comparer. - are sorted using the specified implementation. - - If `comparer` is `null`, the default comparer checks whether type `T` implements the generic interface and uses that implementation, if available. If not, checks whether type `T` implements the interface. If type `T` does not implement either interface, throws an . - - This method uses , which applies the introspective sort as follows: - -- If the partition size is less than or equal to 16 elements, it uses an insertion sort algorithm - -- If the number of partitions exceeds 2 log *n*, where *n* is the range of the input array, it uses a [Heapsort](https://en.wikipedia.org/wiki/Heapsort) algorithm. - -- Otherwise, it uses a Quicksort algorithm. - - This implementation performs an unstable sort; that is, if two elements are equal, their order might not be preserved. In contrast, a stable sort preserves the order of elements that are equal. - - This method is an O(*n* log *n*) operation, where *n* is . - -## Examples - The following example demonstrates the method overload and the method overload. - - The example defines an alternative comparer for strings named DinoCompare, which implements the `IComparer` (`IComparer(Of String)` in Visual Basic, `IComparer` in Visual C++) generic interface. The comparer works as follows: First, the comparands are tested for `null`, and a null reference is treated as less than a non-null. Second, the string lengths are compared, and the longer string is deemed to be greater. Third, if the lengths are equal, ordinary string comparison is used. - - A of strings is created and populated with the names of five herbivorous dinosaurs and three carnivorous dinosaurs. Within each of the two groups, the names are not in any particular sort order. The list is displayed, the range of herbivores is sorted using the alternate comparer, and the list is displayed again. - - The method overload is then used to search only the range of herbivores for "Brachiosaurus". The string is not found, and the bitwise complement (the ~ operator in C# and Visual C++, `Xor` -1 in Visual Basic) of the negative number returned by the method is used as an index for inserting the new string. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_SortSearchComparerRange/cpp/source.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/BinarySearch/source2.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_SortSearchComparerRange/vb/source.vb" id="Snippet1"::: - + are sorted using the specified implementation. + + If `comparer` is `null`, the default comparer checks whether type `T` implements the generic interface and uses that implementation, if available. If not, checks whether type `T` implements the interface. If type `T` does not implement either interface, throws an . + + This method uses , which applies the introspective sort as follows: + +- If the partition size is less than or equal to 16 elements, it uses an insertion sort algorithm + +- If the number of partitions exceeds 2 log *n*, where *n* is the range of the input array, it uses a [Heapsort](https://en.wikipedia.org/wiki/Heapsort) algorithm. + +- Otherwise, it uses a Quicksort algorithm. + + This implementation performs an unstable sort; that is, if two elements are equal, their order might not be preserved. In contrast, a stable sort preserves the order of elements that are equal. + + This method is an O(*n* log *n*) operation, where *n* is . + +## Examples + The following example demonstrates the method overload and the method overload. + + The example defines an alternative comparer for strings named DinoCompare, which implements the `IComparer` (`IComparer(Of String)` in Visual Basic, `IComparer` in Visual C++) generic interface. The comparer works as follows: First, the comparands are tested for `null`, and a null reference is treated as less than a non-null. Second, the string lengths are compared, and the longer string is deemed to be greater. Third, if the lengths are equal, ordinary string comparison is used. + + A of strings is created and populated with the names of five herbivorous dinosaurs and three carnivorous dinosaurs. Within each of the two groups, the names are not in any particular sort order. The list is displayed, the range of herbivores is sorted using the alternate comparer, and the list is displayed again. + + The method overload is then used to search only the range of herbivores for "Brachiosaurus". The string is not found, and the bitwise complement (the ~ operator in C# and Visual C++, `Xor` -1 in Visual Basic) of the negative number returned by the method is used as an index for inserting the new string. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_SortSearchComparerRange/cpp/source.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/BinarySearch/source2.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_SortSearchComparerRange/vb/source.vb" id="Snippet1"::: + ]]> - is less than 0. - - -or- - + is less than 0. + + -or- + is less than 0. - and do not specify a valid range in the . - - -or- - + and do not specify a valid range in the . + + -or- + The implementation of caused an error during the sort. For example, might not return 0 when comparing an item with itself. is , and the default comparer cannot find implementation of the generic interface or the interface for type . @@ -4205,15 +4205,15 @@ Public Function StartsWith(e As Employee) As Boolean if the is read-only; otherwise, . In the default implementation of , this property always returns . - @@ -4267,27 +4267,27 @@ Public Function StartsWith(e As Employee) As Boolean Returns an enumerator that iterates through a collection. An that can be used to iterate through the collection. - 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 . - - The property returns the same object until 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. You cannot set to the first element of the collection again; you must create a new enumerator instance instead. - - 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 enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - - Default implementations of collections in the namespace are not synchronized. - - This method is an O(1) operation. - + 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 . + + The property returns the same object until 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. You cannot set to the first element of the collection again; you must create a new enumerator instance instead. + + 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 enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. + + Default implementations of collections in the namespace are not synchronized. + + This method is an O(1) operation. + ]]> @@ -4346,15 +4346,15 @@ Public Function StartsWith(e As Employee) As Boolean The zero-based index in at which copying begins. Copies the elements of the to an , starting at a particular index. - [!NOTE] -> If the type of the source cannot be cast automatically to the type of the destination `array`, the nongeneric implementations of throw , whereas the generic implementations throw . - - This method is an O(*n*) operation, where *n* is . - + [!NOTE] +> If the type of the source cannot be cast automatically to the type of the destination `array`, the nongeneric implementations of throw , whereas the generic implementations throw . + + This method is an O(*n*) operation, where *n* is . + ]]> @@ -4362,18 +4362,18 @@ Public Function StartsWith(e As Employee) As Boolean is less than 0. - is multidimensional. - - -or- - - does not have zero-based indexing. - - -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- + + does not have zero-based indexing. + + -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 .
@@ -4420,17 +4420,17 @@ Public Function StartsWith(e As Employee) As Boolean if access to the is synchronized (thread safe); otherwise, . In the default implementation of , this property always returns . - namespace are not synchronized. - - Enumerating through a collection is intrinsically not a thread-safe procedure. In the rare case where enumeration contends with write accesses, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - - returns an object that can be used to synchronize access to the . Synchronization is effective only if all threads lock this object before accessing the collection. - - Retrieving the value of this property is an O(1) operation. - + namespace are not synchronized. + + Enumerating through a collection is intrinsically not a thread-safe procedure. In the rare case where enumeration contends with write accesses, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. + + returns an object that can be used to synchronize access to the . Synchronization is effective only if all threads lock this object before accessing the collection. + + Retrieving the value of this property is an O(1) operation. + ]]> @@ -4478,45 +4478,45 @@ Public Function StartsWith(e As Employee) As Boolean Gets an object that can be used to synchronize access to the . An object that can be used to synchronize access to the . In the default implementation of , this property always returns the current instance. - namespace are not synchronized. - - Enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - - returns an object that can be used to synchronize access to the . Synchronization is effective only if all threads lock this object before accessing the collection. The following code shows the use of the property for C#, C++, and Visual Basic. - -```csharp -ICollection ic = ...; -lock (ic.SyncRoot) -{ - // Access the collection. -} -``` - -```vb -Dim ic As ICollection = ... -SyncLock ic.SyncRoot - ' Access the collection. -End SyncLock -``` - -```cpp -ICollection^ ic = ...; -try -{ - Monitor::Enter(ic->SyncRoot); - // Access the collection. -} -finally -{ - Monitor::Exit(ic->SyncRoot); -} -``` - - Retrieving the value of this property is an O(1) operation. - + namespace are not synchronized. + + Enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. + + returns an object that can be used to synchronize access to the . Synchronization is effective only if all threads lock this object before accessing the collection. The following code shows the use of the property for C#, C++, and Visual Basic. + +```csharp +ICollection ic = ...; +lock (ic.SyncRoot) +{ + // Access the collection. +} +``` + +```vb +Dim ic As ICollection = ... +SyncLock ic.SyncRoot + ' Access the collection. +End SyncLock +``` + +```cpp +ICollection^ ic = ...; +try +{ + Monitor::Enter(ic->SyncRoot); + // Access the collection. +} +finally +{ + Monitor::Exit(ic->SyncRoot); +} +``` + + Retrieving the value of this property is an O(1) operation. + ]]> @@ -4571,27 +4571,27 @@ finally Returns an enumerator that iterates through a collection. An that can be used to iterate through the collection. - 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 . - - The property 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 . - - 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 enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - - Default implementations of collections in the namespace are not synchronized. - - This method is an O(1) operation. - + 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 . + + The property 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 . + + 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 enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. + + Default implementations of collections in the namespace are not synchronized. + + This method is an O(1) operation. + ]]> @@ -4643,11 +4643,11 @@ finally Adds an item to the . The position into which the new element was inserted. - is less than , this method is an O(1) operation. If the capacity needs to be increased to accommodate the new element, this method becomes an O(*n*) operation, where *n* is . - + is less than , this method is an O(1) operation. If the capacity needs to be increased to accommodate the new element, this method becomes an O(*n*) operation, where *n* is . + ]]> @@ -4707,13 +4707,13 @@ finally if is found in the ; otherwise, . - for `T`, the type of values in the list. - - This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is . - + for `T`, the type of values in the list. + + This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is . + ]]>
@@ -4774,13 +4774,13 @@ finally Determines the index of a specific item in the . The index of if found in the list; otherwise, -1. - for `T`, the type of values in the list. - - This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is . - + for `T`, the type of values in the list. + + This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is . + ]]> @@ -4834,13 +4834,13 @@ finally The object to insert into the . Inserts an item to the at the specified index. - , then `item` is appended to the end. - - This method is an O(*n*) operation, where *n* is . - + , then `item` is appended to the end. + + This method is an O(*n*) operation, where *n* is . + ]]> @@ -4892,15 +4892,15 @@ finally if the has a fixed size; otherwise, . In the default implementation of , this property always returns . -
@@ -4954,15 +4954,15 @@ finally if the is read-only; otherwise, . In the default implementation of , this property always returns . -
@@ -5020,13 +5020,13 @@ finally Gets or sets the element at the specified index. The element at the specified index. - property. Visual Basic implements as a default property, which provides the same indexing functionality. - - Retrieving the value of this property is an O(1) operation; setting the property is also an O(1) operation. - + property. Visual Basic implements as a default property, which provides the same indexing functionality. + + Retrieving the value of this property is an O(1) operation; setting the property is also an O(1) operation. + ]]> @@ -5085,13 +5085,13 @@ finally The object to remove from the . Removes the first occurrence of a specific object from the . - for `T`, the type of values in the list. - - This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is . - + for `T`, the type of values in the list. + + This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is . + ]]> @@ -5138,20 +5138,20 @@ finally Copies the elements of the to a new array. An array containing copies of the elements of the . - , which is an O(*n*) operation, where *n* is . - - This method is an O(*n*) operation, where *n* is . - -## Examples - The following example demonstrates the method and other methods of the class that act on ranges. At the end of the example, the method is used to get three items from the list, beginning with index location 2. The method is called on the resulting , creating an array of three elements. The elements of the array are displayed. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_Ranges/cpp/source.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/.ctor/source1.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_Ranges/vb/source.vb" id="Snippet1"::: - + , which is an O(*n*) operation, where *n* is . + + This method is an O(*n*) operation, where *n* is . + +## Examples + The following example demonstrates the method and other methods of the class that act on ranges. At the end of the example, the method is used to get three items from the list, beginning with index location 2. The method is called on the resulting , creating an array of three elements. The elements of the array are displayed. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_Ranges/cpp/source.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/.ctor/source1.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_Ranges/vb/source.vb" id="Snippet1"::: + ]]>
@@ -5195,34 +5195,34 @@ finally Sets the capacity to the actual number of elements in the , if that number is less than a threshold value. - can be considerable, however, so the method does nothing if the list is at more than 90 percent of capacity. This avoids incurring a large reallocation cost for a relatively small gain. - -> [!NOTE] -> The current threshold of 90 percent might change in future releases. - - This method is an O(*n*) operation, where *n* is . - - To reset a to its initial state, call the method before calling the method. Trimming an empty sets the capacity of the to the default capacity. - - The capacity can also be set using the property. - -## Examples - - The following example demonstrates how to check the capacity and count of a that contains a simple business object, and illustrates using the method to remove extra capacity. - - :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Capacity/program.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.list.capacitycount/vb/module1.vb" id="Snippet1"::: - - The following example demonstrates the method. Several properties and methods of the class are used to add, insert, and remove items from a list of strings. Then the method is used to reduce the capacity to match the count, and the and properties are displayed. If the unused capacity had been less than 10 percent of total capacity, the list would not have been resized. Finally, the contents of the list are cleared. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_Class/cpp/source.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Overview/source.cs" interactive="try-dotnet-method" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_Class/vb/source.vb" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR/List`1_Class/fs/listclass.fs" id="Snippet1"::: - + can be considerable, however, so the method does nothing if the list is at more than 90 percent of capacity. This avoids incurring a large reallocation cost for a relatively small gain. + +> [!NOTE] +> The current threshold of 90 percent might change in future releases. + + This method is an O(*n*) operation, where *n* is . + + To reset a to its initial state, call the method before calling the method. Trimming an empty sets the capacity of the to the default capacity. + + The capacity can also be set using the property. + +## Examples + + The following example demonstrates how to check the capacity and count of a that contains a simple business object, and illustrates using the method to remove extra capacity. + + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Capacity/program.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.list.capacitycount/vb/module1.vb" id="Snippet1"::: + + The following example demonstrates the method. Several properties and methods of the class are used to add, insert, and remove items from a list of strings. Then the method is used to reduce the capacity to match the count, and the and properties are displayed. If the unused capacity had been less than 10 percent of total capacity, the list would not have been resized. Finally, the contents of the list are cleared. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_Class/cpp/source.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Overview/source.cs" interactive="try-dotnet-method" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_Class/vb/source.vb" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR/List`1_Class/fs/listclass.fs" id="Snippet1"::: + ]]> @@ -5274,27 +5274,27 @@ finally if every element in the matches the conditions defined by the specified predicate; otherwise, . If the list has no elements, the return value is . - is a delegate to a method that returns `true` if the object passed to it matches the conditions defined in the delegate. The elements of the current are individually passed to the delegate, and processing is stopped when the delegate returns `false` for any element. The elements are processed in order, and all calls are made on a single thread. - - This method is an O(*n*) operation, where *n* is . - -## Examples - The following example demonstrates the method and several other methods that use generic delegate. - - A of strings is created, containing 8 dinosaur names, two of which (at positions 1 and 5) end with "saurus". The example also defines a search predicate method named `EndsWithSaurus`, which accepts a string parameter and returns a Boolean value indicating whether the input string ends in "saurus". - - The method traverses the list from the beginning, passing each element in turn to the `EndsWithSaurus` method. The search stops when the `EndsWithSaurus` method returns `false`. - -> [!NOTE] -> In C# and Visual Basic, it is not necessary to create the `Predicate` delegate (`Predicate(Of String)` in Visual Basic) explicitly. These languages infer the correct delegate from context and create it automatically. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_FindEtAl/cpp/source.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Exists/source.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_FindEtAl/vb/source.vb" id="Snippet1"::: - + is a delegate to a method that returns `true` if the object passed to it matches the conditions defined in the delegate. The elements of the current are individually passed to the delegate, and processing is stopped when the delegate returns `false` for any element. The elements are processed in order, and all calls are made on a single thread. + + This method is an O(*n*) operation, where *n* is . + +## Examples + The following example demonstrates the method and several other methods that use generic delegate. + + A of strings is created, containing 8 dinosaur names, two of which (at positions 1 and 5) end with "saurus". The example also defines a search predicate method named `EndsWithSaurus`, which accepts a string parameter and returns a Boolean value indicating whether the input string ends in "saurus". + + The method traverses the list from the beginning, passing each element in turn to the `EndsWithSaurus` method. The search stops when the `EndsWithSaurus` method returns `false`. + +> [!NOTE] +> In C# and Visual Basic, it is not necessary to create the `Predicate` delegate (`Predicate(Of String)` in Visual Basic) explicitly. These languages infer the correct delegate from context and create it automatically. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/List`1_FindEtAl/cpp/source.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Exists/source.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/List`1_FindEtAl/vb/source.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.Collections.Generic/SortedSet`1+Enumerator.xml b/xml/System.Collections.Generic/SortedSet`1+Enumerator.xml index 28e828085aa..ed3ddef097f 100644 --- a/xml/System.Collections.Generic/SortedSet`1+Enumerator.xml +++ b/xml/System.Collections.Generic/SortedSet`1+Enumerator.xml @@ -86,25 +86,25 @@ Enumerates the elements of a object. - 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 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. You cannot set to the first element of the collection again; you must create a new enumerator object instead. - - 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 enumerator doesn't have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - - Default implementations of collections in the namespace are not synchronized. - + 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 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. You cannot set to the first element of the collection again; you must create a new enumerator object instead. + + 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 enumerator doesn't have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. + + Default implementations of collections in the namespace are not synchronized. + ]]> @@ -160,20 +160,20 @@ Gets the element at the current position of the enumerator. The element in the collection at the current position of the enumerator. - is undefined under any of the following conditions: + +- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. - is undefined under any of the following conditions: - -- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. - - The last call to returned `false`, which indicates the end of the collection and that the enumerator is positioned after the last element of the collection. - The enumerator is invalidated due to changes made in the collection, such as adding, modifying, or deleting elements. - does not move the position of the enumerator, and consecutive calls to return the same object until either or is called. - + does not move the position of the enumerator, and consecutive calls to return the same object until either or is called. + ]]> @@ -264,15 +264,15 @@ if the enumerator was successfully advanced to the next element; if the enumerator has passed the end of the collection. - method advances the enumerator to the first element of the collection. - - 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`. - - 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 . - + method advances the enumerator to the first element of the collection. + + 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`. + + 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. @@ -326,20 +326,20 @@ Gets the element at the current position of the enumerator. The element in the collection at the current position of the enumerator. - is undefined under any of the following conditions: - -- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. - + is undefined under any of the following conditions: + +- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. + - The last call to returned `false`, which indicates the end of the collection and that the enumerator is positioned after the last element of the collection. - The enumerator is invalidated due to changes made in the collection, such as adding, modifying, or deleting elements. - does not move the position of the enumerator, and consecutive calls to return the same object until either or is called. - + does not move the position of the enumerator, and consecutive calls to return the same object until either or is called. + ]]> The enumerator is positioned before the first element of the collection or after the last element. @@ -386,11 +386,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. @@ -432,7 +432,7 @@ System.Void - + The source of the deserialization event. @@ -477,8 +477,8 @@ System.Void - - + + A object that contains the information required to serialize the instance. diff --git a/xml/System.Collections.Generic/SortedSet`1.xml b/xml/System.Collections.Generic/SortedSet`1.xml index 8e9540412a1..1347e8330d5 100644 --- a/xml/System.Collections.Generic/SortedSet`1.xml +++ b/xml/System.Collections.Generic/SortedSet`1.xml @@ -126,23 +126,23 @@ The type of elements in the set. Represents a collection of objects that is maintained in sorted order. - object maintains a sorted order without affecting performance as elements are inserted and deleted. Duplicate elements are not allowed. Changing the sort values of existing items is not supported and may lead to unexpected behavior. - - For a thread safe alternative to , see - - - -## Examples - The following example demonstrates a class that is created with the constructor that takes an as a parameter. This comparer (`ByFileExtension`) is used to sort a list of file names by their extensions. - - This example demonstrates how to create a sorted set of media file names, remove unwanted elements, view a range of elements, and compare the set with another sorted set. - - :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/SortedSetT/Overview/program.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.sortedset/vb/program.vb" id="Snippet1"::: - + object maintains a sorted order without affecting performance as elements are inserted and deleted. Duplicate elements are not allowed. Changing the sort values of existing items is not supported and may lead to unexpected behavior. + + For a thread safe alternative to , see + + + +## Examples + The following example demonstrates a class that is created with the constructor that takes an as a parameter. This comparer (`ByFileExtension`) is used to sort a list of file names by their extensions. + + This example demonstrates how to create a sorted set of media file names, remove unwanted elements, view a range of elements, and compare the set with another sorted set. + + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/SortedSetT/Overview/program.cs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.sortedset/vb/program.vb" id="Snippet1"::: + ]]> @@ -157,11 +157,11 @@ Initializes a new instance of the class. - @@ -248,16 +248,16 @@ The default comparer to use for comparing objects. Initializes a new instance of the class that uses a specified comparer. - class. - - :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/SortedSetT/Overview/program.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.sortedset/vb/program.vb" id="Snippet2"::: -:::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/SortedSetT/Overview/program.cs" id="Snippet9"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.sortedset/vb/program.vb" id="Snippet9"::: - + class. + + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/SortedSetT/Overview/program.cs" id="Snippet2"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.sortedset/vb/program.vb" id="Snippet2"::: +:::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/SortedSetT/Overview/program.cs" id="Snippet9"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.sortedset/vb/program.vb" id="Snippet9"::: + ]]> @@ -302,13 +302,13 @@ The enumerable collection to be copied. Initializes a new instance of the class that contains elements copied from a specified enumerable collection. - class, and no exceptions are thrown. - - This constructor is an `O(n log n)` operation, where `n` is the number of elements in the `collection` parameter. - + class, and no exceptions are thrown. + + This constructor is an `O(n log n)` operation, where `n` is the number of elements in the `collection` parameter. + ]]> @@ -409,19 +409,19 @@ - - + + The object that contains the information that is required to serialize the object. The structure that contains the source and destination of the serialized stream associated with the object. Initializes a new instance of the class that contains serialized data. - @@ -478,21 +478,21 @@ if is added to the set; otherwise, . - class does not accept duplicate elements. If `item` is already in the set, this method returns `false` and does not throw an exception. - - If already equals the capacity of the object, the capacity is automatically adjusted to accommodate the new item. - - - -## Examples - The following example adds elements to a sorted set. This code example is part of a larger example provided for the class. - - :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/SortedSetT/Overview/program.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.sortedset/vb/program.vb" id="Snippet3"::: - + class does not accept duplicate elements. If `item` is already in the set, this method returns `false` and does not throw an exception. + + If already equals the capacity of the object, the capacity is automatically adjusted to accommodate the new item. + + + +## Examples + The following example adds elements to a sorted set. This code example is part of a larger example provided for the class. + + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/SortedSetT/Overview/program.cs" id="Snippet3"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.sortedset/vb/program.vb" id="Snippet3"::: + ]]> @@ -538,11 +538,11 @@ Removes all elements from the set. - . - + . + ]]> @@ -591,13 +591,13 @@ Gets the object that is used to order the values in the . The comparer that is used to order the values in the . - , or the comparer used for its constructor. - - Retrieving the value of this property is an `O(1)` operation. - + , or the comparer used for its constructor. + + Retrieving the value of this property is an `O(1)` operation. + ]]> @@ -649,11 +649,11 @@ if the set contains ; otherwise, . -
@@ -667,11 +667,11 @@ Copies a portion or all of a to a compatible one-dimensional array, starting at the beginning of the destination array or at a specified index. - . - + . + ]]> @@ -717,11 +717,11 @@ A one-dimensional array that is the destination of the elements copied from the . Copies the complete to a compatible one-dimensional array, starting at the beginning of the target array. - The number of elements in the source exceeds the number of elements that the destination array can contain. @@ -775,11 +775,11 @@ The zero-based index in at which copying begins. Copies the complete to a compatible one-dimensional array, starting at the specified array index. - . - + . + ]]> The number of elements in the source array is greater than the available space from to the end of the destination array. @@ -834,21 +834,21 @@ The number of elements to copy. Copies a specified number of elements from to a compatible one-dimensional array, starting at the specified array index. - The number of elements in the source array is greater than the available space from to the end of the destination array. is . - is less than zero. - - -or- - + is less than zero. + + -or- + is less than zero. @@ -895,11 +895,11 @@ Gets the number of elements in the . The number of elements in the . - @@ -951,13 +951,13 @@ Returns an object that can be used to create a collection that contains individual sets. A comparer for creating a collection of sets. - object checks for equality at only one level; however, you can chain together comparers at additional levels to perform deeper equality testing. - - Calling this method is an `O(1)` operation. - + object checks for equality at only one level; however, you can chain together comparers at additional levels to perform deeper equality testing. + + Calling this method is an `O(1)` operation. + ]]> @@ -996,7 +996,7 @@ System.Collections.Generic.IEqualityComparer<System.Collections.Generic.SortedSet<T>> - + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 2, 1 })] @@ -1010,21 +1010,21 @@ Returns an object, according to a specified comparer, that can be used to create a collection that contains individual sets. A comparer for creating a collection of sets. - must have the same definition of equality. - - You can use the comparer returned by this method in the constructor to create a hash table of individual sets. - - - -## Examples - The following example uses the method to create a set of sets. This code example is part of a larger example provided for the class. - - :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/SortedSetT/Overview/program.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.sortedset/vb/program.vb" id="Snippet7"::: - + must have the same definition of equality. + + You can use the comparer returned by this method in the constructor to create a hash table of individual sets. + + + +## Examples + The following example uses the method to create a set of sets. This code example is part of a larger example provided for the class. + + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/SortedSetT/Overview/program.cs" id="Snippet7"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.sortedset/vb/program.vb" id="Snippet7"::: + ]]> @@ -1073,21 +1073,21 @@ The collection of items to remove from the object. Removes all elements that are in a specified collection from the current object. - that is also in `other`. Duplicate values in `other` are ignored. - - This method is an `O(n)` operation, where `n` is the number of elements in the `other` parameter. - - - -## Examples - The following example removes elements from a sorted set that are duplicated in another sorted set. This code example is part of a larger example provided for the class. - - :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/SortedSetT/Overview/program.cs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.sortedset/vb/program.vb" id="Snippet6"::: - + that is also in `other`. Duplicate values in `other` are ignored. + + This method is an `O(n)` operation, where `n` is the number of elements in the `other` parameter. + + + +## Examples + The following example removes elements from a sorted set that are duplicated in another sorted set. This code example is part of a larger example provided for the class. + + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/SortedSetT/Overview/program.cs" id="Snippet6"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.sortedset/vb/program.vb" id="Snippet6"::: + ]]> @@ -1133,13 +1133,13 @@ Returns an enumerator that iterates through the . An enumerator that iterates through the in sorted order. - or throws an . - - This method is an `O(log n)` operation. - + or throws an . + + This method is an `O(log n)` operation. + ]]> @@ -1177,19 +1177,19 @@ System.Void - - + + A object that contains the information that is required to serialize the object. A structure that contains the source and destination of the serialized stream associated with the object. Implements the interface and returns the data that you must have to serialize a object. - . - + . + ]]> @@ -1247,19 +1247,19 @@ Returns a view of a subset in a . A subset view that contains only the values in the specified range. - , but provides a window into the underlying itself. You can make changes in both the view and in the underlying . - - - -## Examples - The following example uses the method to list only the AVI files from a sorted set of media file names. The comparer evaluates file names according to their extensions. The `lowerValue` is "AVI" and the `upperValue` is only one value higher, "AVJ", to get the view of all AVI files. This code example is part of a larger example provided for the class. - - :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/SortedSetT/Overview/program.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.sortedset/vb/program.vb" id="Snippet5"::: - + , but provides a window into the underlying itself. You can make changes in both the view and in the underlying . + + + +## Examples + The following example uses the method to list only the AVI files from a sorted set of media file names. The comparer evaluates file names according to their extensions. The `lowerValue` is "AVI" and the `upperValue` is only one value higher, "AVJ", to get the view of all AVI files. This code example is part of a larger example provided for the class. + + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/SortedSetT/Overview/program.cs" id="Snippet5"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.sortedset/vb/program.vb" id="Snippet5"::: + ]]> @@ -1311,13 +1311,13 @@ The collection to compare to the current object. Modifies the current object so that it contains only elements that are also in a specified collection. - collection with the same equality comparer as the current object, this method is an `O(n)` operation. Otherwise, this method is an `O(n + m)` operation, where `n` is and `m` is the number of elements in `other`. - + collection with the same equality comparer as the current object, this method is an `O(n)` operation. Otherwise, this method is an `O(n + m)` operation, where `n` is and `m` is the number of elements in `other`. + ]]> @@ -1377,15 +1377,15 @@ if the object is a proper subset of ; otherwise, . - object is empty unless the `other` parameter is also an empty set. - - This method always returns `false` if is greater than or equal to the number of elements in `other`. - - If the collection represented by `other` is a collection with the same equality comparer as the current object, then this method is an `O(n)` operation. Otherwise, this method is an `O(n + m)` operation, where `n` is and `m` is the number of elements in `other`. - + object is empty unless the `other` parameter is also an empty set. + + This method always returns `false` if is greater than or equal to the number of elements in `other`. + + If the collection represented by `other` is a collection with the same equality comparer as the current object, then this method is an `O(n)` operation. Otherwise, this method is an `O(n + m)` operation, where `n` is and `m` is the number of elements in `other`. + ]]> @@ -1445,15 +1445,15 @@ if the object is a proper superset of ; otherwise, . - collection is also empty. - - This method always returns `false` if is less than or equal to the number of elements in `other`. - - If the collection represented by `other` is a collection with the same equality comparer as the current object, this method is an `O(n)` operation. Otherwise, this method is an `O(n + m)` operation, where `n` is the number of elements in `other` and `m` is . - + collection is also empty. + + This method always returns `false` if is less than or equal to the number of elements in `other`. + + If the collection represented by `other` is a collection with the same equality comparer as the current object, this method is an `O(n)` operation. Otherwise, this method is an `O(n + m)` operation, where `n` is the number of elements in `other` and `m` is . + ]]> @@ -1513,15 +1513,15 @@ if the current object is a subset of ; otherwise, . - object is empty, even if the `other` parameter is an empty set. - - This method always returns `false` if is greater than the number of elements in `other`. - - If the collection represented by `other` is a collection with the same equality comparer as the current object, this method is an `O(n)` operation. Otherwise, this method is an `O(n + m)` operation, where `n` is and `m` is the number of elements in `other`. - + object is empty, even if the `other` parameter is an empty set. + + This method always returns `false` if is greater than the number of elements in `other`. + + If the collection represented by `other` is a collection with the same equality comparer as the current object, this method is an `O(n)` operation. Otherwise, this method is an `O(n + m)` operation, where `n` is and `m` is the number of elements in `other`. + ]]> @@ -1575,15 +1575,15 @@ if the object is a superset of ; otherwise, . - object is empty. - - This method always returns `false` if is less than the number of elements in `other`. - - If the collection represented by `other` is a collection with the same equality comparer as the current object, this method is an `O(n)` operation. Otherwise, this method is an `O(n + m)` operation, where `n` is the number of elements in `other` and `m` is . - + object is empty. + + This method always returns `false` if is less than the number of elements in `other`. + + If the collection represented by `other` is a collection with the same equality comparer as the current object, this method is an `O(n)` operation. Otherwise, this method is an `O(n + m)` operation, where `n` is the number of elements in `other` and `m` is . + ]]> @@ -1639,11 +1639,11 @@ Gets the maximum value in the , as defined by the comparer. The maximum value in the set. - has no elements, then the property returns the default value of `T`. - + has no elements, then the property returns the default value of `T`. + ]]> @@ -1697,11 +1697,11 @@ Gets the minimum value in the , as defined by the comparer. The minimum value in the set. - has no elements, then the property returns the default value of `T`. - + has no elements, then the property returns the default value of `T`. + ]]> @@ -1746,17 +1746,17 @@ System.Void - + The source of the deserialization event. Implements the interface, and raises the deserialization event when the deserialization is completed. - . - + . + ]]> The object associated with the current object is invalid. @@ -1809,13 +1809,13 @@ if the object and share at least one common element; otherwise, . - and `n` is the number of elements in `other`. - + and `n` is the number of elements in `other`. + ]]> @@ -1874,15 +1874,15 @@ if the element is found and successfully removed; otherwise, . - object does not contain the specified element, the object remains unchanged and no exception is thrown. - - `item` can be `null` for reference types. - - This method is an `O(log n)` operation. - + object does not contain the specified element, the object remains unchanged and no exception is thrown. + + `item` can be `null` for reference types. + + This method is an `O(log n)` operation. + ]]> @@ -1929,26 +1929,26 @@ Removes all elements that match the conditions defined by the specified predicate from a . The number of elements that were removed from the collection. - . Doing so can cause unexpected results. - - Calling this method is an `O(n)` operation, where `n` is . - - - -## Examples - The following example removes unwanted elements from a sorted set. This code example is part of a larger example provided for the class. - - :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/SortedSetT/Overview/program.cs" id="Snippet8"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.sortedset/vb/program.vb" id="Snippet8"::: - - :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/SortedSetT/Overview/program.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.sortedset/vb/program.vb" id="Snippet4"::: - - - + . Doing so can cause unexpected results. + + Calling this method is an `O(n)` operation, where `n` is . + + + +## Examples + The following example removes unwanted elements from a sorted set. This code example is part of a larger example provided for the class. + + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/SortedSetT/Overview/program.cs" id="Snippet8"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.sortedset/vb/program.vb" id="Snippet8"::: + + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/SortedSetT/Overview/program.cs" id="Snippet4"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.sortedset/vb/program.vb" id="Snippet4"::: + + + ]]> @@ -2060,13 +2060,13 @@ if the current object is equal to ; otherwise, . - collection with the same equality comparer as the current object, this method is an `O(log n)` operation. Otherwise, this method is an `O(n + m)` operation, where `n` is the number of elements in `other` and `m` is . - + collection with the same equality comparer as the current object, this method is an `O(log n)` operation. Otherwise, this method is an `O(n + m)` operation, where `n` is the number of elements in `other` and `m` is . + ]]> @@ -2117,13 +2117,13 @@ The collection to compare to the current object. Modifies the current object so that it contains only elements that are present either in the current object or in the specified collection, but not both. - collection with the same equality comparer as the current object, this method is an `O(n log m)` operation. Otherwise, this method is an `O(n log m) + O(n log n)` operation, where `n` is the number of elements in `other` and `m` is . - + collection with the same equality comparer as the current object, this method is an `O(n log m)` operation. Otherwise, this method is an `O(n log m) + O(n log n)` operation, where `n` is the number of elements in `other` and `m` is . + ]]> @@ -2174,13 +2174,13 @@ The object to add to the object. Adds an item to an object. - instance is cast to an interface. - - If is less than , this method is an `O(1)` operation. If the capacity must be increased to accommodate the new element, this method becomes an `O(n)` operation, where `n` is . - + instance is cast to an interface. + + If is less than , this method is an `O(1)` operation. If the capacity must be increased to accommodate the new element, this method becomes an `O(n)` operation, where `n` is . + ]]> The is read-only. @@ -2228,17 +2228,17 @@ if the collection is read-only; otherwise, . - instance is cast to an interface. - - A collection that is read-only does not allow the addition, removal, or modification of elements after the collection is created. - - A collection that is read-only is simply a collection with a wrapper that prevents modifying the collection; therefore, if changes are made to the underlying collection, the read-only collection reflects those changes. - - Getting the value of this property is an `O(1)` operation. - + instance is cast to an interface. + + A collection that is read-only does not allow the addition, removal, or modification of elements after the collection is created. + + A collection that is read-only is simply a collection with a wrapper that prevents modifying the collection; therefore, if changes are made to the underlying collection, the read-only collection reflects those changes. + + Getting the value of this property is an `O(1)` operation. + ]]> @@ -2285,13 +2285,13 @@ Returns an enumerator that iterates through a collection. An enumerator that can be used to iterate through the collection. - instance is cast to an interface. - - This method is an `O(log n)` operation. - + instance is cast to an interface. + + This method is an `O(log n)` operation. + ]]> @@ -2342,11 +2342,11 @@ The zero-based index in at which copying begins. Copies the complete to a compatible one-dimensional array, starting at the specified array index. - instance is cast to an interface. - + instance is cast to an interface. + ]]> The number of elements in the source array is greater than the available space from to the end of the destination array. @@ -2398,11 +2398,11 @@ if access to the is synchronized; otherwise, . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -2448,13 +2448,13 @@ Gets an object that can be used to synchronize access to the . An object that can be used to synchronize access to the . In the default implementation of , this property always returns the current instance. - instance is cast to an interface. - - This method is an `O(1)` operation. - + instance is cast to an interface. + + This method is an `O(1)` operation. + ]]> @@ -2501,13 +2501,13 @@ Returns an enumerator that iterates through a collection. An enumerator that can be used to iterate through the collection. - instance is cast to an interface. - - This method is an `O(log n)` operation. - + instance is cast to an interface. + + This method is an `O(log n)` operation. + ]]> @@ -2554,17 +2554,17 @@ System.Void - + The source of the deserialization event. Implements the interface, and raises the deserialization event when the deserialization is completed. - instance is cast to an interface. - + instance is cast to an interface. + ]]> The object associated with the current instance is invalid. @@ -2612,19 +2612,19 @@ System.Void - - + + A object that contains the information that is required to serialize the instance. A structure that contains the source and destination of the serialized stream associated with the instance. Implements the interface, and returns the data that you need to serialize the instance. - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -2678,11 +2678,11 @@ Searches the set for a given value and returns the equal value it finds, if any. A value indicating whether the search was successful. - @@ -2731,11 +2731,11 @@ The collection to compare to the current object. Modifies the current object so that it contains all elements that are present in either the current object or the specified collection. - diff --git a/xml/System.Collections.Generic/SynchronizedReadOnlyCollection`1.xml b/xml/System.Collections.Generic/SynchronizedReadOnlyCollection`1.xml index 6b7850c1167..3b1e9d78e56 100644 --- a/xml/System.Collections.Generic/SynchronizedReadOnlyCollection`1.xml +++ b/xml/System.Collections.Generic/SynchronizedReadOnlyCollection`1.xml @@ -52,11 +52,11 @@ The type of object contained as items in the thread-safe, read-only collection. Provides a thread-safe, read-only collection that contains objects of a type specified by the generic parameter as elements. - stores data in an container and provides an object that can be set and used to synchronize access to the collection so that it is thread safe. The container can be recovered using the property. The synchronized object can be recovered using the property. It can only be set using one of the constructors that take the `syncRoot` parameter. - + stores data in an container and provides an object that can be set and used to synchronize access to the collection so that it is thread safe. The container can be recovered using the property. The synchronized object can be recovered using the property. It can only be set using one of the constructors that take the `syncRoot` parameter. + ]]> @@ -117,11 +117,11 @@ The object used to synchronize access to the thread-safe, read-only collection. Initializes a new instance of the class with the object used to synchronize access to the thread-safe, read-only collection. - are created using the same `syncRoot`, then access is protected across all instances. - + are created using the same `syncRoot`, then access is protected across all instances. + ]]> @@ -195,32 +195,6 @@ or is . - - - - - - - - Constructor - - System.ServiceModel - 2.0.5.0 - 4.0.0.0 - - - - - - - - To be added. - To be added. - To be added. - To be added. - To be added. - - @@ -481,11 +455,11 @@ The element to be added to the collection. Throws a if called. - Items cannot be set in a read-only collection. @@ -524,11 +498,11 @@ Throws a if called. - Items cannot be cleared from a read-only collection. @@ -818,11 +792,11 @@ This member is an explicit interface member implementation. It can be used only Gets the object used to synchronize access to the thread-safe, read-only collection. The object used to synchronize access to the thread-safe, read-only collection. - constructor. - + constructor. + ]]> @@ -896,11 +870,11 @@ This member is an explicit interface member implementation. It can be used only Adds an element to the collection. The position into which the new element was inserted. - Items cannot be set in a read-only collection. @@ -1057,11 +1031,11 @@ This member is an explicit interface member implementation. It can be used only The object to insert into the collection. Items cannot be inserted into a read-only collection. - if called. - + if called. + ]]> Items cannot be inserted into a read-only collection. @@ -1217,11 +1191,11 @@ This member is an explicit interface member implementation. It can be used only The zero-based index of the element to be retrieved from the collection. Retrieves the specified element from the collection. - if called. - + if called. + ]]> Items cannot be removed from a read-only collection. @@ -1263,11 +1237,11 @@ This member is an explicit interface member implementation. It can be used only The zero-based index of the element to be retrieved from the collection. Items cannot be removed from a read-only collection. - if called. - + if called. + ]]> Items cannot be removed from a read-only collection. diff --git a/xml/System.Collections.ObjectModel/ObservableCollection`1.xml b/xml/System.Collections.ObjectModel/ObservableCollection`1.xml index 186836d77c8..2ca8fd9d2f9 100644 --- a/xml/System.Collections.ObjectModel/ObservableCollection`1.xml +++ b/xml/System.Collections.ObjectModel/ObservableCollection`1.xml @@ -254,7 +254,7 @@ - + The list from which the elements are copied. diff --git a/xml/System.Collections.Specialized/NameObjectCollectionBase.xml b/xml/System.Collections.Specialized/NameObjectCollectionBase.xml index cea456371a0..ec7fa84ef7c 100644 --- a/xml/System.Collections.Specialized/NameObjectCollectionBase.xml +++ b/xml/System.Collections.Specialized/NameObjectCollectionBase.xml @@ -78,41 +78,41 @@ Provides the base class for a collection of associated keys and values that can be accessed either with the key or with the index. - is the number of elements the can hold. As elements are added to a , the capacity is automatically increased as required through reallocation. - - The hash code provider dispenses hash codes for keys in the instance. The default hash code provider is the . - - The comparer determines whether two keys are equal. The default comparer is the . - - In .NET Framework version 1.0, this class uses culture-sensitive string comparisons. However, in .NET Framework version 1.1 and later, this class uses when comparing strings. For more information about how culture affects comparisons and sorting, see [Performing Culture-Insensitive String Operations](/dotnet/standard/globalization-localization/performing-culture-insensitive-string-operations). - - `null` is allowed as a key or as a value. - + is the number of elements the can hold. As elements are added to a , the capacity is automatically increased as required through reallocation. + + The hash code provider dispenses hash codes for keys in the instance. The default hash code provider is the . + + The comparer determines whether two keys are equal. The default comparer is the . + + In .NET Framework version 1.0, this class uses culture-sensitive string comparisons. However, in .NET Framework version 1.1 and later, this class uses when comparing strings. For more information about how culture affects comparisons and sorting, see [Performing Culture-Insensitive String Operations](/dotnet/standard/globalization-localization/performing-culture-insensitive-string-operations). + + `null` is allowed as a key or as a value. + > [!CAUTION] -> The method does not distinguish between `null` which is returned because the specified key is not found and `null` which is returned because the value associated with the key is `null`. - - - -## Examples - The following code example shows how to implement and use the class. - +> The method does not distinguish between `null` which is returned because the specified key is not found and `null` which is returned because the value associated with the key is `null`. + + + +## Examples + The following code example shows how to implement and use the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Collections.Specialized.NameObjectCollectionBase/CPP/nameobjectcollectionbase.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Specialized/NameObjectCollectionBase/Overview/nameobjectcollectionbase.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Specialized.NameObjectCollectionBase/VB/nameobjectcollectionbase.vb" id="Snippet1"::: ]]> - Public static ( in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe. - - This implementation does not provide a synchronized (thread safe) wrapper for a , but derived classes can create their own synchronized versions of the using the property. - + Public static ( in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe. + + This implementation does not provide a synchronized (thread safe) wrapper for a , but derived classes can create their own synchronized versions of the using the property. + 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. @@ -166,19 +166,19 @@ Initializes a new instance of the class that is empty. - is the number of elements that the can hold. As elements are added to a , the capacity is automatically increased as required by reallocating the internal array. - - If the size of the collection can be estimated, specifying the initial capacity eliminates the need to perform a number of resizing operations while adding elements to the . - - The hash code provider dispenses hash codes for keys in the instance. The default hash code provider is the . - - The comparer determines whether two keys are equal. The default comparer is the . - - This constructor is an O(1) operation. - + is the number of elements that the can hold. As elements are added to a , the capacity is automatically increased as required by reallocating the internal array. + + If the size of the collection can be estimated, specifying the initial capacity eliminates the need to perform a number of resizing operations while adding elements to the . + + The hash code provider dispenses hash codes for keys in the instance. The default hash code provider is the . + + The comparer determines whether two keys are equal. The default comparer is the . + + This constructor is an O(1) operation. + ]]> @@ -226,17 +226,17 @@ The object to use to determine whether two keys are equal and to generate hash codes for the keys in the collection. Initializes a new instance of the class that is empty, has the default initial capacity, and uses the specified object. - object is the number of elements that the can hold. As elements are added to a , the capacity is automatically increased as required by reallocating the internal array. - - If the size of the collection can be estimated, specifying the initial capacity eliminates the need to perform a number of resizing operations while adding elements to the . - - The object combines the comparer and the hash code provider. The hash code provider dispenses hash codes for keys in the . The comparer determines whether two keys are equal. - - This constructor is an O(1) operation. - + object is the number of elements that the can hold. As elements are added to a , the capacity is automatically increased as required by reallocating the internal array. + + If the size of the collection can be estimated, specifying the initial capacity eliminates the need to perform a number of resizing operations while adding elements to the . + + The object combines the comparer and the hash code provider. The hash code provider dispenses hash codes for keys in the . The comparer determines whether two keys are equal. + + This constructor is an O(1) operation. + ]]> @@ -283,19 +283,19 @@ The approximate number of entries that the instance can initially contain. Initializes a new instance of the class that is empty, has the specified initial capacity, and uses the default hash code provider and the default comparer. - is the number of elements that the can hold. As elements are added to a , the capacity is automatically increased as required by reallocating the internal array. - - If the size of the collection can be estimated, specifying the initial capacity eliminates the need to perform a number of resizing operations while adding elements to the . - - The hash code provider dispenses hash codes for keys in the instance. The default hash code provider is the . - - The comparer determines whether two keys are equal. The default comparer is the . - - This constructor is an O(`n`) operation, where `n` is `capacity`. - + is the number of elements that the can hold. As elements are added to a , the capacity is automatically increased as required by reallocating the internal array. + + If the size of the collection can be estimated, specifying the initial capacity eliminates the need to perform a number of resizing operations while adding elements to the . + + The hash code provider dispenses hash codes for keys in the instance. The default hash code provider is the . + + The comparer determines whether two keys are equal. The default comparer is the . + + This constructor is an O(`n`) operation, where `n` is `capacity`. + ]]> @@ -348,27 +348,27 @@ - - + + The that will supply the hash codes for all keys in the instance. The to use to determine whether two keys are equal. Initializes a new instance of the class that is empty, has the default initial capacity, and uses the specified hash code provider and the specified comparer. - is the number of elements that the can hold. As elements are added to a , the capacity is automatically increased as required by reallocating the internal array. - - If the size of the collection can be estimated, specifying the initial capacity eliminates the need to perform a number of resizing operations while adding elements to the . - - The hash code provider dispenses hash codes for keys in the instance. The default hash code provider is the . - - The comparer determines whether two keys are equal. The default comparer is the . - - This constructor is an O(1) operation. - + is the number of elements that the can hold. As elements are added to a , the capacity is automatically increased as required by reallocating the internal array. + + If the size of the collection can be estimated, specifying the initial capacity eliminates the need to perform a number of resizing operations while adding elements to the . + + The hash code provider dispenses hash codes for keys in the instance. The default hash code provider is the . + + The comparer determines whether two keys are equal. The default comparer is the . + + This constructor is an O(1) operation. + ]]> @@ -420,17 +420,17 @@ The object to use to determine whether two keys are equal and to generate hash codes for the keys in the collection. Initializes a new instance of the class that is empty, has the specified initial capacity, and uses the specified object. - object is the number of elements that the can hold. As elements are added to a , the capacity is automatically increased as required by reallocating the internal array. - - If the size of the collection can be estimated, specifying the initial capacity eliminates the need to perform a number of resizing operations while adding elements to the . - - The object combines the comparer and the hash code provider. The hash code provider dispenses hash codes for keys in the . The comparer determines whether two keys are equal. - - This constructor is an O(`n`) operation, where `n` is the `capacity` parameter. - + object is the number of elements that the can hold. As elements are added to a , the capacity is automatically increased as required by reallocating the internal array. + + If the size of the collection can be estimated, specifying the initial capacity eliminates the need to perform a number of resizing operations while adding elements to the . + + The object combines the comparer and the hash code provider. The hash code provider dispenses hash codes for keys in the . The comparer determines whether two keys are equal. + + This constructor is an O(`n`) operation, where `n` is the `capacity` parameter. + ]]> @@ -489,19 +489,19 @@ - - + + A object that contains the information required to serialize the new instance. A object that contains the source and destination of the serialized stream associated with the new instance. Initializes a new instance of the class that is serializable and uses the specified and . - @@ -553,9 +553,9 @@ - - - + + + The approximate number of entries that the instance can initially contain. @@ -563,19 +563,19 @@ The to use to determine whether two keys are equal. Initializes a new instance of the class that is empty, has the specified initial capacity and uses the specified hash code provider and the specified comparer. - is the number of elements that the can hold. As elements are added to a , the capacity is automatically increased as required by reallocating the internal array. - - If the size of the collection can be estimated, specifying the initial capacity eliminates the need to perform a number of resizing operations while adding elements to the . - - The hash code provider dispenses hash codes for keys in the instance. The default hash code provider is the . - - The comparer determines whether two keys are equal. The default comparer is the . - - This constructor is an O(`n`) operation, where `n` is `capacity`. - + is the number of elements that the can hold. As elements are added to a , the capacity is automatically increased as required by reallocating the internal array. + + If the size of the collection can be estimated, specifying the initial capacity eliminates the need to perform a number of resizing operations while adding elements to the . + + The hash code provider dispenses hash codes for keys in the instance. The default hash code provider is the . + + The comparer determines whether two keys are equal. The default comparer is the . + + This constructor is an O(`n`) operation, where `n` is `capacity`. + ]]> @@ -633,22 +633,22 @@ The value of the entry to add. The value can be . Adds an entry with the specified key and value into the instance. - already equals the capacity, the capacity of the is increased by automatically reallocating the internal array, and the existing elements are copied to the new array before the new element is added. - - If is less than the capacity, this method is an O(1) operation. If the capacity needs to be increased to accommodate the new element, this method becomes an O(`n`) operation, where `n` is . - - - -## Examples - The following code example uses to create a new with elements from an . - + already equals the capacity, the capacity of the is increased by automatically reallocating the internal array, and the existing elements are copied to the new array before the new element is added. + + If is less than the capacity, this method is an O(1) operation. If the capacity needs to be increased to accommodate the new element, this method becomes an O(`n`) operation, where `n` is . + + + +## Examples + The following code example uses to create a new with elements from an . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Collections.Specialized.NameObjectCollectionBase.BaseAdd/CPP/nocb_baseadd.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Specialized/NameObjectCollectionBase/BaseAdd/nocb_baseadd.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Specialized.NameObjectCollectionBase.BaseAdd/VB/nocb_baseadd.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Specialized.NameObjectCollectionBase.BaseAdd/VB/nocb_baseadd.vb" id="Snippet1"::: + ]]> The collection is read-only. @@ -694,22 +694,22 @@ Removes all entries from the instance. - is set to zero, and references to other objects from elements of the collection are also released. - - This method is an O(1) operation. - - - -## Examples - The following code example uses to remove all elements from a . - + is set to zero, and references to other objects from elements of the collection are also released. + + This method is an O(1) operation. + + + +## Examples + The following code example uses to remove all elements from a . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Collections.Specialized.NameObjectCollectionBase.BaseClear/CPP/nocb_baseclear.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Specialized/NameObjectCollectionBase/BaseClear/nocb_baseclear.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Specialized.NameObjectCollectionBase.BaseClear/VB/nocb_baseclear.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Specialized.NameObjectCollectionBase.BaseClear/VB/nocb_baseclear.vb" id="Snippet1"::: + ]]> The collection is read-only. @@ -724,15 +724,15 @@ Gets the value of the specified entry from the instance. - and to get specific keys and values. - + and to get specific keys and values. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Collections.Specialized.NameObjectCollectionBase.BaseGet/CPP/nocb_baseget.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Specialized/NameObjectCollectionBase/BaseGetKey/nocb_baseget.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Specialized.NameObjectCollectionBase.BaseGet/VB/nocb_baseget.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Specialized.NameObjectCollectionBase.BaseGet/VB/nocb_baseget.vb" id="Snippet1"::: + ]]> @@ -782,10 +782,10 @@ Gets the value of the entry at the specified index of the instance. An that represents the value of the entry at the specified index. - @@ -838,15 +838,15 @@ Gets the value of the first entry with the specified key from the instance. An that represents the value of the first entry with the specified key, if found; otherwise, . - [!CAUTION] -> This method returns `null` in the following cases: 1) if the specified key is not found; and 2) if the specified key is found and its associated value is `null`. This method does not distinguish between the two cases. - - This method is an O(1) operation. +> This method returns `null` in the following cases: 1) if the specified key is not found; and 2) if the specified key is found and its associated value is `null`. This method does not distinguish between the two cases. + + This method is an O(1) operation. ]]> @@ -895,20 +895,20 @@ Returns a array that contains all the keys in the instance. A array that contains all the keys in the instance. - . - - - -## Examples - The following code example uses and to get an array of the keys or an array of the values. - + . + + + +## Examples + The following code example uses and to get an array of the keys or an array of the values. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Collections.Specialized.NameObjectCollectionBase.BaseGetAll/CPP/nocb_basegetall.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Specialized/NameObjectCollectionBase/BaseGetAllKeys/nocb_basegetall.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Specialized.NameObjectCollectionBase.BaseGetAll/VB/nocb_basegetall.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Specialized.NameObjectCollectionBase.BaseGetAll/VB/nocb_basegetall.vb" id="Snippet1"::: + ]]> @@ -965,20 +965,20 @@ Returns an array that contains all the values in the instance. An array that contains all the values in the instance. - . - - - -## Examples - The following code example uses and to get an array of the keys or an array of the values. - + . + + + +## Examples + The following code example uses and to get an array of the keys or an array of the values. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Collections.Specialized.NameObjectCollectionBase.BaseGetAll/CPP/nocb_basegetall.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Specialized/NameObjectCollectionBase/BaseGetAllKeys/nocb_basegetall.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Specialized.NameObjectCollectionBase.BaseGetAll/VB/nocb_basegetall.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Specialized.NameObjectCollectionBase.BaseGetAll/VB/nocb_basegetall.vb" id="Snippet1"::: + ]]> @@ -1034,11 +1034,11 @@ Returns an array of the specified type that contains all the values in the instance. An array of the specified type that contains all the values in the instance. - . - + . + ]]> @@ -1093,20 +1093,20 @@ Gets the key of the entry at the specified index of the instance. A that represents the key of the entry at the specified index. - and to get specific keys and values. - + and to get specific keys and values. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Collections.Specialized.NameObjectCollectionBase.BaseGet/CPP/nocb_baseget.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Specialized/NameObjectCollectionBase/BaseGetKey/nocb_baseget.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Specialized.NameObjectCollectionBase.BaseGet/VB/nocb_baseget.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Specialized.NameObjectCollectionBase.BaseGet/VB/nocb_baseget.vb" id="Snippet1"::: + ]]> @@ -1155,20 +1155,20 @@ if the instance contains entries whose keys are not ; otherwise, . - to determine if the collection contains keys that are not `null`. - + to determine if the collection contains keys that are not `null`. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Collections.Specialized.NameObjectCollectionBase.BaseHasKeys/CPP/nocb_basehaskeys.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Specialized/NameObjectCollectionBase/BaseHasKeys/nocb_basehaskeys.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Specialized.NameObjectCollectionBase.BaseHasKeys/VB/nocb_basehaskeys.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Specialized.NameObjectCollectionBase.BaseHasKeys/VB/nocb_basehaskeys.vb" id="Snippet1"::: + ]]> @@ -1217,24 +1217,24 @@ The key of the entries to remove. The key can be . Removes the entries with the specified key from the instance. - does not contain an element with the specified key, the remains unchanged. No exception is thrown. - - In collections of contiguous elements, such as lists, the elements that follow the removed element move up to occupy the vacated spot. If the collection is indexed, the indexes of the elements that are moved are also updated. This behavior does not apply to collections where elements are conceptually grouped into buckets, such as a hash table. - - This method is an O(`n`) operation, where `n` is . - - - -## Examples - The following code example uses and to remove elements from a . - + does not contain an element with the specified key, the remains unchanged. No exception is thrown. + + In collections of contiguous elements, such as lists, the elements that follow the removed element move up to occupy the vacated spot. If the collection is indexed, the indexes of the elements that are moved are also updated. This behavior does not apply to collections where elements are conceptually grouped into buckets, such as a hash table. + + This method is an O(`n`) operation, where `n` is . + + + +## Examples + The following code example uses and to remove elements from a . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Collections.Specialized.NameObjectCollectionBase.BaseRemove/CPP/nocb_baseremove.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Specialized/NameObjectCollectionBase/BaseRemove/nocb_baseremove.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Specialized.NameObjectCollectionBase.BaseRemove/VB/nocb_baseremove.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Specialized.NameObjectCollectionBase.BaseRemove/VB/nocb_baseremove.vb" id="Snippet1"::: + ]]> The collection is read-only. @@ -1284,22 +1284,22 @@ The zero-based index of the entry to remove. Removes the entry at the specified index of the instance. - . - - - -## Examples - The following code example uses and to remove elements from a . - + . + + + +## Examples + The following code example uses and to remove elements from a . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Collections.Specialized.NameObjectCollectionBase.BaseRemove/CPP/nocb_baseremove.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Specialized/NameObjectCollectionBase/BaseRemove/nocb_baseremove.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Specialized.NameObjectCollectionBase.BaseRemove/VB/nocb_baseremove.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Specialized.NameObjectCollectionBase.BaseRemove/VB/nocb_baseremove.vb" id="Snippet1"::: + ]]> @@ -1316,15 +1316,15 @@ Sets the value of an entry in the instance. - to set the value of a specific element. -## Examples - The following code example uses to set the value of a specific element. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Collections.Specialized.NameObjectCollectionBase.BaseSet/CPP/nocb_baseset.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Specialized/NameObjectCollectionBase/BaseSet/nocb_baseset.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Specialized.NameObjectCollectionBase.BaseSet/VB/nocb_baseset.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Specialized.NameObjectCollectionBase.BaseSet/VB/nocb_baseset.vb" id="Snippet1"::: + ]]> @@ -1375,11 +1375,11 @@ The that represents the new value of the entry to set. The value can be . Sets the value of the entry at the specified index of the instance. - The collection is read-only. @@ -1434,13 +1434,13 @@ The that represents the new value of the entry to set. The value can be . Sets the value of the first entry with the specified key in the instance, if found; otherwise, adds an entry with the specified key and value into the instance. - The collection is read-only. @@ -1491,15 +1491,15 @@ Gets the number of key/value pairs contained in the instance. The number of key/value pairs contained in the instance. - can store. is the number of elements that are actually in the . - - The capacity is always greater than or equal to . If exceeds the capacity while adding elements, the capacity is automatically increased by reallocating the internal array before copying the old elements and adding the new elements. - - Retrieving the value of this property is an O(1) operation. - + can store. is the number of elements that are actually in the . + + The capacity is always greater than or equal to . If exceeds the capacity while adding elements, the capacity is automatically increased by reallocating the internal array before copying the old elements and adding the new elements. + + Retrieving the value of this property is an O(1) operation. + ]]> @@ -1556,27 +1556,27 @@ Returns an enumerator that iterates through the . An for the instance. - also brings the enumerator back to this position. At this position, 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. - - 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. - - The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - - This method is an O(1) operation. - + also brings the enumerator back to this position. At this position, 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. + + 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. + + The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. + + This method is an O(1) operation. + ]]> @@ -1633,19 +1633,19 @@ System.Void - - + + A object that contains the information required to serialize the instance. A object that contains the source and destination of the serialized stream associated with the instance. Implements the interface and returns the data needed to serialize the instance. - . - + . + ]]> @@ -1706,24 +1706,24 @@ if the instance is read-only; otherwise, . - @@ -1778,11 +1778,11 @@ Gets a instance that contains all the keys in the instance. A instance that contains all the keys in the instance. - @@ -1826,19 +1826,19 @@ System.Void - + The source of the deserialization event. Implements the interface and raises the deserialization event when the deserialization is complete. - method is not visible to COM clients by default, inheriting the class can expose it and can cause undesirable behavior in COM clients. - - This method is an O(`n`) operation, where `n` is . - + method is not visible to COM clients by default, inheriting the class can expose it and can cause undesirable behavior in COM clients. + + This method is an O(`n`) operation, where `n` is . + ]]> The object associated with the current instance is invalid. @@ -1895,17 +1895,17 @@ The zero-based index in at which copying begins. Copies the entire to a compatible one-dimensional , starting at the specified index of the target array. - to copy the elements. - - While the method is not visible to COM clients by default, inheriting the class can expose it and can cause undesirable behavior in COM clients. - - This method is an O(`n`) operation, where `n` is . - + to copy the elements. + + While the method is not visible to COM clients by default, inheriting the class can expose it and can cause undesirable behavior in COM clients. + + This method is an O(`n`) operation, where `n` is . + ]]> @@ -1913,10 +1913,10 @@ is less than zero. - is multidimensional. - - -or- - + is multidimensional. + + -or- + The number of elements in the source is greater than the available space from to the end of the destination . The type of the source cannot be cast automatically to the type of the destination . @@ -1964,21 +1964,21 @@ if access to the object is synchronized (thread safe); otherwise, . The default is . - object is not synchronized. Derived classes can provide a synchronized version of the using the property. - - 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 property during the entire enumeration. - + object is not synchronized. Derived classes can provide a synchronized version of the using the property. + + 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 property during the entire enumeration. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Collections.Specialized.NameObjectCollectionBase/CPP/remarks.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Specialized/NameObjectCollectionBase/Overview/remarks.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Specialized.NameObjectCollectionBase/VB/remarks.vb" id="Snippet2"::: - - Retrieving the value of this property is an O(1) operation. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Specialized.NameObjectCollectionBase/VB/remarks.vb" id="Snippet2"::: + + Retrieving the value of this property is an O(1) operation. + ]]> @@ -2032,21 +2032,21 @@ Gets an object that can be used to synchronize access to the object. An object that can be used to synchronize access to the object. - class using the property. The synchronizing code must perform operations on the property of the object, not directly on the object. 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. - - 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. - + class using the property. The synchronizing code must perform operations on the property of the object, not directly on the object. 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. + + 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. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Collections.Specialized.NameObjectCollectionBase/CPP/remarks.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Specialized/NameObjectCollectionBase/Overview/remarks.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Specialized.NameObjectCollectionBase/VB/remarks.vb" id="Snippet2"::: - - Retrieving the value of this property is an O(1) operation. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Specialized.NameObjectCollectionBase/VB/remarks.vb" id="Snippet2"::: + + Retrieving the value of this property is an O(1) operation. + ]]> diff --git a/xml/System.Collections.Specialized/NameValueCollection.xml b/xml/System.Collections.Specialized/NameValueCollection.xml index 2a09e136109..ec95464fd1e 100644 --- a/xml/System.Collections.Specialized/NameValueCollection.xml +++ b/xml/System.Collections.Specialized/NameValueCollection.xml @@ -59,40 +59,40 @@ Represents a collection of associated keys and values that can be accessed either with the key or with the index. - class. Each element of the collection is a key/value pair. However, unlike the , this class can store multiple string values under a single key. - - This class can be used for headers, query strings and form data. - - Collections of this type do not preserve the ordering of elements, and no particular ordering is guaranteed when enumerating the collection. - - The capacity of a is the number of elements the can hold. As elements are added, its capacity is automatically increased as required through reallocation. - - The hash code provider dispenses hash codes for keys in the . The default hash code provider is the . - - The comparer determines whether two keys are equal. The default comparer is a that uses the conventions of the [invariant culture](xref:System.Globalization.CultureInfo.InvariantCulture); that is, key comparisons are case-insensitive by default. To perform case-sensitive key comparisons, call the constructor, and provide a value of , , or as the `equalityComparer` argument. For more information about how culture affects comparisons and sorting, see [Performing Culture-Insensitive String Operations](/dotnet/standard/globalization-localization/performing-culture-insensitive-string-operations). - - `null` is allowed as a key or as a value. - + This collection is based on the class. Each element of the collection is a key/value pair. However, unlike the , this class can store multiple string values under a single key. + + This class can be used for headers, query strings and form data. + + Collections of this type do not preserve the ordering of elements, and no particular ordering is guaranteed when enumerating the collection. + + The capacity of a is the number of elements the can hold. As elements are added, its capacity is automatically increased as required through reallocation. + + The hash code provider dispenses hash codes for keys in the . The default hash code provider is the . + + The comparer determines whether two keys are equal. The default comparer is a that uses the conventions of the [invariant culture](xref:System.Globalization.CultureInfo.InvariantCulture); that is, key comparisons are case-insensitive by default. To perform case-sensitive key comparisons, call the constructor, and provide a value of , , or as the `equalityComparer` argument. For more information about how culture affects comparisons and sorting, see [Performing Culture-Insensitive String Operations](/dotnet/standard/globalization-localization/performing-culture-insensitive-string-operations). + + `null` is allowed as a key or as a value. + > [!CAUTION] -> The method does not distinguish between `null` which is returned because the specified key is not found and `null` which is returned because the value associated with the key is `null`. - - - -## Examples +> The method does not distinguish between `null` which is returned because the specified key is not found and `null` which is returned because the value associated with the key is `null`. + + + +## Examples :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Collections.Specialized.NameValueCollection2/CPP/nvc.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Specialized/NameValueCollection/Overview/nvc.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Specialized.NameValueCollection2/VB/nvc.vb" id="Snippet1"::: - + ]]> - Public static ( in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe. - - This implementation does not provide a synchronized (thread safe) wrapper for a , but derived classes can create their own synchronized versions of the using the property of the class. - + Public static ( in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe. + + This implementation does not provide a synchronized (thread safe) wrapper for a , but derived classes can create their own synchronized versions of the using the property of the class. + 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. Performing Culture-Insensitive String Operations @@ -150,19 +150,19 @@ Initializes a new instance of the class that is empty, has the default initial capacity and uses the default case-insensitive hash code provider and the default case-insensitive comparer. - is the number of elements that the can hold. As elements are added to a , the capacity is automatically increased as required by reallocating the internal array. - - If the size of the collection can be estimated, specifying the initial capacity eliminates the need to perform a number of resizing operations while adding elements to the . - - The hash code provider dispenses hash codes for keys in the . The default hash code provider is the . - - The comparer determines whether two keys are equal. The default comparer is the . - - This constructor is an O(1) operation. - + is the number of elements that the can hold. As elements are added to a , the capacity is automatically increased as required by reallocating the internal array. + + If the size of the collection can be estimated, specifying the initial capacity eliminates the need to perform a number of resizing operations while adding elements to the . + + The hash code provider dispenses hash codes for keys in the . The default hash code provider is the . + + The comparer determines whether two keys are equal. The default comparer is the . + + This constructor is an O(1) operation. + ]]> @@ -216,17 +216,17 @@ The object to use to determine whether two keys are equal and to generate hash codes for the keys in the collection. Initializes a new instance of the class that is empty, has the default initial capacity, and uses the specified object. - object is the number of elements that the can hold. As elements are added to a , the capacity is automatically increased as required by reallocating the internal array. - - If the size of the collection can be estimated, specifying the initial capacity eliminates the need to perform a number of resizing operations while adding elements to the . - - The object combines the comparer and the hash code provider. The hash code provider dispenses hash codes for keys in the . The comparer determines whether two keys are equal. - - This constructor is an O(1) operation. - + object is the number of elements that the can hold. As elements are added to a , the capacity is automatically increased as required by reallocating the internal array. + + If the size of the collection can be estimated, specifying the initial capacity eliminates the need to perform a number of resizing operations while adding elements to the . + + The object combines the comparer and the hash code provider. The hash code provider dispenses hash codes for keys in the . The comparer determines whether two keys are equal. + + This constructor is an O(1) operation. + ]]> @@ -279,21 +279,21 @@ The to copy to the new instance. Copies the entries from the specified to a new with the same initial capacity as the number of entries copied and using the same hash code provider and the same comparer as the source collection. - is the number of elements that the can hold. As elements are added to a , the capacity is automatically increased as required by reallocating the internal array. - - If the size of the collection can be estimated, specifying the initial capacity eliminates the need to perform a number of resizing operations while adding elements to the . - - The hash code provider dispenses hash codes for keys in the . The default hash code provider is the . - - The comparer determines whether two keys are equal. The default comparer is the . - - The elements of the new are sorted in the same order as the source . - - This constructor is an O(`n`) operation, where `n` is the number of elements in `col`. - + is the number of elements that the can hold. As elements are added to a , the capacity is automatically increased as required by reallocating the internal array. + + If the size of the collection can be estimated, specifying the initial capacity eliminates the need to perform a number of resizing operations while adding elements to the . + + The hash code provider dispenses hash codes for keys in the . The default hash code provider is the . + + The comparer determines whether two keys are equal. The default comparer is the . + + The elements of the new are sorted in the same order as the source . + + This constructor is an O(`n`) operation, where `n` is the number of elements in `col`. + ]]> @@ -349,19 +349,19 @@ The initial number of entries that the can contain. Initializes a new instance of the class that is empty, has the specified initial capacity and uses the default case-insensitive hash code provider and the default case-insensitive comparer. - is the number of elements that the can hold. As elements are added to a , the capacity is automatically increased as required by reallocating the internal array. - - If the size of the collection can be estimated, specifying the initial capacity eliminates the need to perform a number of resizing operations while adding elements to the . - - The hash code provider dispenses hash codes for keys in the . The default hash code provider is the . - - The comparer determines whether two keys are equal. The default comparer is the . - - This constructor is an O(`n`) operation, where `n` is `capacity`. - + is the number of elements that the can hold. As elements are added to a , the capacity is automatically increased as required by reallocating the internal array. + + If the size of the collection can be estimated, specifying the initial capacity eliminates the need to perform a number of resizing operations while adding elements to the . + + The hash code provider dispenses hash codes for keys in the . The default hash code provider is the . + + The comparer determines whether two keys are equal. The default comparer is the . + + This constructor is an O(`n`) operation, where `n` is `capacity`. + ]]> @@ -418,27 +418,27 @@ - - + + The that will supply the hash codes for all keys in the . The to use to determine whether two keys are equal. Initializes a new instance of the class that is empty, has the default initial capacity and uses the specified hash code provider and the specified comparer. - is the number of elements that the can hold. As elements are added to a , the capacity is automatically increased as required by reallocating the internal array. - - If the size of the collection can be estimated, specifying the initial capacity eliminates the need to perform a number of resizing operations while adding elements to the . - - The hash code provider dispenses hash codes for keys in the . The default hash code provider is the . - - The comparer determines whether two keys are equal. The default comparer is the . - - This constructor is an O(1) operation. - + is the number of elements that the can hold. As elements are added to a , the capacity is automatically increased as required by reallocating the internal array. + + If the size of the collection can be estimated, specifying the initial capacity eliminates the need to perform a number of resizing operations while adding elements to the . + + The hash code provider dispenses hash codes for keys in the . The default hash code provider is the . + + The comparer determines whether two keys are equal. The default comparer is the . + + This constructor is an O(1) operation. + ]]> @@ -496,17 +496,17 @@ The object to use to determine whether two keys are equal and to generate hash codes for the keys in the collection. Initializes a new instance of the class that is empty, has the specified initial capacity, and uses the specified object. - object is the number of elements that the can hold. As elements are added to a , the capacity is automatically increased as required by reallocating the internal array. - - If the size of the collection can be estimated, specifying the initial capacity eliminates the need to perform a number of resizing operations while adding elements to the . - - The object combines the comparer and the hash code provider. The hash code provider dispenses hash codes for keys in the . The comparer determines whether two keys are equal. - - This constructor is an O(`n`) operation, where `n` is the `capacity` parameter. - + object is the number of elements that the can hold. As elements are added to a , the capacity is automatically increased as required by reallocating the internal array. + + If the size of the collection can be estimated, specifying the initial capacity eliminates the need to perform a number of resizing operations while adding elements to the . + + The object combines the comparer and the hash code provider. The hash code provider dispenses hash codes for keys in the . The comparer determines whether two keys are equal. + + This constructor is an O(`n`) operation, where `n` is the `capacity` parameter. + ]]> @@ -563,19 +563,19 @@ The to copy to the new instance. Copies the entries from the specified to a new with the specified initial capacity or the same initial capacity as the number of entries copied, whichever is greater, and using the default case-insensitive hash code provider and the default case-insensitive comparer. - is the number of elements that the can hold. As elements are added to a , the capacity is automatically increased as required by reallocating the internal array. - - If the size of the collection can be estimated, specifying the initial capacity eliminates the need to perform a number of resizing operations while adding elements to the . - - The hash code provider dispenses hash codes for keys in the . The default hash code provider is the . - - The comparer determines whether two keys are equal. The default comparer is the . - - This constructor is an O(`n`) operation, where `n` is `capacity`. If the number of elements in `col` is greater than `capacity`, this constructor becomes an O(`n` + `m`) operation, where `n` is `capacity` and `m` is the number of elements in `col`. - + is the number of elements that the can hold. As elements are added to a , the capacity is automatically increased as required by reallocating the internal array. + + If the size of the collection can be estimated, specifying the initial capacity eliminates the need to perform a number of resizing operations while adding elements to the . + + The hash code provider dispenses hash codes for keys in the . The default hash code provider is the . + + The comparer determines whether two keys are equal. The default comparer is the . + + This constructor is an O(`n`) operation, where `n` is `capacity`. If the number of elements in `col` is greater than `capacity`, this constructor becomes an O(`n` + `m`) operation, where `n` is `capacity` and `m` is the number of elements in `col`. + ]]> @@ -637,19 +637,19 @@ - - + + A object that contains the information required to serialize the new instance. A object that contains the source and destination of the serialized stream associated with the new instance. Initializes a new instance of the class that is serializable and uses the specified and . - @@ -705,9 +705,9 @@ - - - + + + The initial number of entries that the can contain. @@ -715,19 +715,19 @@ The to use to determine whether two keys are equal. Initializes a new instance of the class that is empty, has the specified initial capacity and uses the specified hash code provider and the specified comparer. - is the number of elements that the can hold. As elements are added to a , the capacity is automatically increased as required by reallocating the internal array. - - If the size of the collection can be estimated, specifying the initial capacity eliminates the need to perform a number of resizing operations while adding elements to the . - - The hash code provider dispenses hash codes for keys in the . The default hash code provider is the . - - The comparer determines whether two keys are equal. The default comparer is the . - - This constructor is an O(`n`) operation, where `n` is `capacity`. - + is the number of elements that the can hold. As elements are added to a , the capacity is automatically increased as required by reallocating the internal array. + + If the size of the collection can be estimated, specifying the initial capacity eliminates the need to perform a number of resizing operations while adding elements to the . + + The hash code provider dispenses hash codes for keys in the . The default hash code provider is the . + + The comparer determines whether two keys are equal. The default comparer is the . + + This constructor is an O(`n`) operation, where `n` is `capacity`. + ]]> @@ -796,15 +796,15 @@ The to copy to the current . Copies the entries in the specified to the current . - instance, the associated value in `c` is added to the existing comma-separated list of values associated with the same key in the target instance. - - If already equals the capacity, the capacity of the is increased by automatically reallocating the internal array, and the existing elements are copied to the new array before the new element is added. - - If is less than the capacity, this method is an O(1) operation. If the capacity needs to be increased to accommodate the new element, this method becomes an O(`n`) operation, where `n` is . - + instance, the associated value in `c` is added to the existing comma-separated list of values associated with the same key in the target instance. + + If already equals the capacity, the capacity of the is increased by automatically reallocating the internal array, and the existing elements are copied to the new array before the new element is added. + + If is less than the capacity, this method is an O(1) operation. If the capacity needs to be increased to accommodate the new element, this method becomes an O(`n`) operation, where `n` is . + ]]> The collection is read-only. @@ -859,15 +859,15 @@ The value of the entry to add. The value can be . Adds an entry with the specified name and value to the . - instance, the specified value is added to the existing comma-separated list of values in the form `"value1,value2,value3"`. The values are associated with the same key in the target instance. - - If already equals the capacity, the capacity of the is increased by automatically reallocating the internal array, and the existing elements are copied to the new array before the new element is added. - - If is less than the capacity, this method is an O(1) operation. If the capacity needs to be increased to accommodate the new element, this method becomes an O(`n`) operation, where `n` is . - + instance, the specified value is added to the existing comma-separated list of values in the form `"value1,value2,value3"`. The values are associated with the same key in the target instance. + + If already equals the capacity, the capacity of the is increased by automatically reallocating the internal array, and the existing elements are copied to the new array before the new element is added. + + If is less than the capacity, this method is an O(1) operation. If the capacity needs to be increased to accommodate the new element, this method becomes an O(`n`) operation, where `n` is . + ]]> The collection is read-only. @@ -920,15 +920,15 @@ Gets all the keys in the . A array that contains all the keys of the . - array, not `null`. - - The arrays returned by are cached for better performance and are automatically refreshed when the collection changes. A derived class can invalidate the cached version by calling , thereby forcing the arrays to be recreated. - - This method is an O(`n`) operation, where `n` is . - + array, not `null`. + + The arrays returned by are cached for better performance and are automatically refreshed when the collection changes. A derived class can invalidate the cached version by calling , thereby forcing the arrays to be recreated. + + This method is an O(`n`) operation, where `n` is . + ]]> @@ -980,11 +980,11 @@ Invalidates the cached arrays and removes all entries from the . - The collection is read-only. @@ -1042,15 +1042,15 @@ The zero-based index in at which copying begins. Copies the entire to a compatible one-dimensional , starting at the specified index of the target array. - to copy the elements. - - This method is an O(`n`) operation, where `n` is . - + to copy the elements. + + This method is an O(`n`) operation, where `n` is . + ]]> @@ -1058,10 +1058,10 @@ is less than zero. - is multidimensional. - - -or- - + is multidimensional. + + -or- + The number of elements in the source is greater than the available space from to the end of the destination . The type of the source cannot be cast automatically to the type of the destination . @@ -1121,11 +1121,11 @@ Gets the values at the specified index of the combined into one comma-separated list. A that contains a comma-separated list of the values at the specified index of the , if found; otherwise, . - @@ -1180,15 +1180,15 @@ Gets the values associated with the specified key from the combined into one comma-separated list. A that contains a comma-separated list of the values associated with the specified key from the , if found; otherwise, . - [!CAUTION] -> This method returns `null` in the following cases: 1) if the specified key is not found; and 2) if the specified key is found and its associated value is `null`. This method does not distinguish between the two cases. - - This method is an O(`n`) operation, where `n` is the number of values associated with the specified key. - +> This method returns `null` in the following cases: 1) if the specified key is not found; and 2) if the specified key is found and its associated value is `null`. This method does not distinguish between the two cases. + + This method is an O(`n`) operation, where `n` is the number of values associated with the specified key. + ]]> @@ -1241,11 +1241,11 @@ Gets the key at the specified index of the . A that contains the key at the specified index of the , if found; otherwise, . - @@ -1308,11 +1308,11 @@ Gets the values at the specified index of the . A array that contains the values at the specified index of the , if found; otherwise, . - @@ -1367,15 +1367,15 @@ Gets the values associated with the specified key from the . A array that contains the values associated with the specified key from the , if found; otherwise, . - [!CAUTION] -> This method returns `null` in the following cases: 1) if the specified key is not found; and 2) if the specified key is found and its associated value is `null`. This method does not distinguish between the two cases. - - This method is an O(`n`) operation, where `n` is the number of values associated with the specified key. - +> This method returns `null` in the following cases: 1) if the specified key is not found; and 2) if the specified key is found and its associated value is `null`. This method does not distinguish between the two cases. + + This method is an O(`n`) operation, where `n` is the number of values associated with the specified key. + ]]> @@ -1431,11 +1431,11 @@ if the contains keys that are not ; otherwise, . - @@ -1480,13 +1480,13 @@ Resets the cached arrays of the collection to . - are cached for better performance and are automatically refreshed when the collection changes. A derived class can invalidate the cached version by calling , thereby forcing the arrays to be recreated. - - This method is an O(1) operation. - + are cached for better performance and are automatically refreshed when the collection changes. A derived class can invalidate the cached version by calling , thereby forcing the arrays to be recreated. + + This method is an O(1) operation. + ]]> @@ -1553,17 +1553,17 @@ Gets the entry at the specified index of the . A that contains the comma-separated list of values at the specified index of the collection. - property. Visual Basic implements as a [default property](/dotnet/visual-basic/language-reference/modifiers/default), which provides the same indexing functionality. - - Retrieving the values at the specified index is an O(`n`) operation, where `n` is the number of values. - + property. Visual Basic implements as a [default property](/dotnet/visual-basic/language-reference/modifiers/default), which provides the same indexing functionality. + + Retrieving the values at the specified index is an O(`n`) operation, where `n` is the number of values. + ]]> @@ -1627,22 +1627,22 @@ Gets or sets the entry with the specified key in the . A that contains the comma-separated list of values associated with the specified key, if found; otherwise, . - method. - - If the specified key does not exist in the collection, setting this property creates a new entry using the specified key and the specified value. - + method. + + If the specified key does not exist in the collection, setting this property creates a new entry using the specified key and the specified value. + > [!CAUTION] -> This property returns `null` in the following cases: 1) if the specified key is not found; and 2) if the specified key is found and its associated value is `null`. This property does not distinguish between the two cases. - - The C# language uses the [this](/dotnet/csharp/language-reference/keywords/this) keyword to define the indexers instead of implementing the property. Visual Basic implements as a [default property](/dotnet/visual-basic/language-reference/modifiers/default), which provides the same indexing functionality. - - Retrieving or setting the values associated with the specified key is an O(`n`) operation, where `n` is the number of values. - +> This property returns `null` in the following cases: 1) if the specified key is not found; and 2) if the specified key is found and its associated value is `null`. This property does not distinguish between the two cases. + + The C# language uses the [this](/dotnet/csharp/language-reference/keywords/this) keyword to define the indexers instead of implementing the property. Visual Basic implements as a [default property](/dotnet/visual-basic/language-reference/modifiers/default), which provides the same indexing functionality. + + Retrieving or setting the values associated with the specified key is an O(`n`) operation, where `n` is the number of values. + ]]> The collection is read-only and the operation attempts to modify the collection. @@ -1694,17 +1694,17 @@ The key of the entry to remove. The key can be . Removes the entries with the specified key from the instance. - doesn't contain an element with the specified key, the remains unchanged. No exception is thrown. If you specify a `null` value to the `name` parameter, an entry with a `null` key is removed, if found. - - In collections of contiguous elements, such as lists, the elements that follow the removed element move up to occupy the vacated spot. If the collection is indexed, the indexes of the elements that are moved are also updated. This behavior does not apply to collections where elements are conceptually grouped into buckets, such as a hash table. - - This method is an O(`n`) operation, where `n` is . - + + In collections of contiguous elements, such as lists, the elements that follow the removed element move up to occupy the vacated spot. If the collection is indexed, the indexes of the elements that are moved are also updated. This behavior does not apply to collections where elements are conceptually grouped into buckets, such as a hash table. + + This method is an O(`n`) operation, where `n` is . + ]]> The collection is read-only. @@ -1757,15 +1757,15 @@ The that represents the new value to add to the specified entry. The value can be . Sets the value of an entry in the . - method. - - If the specified key does not exist in the collection, this method creates a new entry using the specified key and the specified value. - - This method is an O(1) operation. - + method. + + If the specified key does not exist in the collection, this method creates a new entry using the specified key and the specified value. + + This method is an O(1) operation. + ]]> The collection is read-only. diff --git a/xml/System.Collections.Specialized/OrderedDictionary.xml b/xml/System.Collections.Specialized/OrderedDictionary.xml index 0cec5e75eef..d1f1cec563d 100644 --- a/xml/System.Collections.Specialized/OrderedDictionary.xml +++ b/xml/System.Collections.Specialized/OrderedDictionary.xml @@ -87,30 +87,30 @@ Represents a collection of key/value pairs that are accessible by the key or index. - object. A key cannot be `null`, but a value can be. - - The elements of an are not sorted by the key, unlike the elements of a class. You can access elements either by the key or by the index. - - The `foreach` statement of the C# language (`For Each` in Visual Basic) returns objects that are of the type of each element in the collection. Since each element of the collection is a key/value pair, the element type is not the type of the key or the type of the value. Instead, the element type is . The following code shows C#, Visual Basic and C++ syntax. - + object. A key cannot be `null`, but a value can be. + + The elements of an are not sorted by the key, unlike the elements of a class. You can access elements either by the key or by the index. + + The `foreach` statement of the C# language (`For Each` in Visual Basic) returns objects that are of the type of each element in the collection. Since each element of the collection is a key/value pair, the element type is not the type of the key or the type of the value. Instead, the element type is . The following code shows C#, Visual Basic and C++ syntax. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Collections.Specialized.OrderedDictionary1/cpp/source2.cpp" id="Snippet06"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Specialized/OrderedDictionary/Overview/source2.cs" id="Snippet06"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Specialized.OrderedDictionary1/VB/source2.vb" id="Snippet06"::: - - The `foreach` statement is a wrapper around the enumerator, which only allows reading from, not writing to, the collection. - - - -## Examples - The following code example demonstrates the creation, population and modification of an collection, as well as two techniques to display the contents of the : one using the and properties and the other creating an enumerator through the method. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Specialized.OrderedDictionary1/VB/source2.vb" id="Snippet06"::: + + The `foreach` statement is a wrapper around the enumerator, which only allows reading from, not writing to, the collection. + + + +## Examples + The following code example demonstrates the creation, population and modification of an collection, as well as two techniques to display the contents of the : one using the and properties and the other creating an enumerator through the method. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Collections.Specialized.OrderedDictionary1/cpp/ordereddictionary1.cpp" id="Snippet00"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Specialized/OrderedDictionary/Overview/OrderedDictionary1.cs" interactive="try-dotnet" id="Snippet00"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Specialized.OrderedDictionary1/VB/OrderedDictionary1.vb" id="Snippet00"::: - + ]]> @@ -166,20 +166,20 @@ Initializes a new instance of the class. - collection must be unique. The default comparer is the key's implementation of . - - - -## Examples - The following code example demonstrates the creation and population of an collection. This code is part of a larger code example that can be viewed at . - + collection must be unique. The default comparer is the key's implementation of . + + + +## Examples + The following code example demonstrates the creation and population of an collection. This code is part of a larger code example that can be viewed at . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Collections.Specialized.OrderedDictionary1/cpp/ordereddictionary1.cpp" id="Snippet01"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Specialized/OrderedDictionary/Overview/OrderedDictionary1.cs" id="Snippet01"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Specialized.OrderedDictionary1/VB/OrderedDictionary1.vb" id="Snippet01"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Specialized.OrderedDictionary1/VB/OrderedDictionary1.vb" id="Snippet01"::: + ]]> @@ -231,20 +231,20 @@ - The to use to determine whether two keys are equal. - - -or- - + The to use to determine whether two keys are equal. + + -or- + to use the default comparer, which is each key's implementation of . Initializes a new instance of the class using the specified comparer. - collection must be unique. The default comparer is the key's implementation of . - - The custom comparer enables such scenarios as doing lookups with case-insensitive strings. - + collection must be unique. The default comparer is the key's implementation of . + + The custom comparer enables such scenarios as doing lookups with case-insensitive strings. + ]]> @@ -294,11 +294,11 @@ The initial number of elements that the collection can contain. Initializes a new instance of the class using the specified initial capacity. - collection must be unique. The default comparer is the key's implementation of . - + collection must be unique. The default comparer is the key's implementation of . + ]]> @@ -352,20 +352,20 @@ The initial number of elements that the collection can contain. - The to use to determine whether two keys are equal. - - -or- - + The to use to determine whether two keys are equal. + + -or- + to use the default comparer, which is each key's implementation of . Initializes a new instance of the class using the specified initial capacity and comparer. - collection must be unique. The default comparer is the key's implementation of . - - The custom comparer enables such scenarios as doing lookups with case-insensitive strings. - + collection must be unique. The default comparer is the key's implementation of . + + The custom comparer enables such scenarios as doing lookups with case-insensitive strings. + ]]> @@ -415,19 +415,19 @@ - - + + A object containing the information required to serialize the collection. A object containing the source and destination of the serialized stream associated with the . Initializes a new instance of the class that is serializable using the specified and objects. - collection must be unique. The default comparer is the key's implementation of . - + collection must be unique. The default comparer is the key's implementation of . + ]]> @@ -487,22 +487,22 @@ The value of the entry to add. This value can be . Adds an entry with the specified key and value into the collection with the lowest available index. - property to add new elements by setting the value of a key that does not exist in the collection; however, if the specified key already exists in the , setting the property overwrites the old value. In contrast, the method does not modify existing elements but instead throws . - - - -## Examples - The following code example demonstrates the creation and population of an collection. This code is part of a larger code example that can be viewed at . - + + + +## Examples + The following code example demonstrates the creation and population of an collection. This code is part of a larger code example that can be viewed at . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Collections.Specialized.OrderedDictionary1/cpp/ordereddictionary1.cpp" id="Snippet01"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Specialized/OrderedDictionary/Overview/OrderedDictionary1.cs" id="Snippet01"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Specialized.OrderedDictionary1/VB/OrderedDictionary1.vb" id="Snippet01"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Specialized.OrderedDictionary1/VB/OrderedDictionary1.vb" id="Snippet01"::: + ]]> The collection is read-only. @@ -549,11 +549,11 @@ Returns a read-only copy of the current collection. A read-only copy of the current collection. - method creates a read-only wrapper around the current collection. Changes made to the collection are reflected in the read-only copy. - + method creates a read-only wrapper around the current collection. Changes made to the collection are reflected in the read-only copy. + ]]> @@ -600,20 +600,20 @@ Removes all elements from the collection. - method, the property is set to zero and references to other objects from elements of the collection are also released. The capacity is not changed as a result of calling this method. - - - -## Examples - The following code example demonstrates the modification of an collection. In this example, the method is used to empty the , and then the is repopulated. This code is part of a larger code example that can be viewed at . - + method, the property is set to zero and references to other objects from elements of the collection are also released. The capacity is not changed as a result of calling this method. + + + +## Examples + The following code example demonstrates the modification of an collection. In this example, the method is used to empty the , and then the is repopulated. This code is part of a larger code example that can be viewed at . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Collections.Specialized.OrderedDictionary1/cpp/ordereddictionary1.cpp" id="Snippet03"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Specialized/OrderedDictionary/Overview/OrderedDictionary1.cs" id="Snippet03"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Specialized.OrderedDictionary1/VB/OrderedDictionary1.vb" id="Snippet03"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Specialized.OrderedDictionary1/VB/OrderedDictionary1.vb" id="Snippet03"::: + ]]> The collection is read-only. @@ -666,22 +666,22 @@ if the collection contains an element with the specified key; otherwise, . - property can return a null value if the key does not exist or if the key is `null`. Use the method to determine if a specific key exists in the collection. - - Starting with the .NET Framework 2.0, this method uses the collection's objects' and methods on `item` to determine whether `item` exists. In the earlier versions of the .NET Framework, this determination was made by using the and methods of the `item` parameter on the objects in the collection. - - - -## Examples - The following code example demonstrates the modification of an collection. In this example, the method is used to determine if an entry exists before attempting to remove it. This code is part of a larger code example that can be viewed at . - + property can return a null value if the key does not exist or if the key is `null`. Use the method to determine if a specific key exists in the collection. + + Starting with the .NET Framework 2.0, this method uses the collection's objects' and methods on `item` to determine whether `item` exists. In the earlier versions of the .NET Framework, this determination was made by using the and methods of the `item` parameter on the objects in the collection. + + + +## Examples + The following code example demonstrates the modification of an collection. In this example, the method is used to determine if an entry exists before attempting to remove it. This code is part of a larger code example that can be viewed at . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Collections.Specialized.OrderedDictionary1/cpp/ordereddictionary1.cpp" id="Snippet02"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Specialized/OrderedDictionary/Overview/OrderedDictionary1.cs" id="Snippet02"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Specialized.OrderedDictionary1/VB/OrderedDictionary1.vb" id="Snippet02"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Specialized.OrderedDictionary1/VB/OrderedDictionary1.vb" id="Snippet02"::: + ]]> @@ -733,11 +733,11 @@ The zero-based index in at which copying begins. Copies the elements to a one-dimensional object at the specified index. - method is not guaranteed to preserve the order of the elements in the collection. - + method is not guaranteed to preserve the order of the elements in the collection. + ]]> @@ -784,15 +784,15 @@ Gets the number of key/values pairs contained in the collection. The number of key/value pairs contained in the collection. - collection. In this example, the property is used to remove the last item in the . This code is part of a larger code example that can be viewed at . - + collection. In this example, the property is used to remove the last item in the . This code is part of a larger code example that can be viewed at . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Collections.Specialized.OrderedDictionary1/cpp/ordereddictionary1.cpp" id="Snippet02"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Specialized/OrderedDictionary/Overview/OrderedDictionary1.cs" id="Snippet02"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Specialized.OrderedDictionary1/VB/OrderedDictionary1.vb" id="Snippet02"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Specialized.OrderedDictionary1/VB/OrderedDictionary1.vb" id="Snippet02"::: + ]]> @@ -841,35 +841,35 @@ Returns an object that iterates through the collection. An object for the collection. - method to display the contents of the collection to the console. In this example, the method is used to obtain an object that is passed to a method that displays the contents. This code is part of a larger code example that can be viewed at . - + method to display the contents of the collection to the console. In this example, the method is used to obtain an object that is passed to a method that displays the contents. This code is part of a larger code example that can be viewed at . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Collections.Specialized.OrderedDictionary1/cpp/ordereddictionary1.cpp" id="Snippet03"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Specialized/OrderedDictionary/Overview/OrderedDictionary1.cs" id="Snippet03"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Specialized.OrderedDictionary1/VB/OrderedDictionary1.vb" id="Snippet03"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Specialized.OrderedDictionary1/VB/OrderedDictionary1.vb" id="Snippet03"::: + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Collections.Specialized.OrderedDictionary1/cpp/ordereddictionary1.cpp" id="Snippet05"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Specialized/OrderedDictionary/Overview/OrderedDictionary1.cs" id="Snippet05"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Specialized.OrderedDictionary1/VB/OrderedDictionary1.vb" id="Snippet05"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Specialized.OrderedDictionary1/VB/OrderedDictionary1.vb" id="Snippet05"::: + ]]> @@ -921,8 +921,8 @@ System.Void - - + + A object containing the information required to serialize the collection. @@ -990,22 +990,22 @@ The value of the entry to add. The value can be . Inserts a new entry into the collection with the specified key and value at the specified index. - collection, the `key` and `value` parameters are appended to the end of the collection. - - Entries that follow the insertion point move down to accommodate the new entry and the indexes of the moved entries are also updated. - - - -## Examples - The following code example demonstrates the modification of an collection. In this example, the method is used to add a new entry to the beginning of the , moving the rest of the entries down. This code is part of a larger code example that can be viewed at . - + collection, the `key` and `value` parameters are appended to the end of the collection. + + Entries that follow the insertion point move down to accommodate the new entry and the indexes of the moved entries are also updated. + + + +## Examples + The following code example demonstrates the modification of an collection. In this example, the method is used to add a new entry to the beginning of the , moving the rest of the entries down. This code is part of a larger code example that can be viewed at . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Collections.Specialized.OrderedDictionary1/cpp/ordereddictionary1.cpp" id="Snippet02"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Specialized/OrderedDictionary/Overview/OrderedDictionary1.cs" id="Snippet02"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Specialized.OrderedDictionary1/VB/OrderedDictionary1.vb" id="Snippet02"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Specialized.OrderedDictionary1/VB/OrderedDictionary1.vb" id="Snippet02"::: + ]]> @@ -1062,22 +1062,22 @@ if the collection is read-only; otherwise, . The default is . - collection. In this example, the property is used to determine whether the can be modified. This code is part of a larger code example that can be viewed at . - + collection. In this example, the property is used to determine whether the can be modified. This code is part of a larger code example that can be viewed at . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Collections.Specialized.OrderedDictionary1/cpp/ordereddictionary1.cpp" id="Snippet02"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Specialized/OrderedDictionary/Overview/OrderedDictionary1.cs" id="Snippet02"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Specialized.OrderedDictionary1/VB/OrderedDictionary1.vb" id="Snippet02"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Specialized.OrderedDictionary1/VB/OrderedDictionary1.vb" id="Snippet02"::: + ]]> @@ -1153,21 +1153,21 @@ Gets or sets the value at the specified index. The value of the item at the specified index. - property. Visual Basic implements as a [default property](/dotnet/visual-basic/language-reference/modifiers/default), which provides the same indexing functionality. - + property. Visual Basic implements as a [default property](/dotnet/visual-basic/language-reference/modifiers/default), which provides the same indexing functionality. + ]]> The property is being set and the collection is read-only. - is less than zero. - - -or- - + is less than zero. + + -or- + is equal to or greater than . @@ -1224,24 +1224,24 @@ Gets or sets the value with the specified key. The value associated with the specified key. If the specified key is not found, attempting to get it returns , and attempting to set it creates a new element using the specified key. - property to add new elements by setting the value of a key that does not exist in the collection (for example, `myCollection["myNonexistentKey"] = myValue`). However, if the specified key already exists in the , setting the property overwrites the old value. In contrast, the method does not modify existing elements. - - A key cannot be `null`, but a value can be. To distinguish between `null` that is returned because the specified key is not found and `null` that is returned because the value of the specified key is `null`, use the method to determine if the key exists in the . - - - -## Examples - The following code example demonstrates the modification of an collection. In this example, the property is used to modify the dictionary entry with the key `"testKey2"`. This code is part of a larger code example that can be viewed at . - + property to add new elements by setting the value of a key that does not exist in the collection (for example, `myCollection["myNonexistentKey"] = myValue`). However, if the specified key already exists in the , setting the property overwrites the old value. In contrast, the method does not modify existing elements. + + A key cannot be `null`, but a value can be. To distinguish between `null` that is returned because the specified key is not found and `null` that is returned because the value of the specified key is `null`, use the method to determine if the key exists in the . + + + +## Examples + The following code example demonstrates the modification of an collection. In this example, the property is used to modify the dictionary entry with the key `"testKey2"`. This code is part of a larger code example that can be viewed at . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Collections.Specialized.OrderedDictionary1/cpp/ordereddictionary1.cpp" id="Snippet02"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Specialized/OrderedDictionary/Overview/OrderedDictionary1.cs" id="Snippet02"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Specialized.OrderedDictionary1/VB/OrderedDictionary1.vb" id="Snippet02"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Specialized.OrderedDictionary1/VB/OrderedDictionary1.vb" id="Snippet02"::: + ]]> The property is being set and the collection is read-only. @@ -1289,24 +1289,24 @@ Gets an object containing the keys in the collection. An object containing the keys in the collection. - object is not a static copy; instead, the refers back to the keys in the original collection. Therefore, changes to the continue to be reflected in the . - - - -## Examples - The following code example demonstrates the creation and population of an collection, and then prints the contents to the console. In this example, the and properties are passed to a method that displays the contents. This code is part of a larger code example that can be viewed at . - + object is not a static copy; instead, the refers back to the keys in the original collection. Therefore, changes to the continue to be reflected in the . + + + +## Examples + The following code example demonstrates the creation and population of an collection, and then prints the contents to the console. In this example, the and properties are passed to a method that displays the contents. This code is part of a larger code example that can be viewed at . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Collections.Specialized.OrderedDictionary1/cpp/ordereddictionary1.cpp" id="Snippet01"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Specialized/OrderedDictionary/Overview/OrderedDictionary1.cs" id="Snippet01"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Specialized.OrderedDictionary1/VB/OrderedDictionary1.vb" id="Snippet01"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Specialized.OrderedDictionary1/VB/OrderedDictionary1.vb" id="Snippet01"::: + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Collections.Specialized.OrderedDictionary1/cpp/ordereddictionary1.cpp" id="Snippet04"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Specialized/OrderedDictionary/Overview/OrderedDictionary1.cs" id="Snippet04"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Specialized.OrderedDictionary1/VB/OrderedDictionary1.vb" id="Snippet04"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Specialized.OrderedDictionary1/VB/OrderedDictionary1.vb" id="Snippet04"::: + ]]> @@ -1352,17 +1352,17 @@ System.Void - + The source of the deserialization event. Implements the interface and is called back by the deserialization event when deserialization is complete. - The object associated with the current collection is invalid. @@ -1413,22 +1413,22 @@ The key of the entry to remove. Removes the entry with the specified key from the collection. - collection does not contain an entry with the specified key, the remains unchanged and no exception is thrown. - - - -## Examples - The following code example demonstrates the modification of an collection. In this example, the method is used to remove the entry with the key `"keyToDelete"` from the . This code is part of a larger code example that can be viewed at . - + collection does not contain an entry with the specified key, the remains unchanged and no exception is thrown. + + + +## Examples + The following code example demonstrates the modification of an collection. In this example, the method is used to remove the entry with the key `"keyToDelete"` from the . This code is part of a larger code example that can be viewed at . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Collections.Specialized.OrderedDictionary1/cpp/ordereddictionary1.cpp" id="Snippet02"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Specialized/OrderedDictionary/Overview/OrderedDictionary1.cs" id="Snippet02"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Specialized.OrderedDictionary1/VB/OrderedDictionary1.vb" id="Snippet02"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Specialized.OrderedDictionary1/VB/OrderedDictionary1.vb" id="Snippet02"::: + ]]> The collection is read-only. @@ -1481,28 +1481,28 @@ The zero-based index of the entry to remove. Removes the entry at the specified index from the collection. - collection. In this example, the method is used with the property to remove the last entry from the . This code is part of a larger code example that can be viewed at . - + collection. In this example, the method is used with the property to remove the last entry from the . This code is part of a larger code example that can be viewed at . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Collections.Specialized.OrderedDictionary1/cpp/ordereddictionary1.cpp" id="Snippet02"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Specialized/OrderedDictionary/Overview/OrderedDictionary1.cs" id="Snippet02"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Specialized.OrderedDictionary1/VB/OrderedDictionary1.vb" id="Snippet02"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Specialized.OrderedDictionary1/VB/OrderedDictionary1.vb" id="Snippet02"::: + ]]> The collection is read-only. - is less than zero. - + is less than zero. + -or- - + is equal to or greater than . @@ -1759,7 +1759,7 @@ This member is an explicit interface member implementation. It can be used only System.Void - + The source of the deserialization event. @@ -1809,24 +1809,24 @@ This member is an explicit interface member implementation. It can be used only Gets an object containing the values in the collection. An object containing the values in the collection. - object is not a static copy; instead, the refers back to the values in the original collection. Therefore, changes to the continue to be reflected in the . - - - -## Examples - The following code example demonstrates the creation and population of an collection, and then prints the contents to the console. In this example, the and properties are passed to a method that displays the contents. This code is part of a larger code example that can be viewed at . - + object is not a static copy; instead, the refers back to the values in the original collection. Therefore, changes to the continue to be reflected in the . + + + +## Examples + The following code example demonstrates the creation and population of an collection, and then prints the contents to the console. In this example, the and properties are passed to a method that displays the contents. This code is part of a larger code example that can be viewed at . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Collections.Specialized.OrderedDictionary1/cpp/ordereddictionary1.cpp" id="Snippet01"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Specialized/OrderedDictionary/Overview/OrderedDictionary1.cs" id="Snippet01"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Specialized.OrderedDictionary1/VB/OrderedDictionary1.vb" id="Snippet01"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Specialized.OrderedDictionary1/VB/OrderedDictionary1.vb" id="Snippet01"::: + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Collections.Specialized.OrderedDictionary1/cpp/ordereddictionary1.cpp" id="Snippet04"::: :::code language="csharp" source="~/snippets/csharp/System.Collections.Specialized/OrderedDictionary/Overview/OrderedDictionary1.cs" id="Snippet04"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Specialized.OrderedDictionary1/VB/OrderedDictionary1.vb" id="Snippet04"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Specialized.OrderedDictionary1/VB/OrderedDictionary1.vb" id="Snippet04"::: + ]]> diff --git a/xml/System.Collections/BitArray.xml b/xml/System.Collections/BitArray.xml index 87a807ae505..42a4dcdd37f 100644 --- a/xml/System.Collections/BitArray.xml +++ b/xml/System.Collections/BitArray.xml @@ -79,34 +79,34 @@ Manages a compact array of bit values, which are represented as Booleans, where indicates that the bit is on (1) and indicates the bit is off (0). - class is a collection class in which the capacity is always the same as the count. Elements are added to a by increasing the property; elements are deleted by decreasing the property. The size of a is controlled by the client; indexing past the end of the throws an . The class provides methods that are not found in other collections, including those that allow multiple elements to be modified at once using a filter, such as , , , , and . - - The class is a structure that provides the same functionality as , but with faster performance. is faster because it is a value type and therefore allocated on the stack, whereas is a reference type and, therefore, allocated on the heap. - - can store exactly 32 bits, whereas can store a variable number of bits. stores both bit flags and small integers, thereby making it ideal for data that is not exposed to the user. However, if the number of required bit flags is unknown, is variable, or is greater than 32, use instead. - - is in the namespace; is in the namespace. - - Elements in this collection can be accessed using an integer index. Indexes in this collection are zero-based. - - - -## Examples - The following code example shows how to create and initialize a and how to print out its values. - + class is a collection class in which the capacity is always the same as the count. Elements are added to a by increasing the property; elements are deleted by decreasing the property. The size of a is controlled by the client; indexing past the end of the throws an . The class provides methods that are not found in other collections, including those that allow multiple elements to be modified at once using a filter, such as , , , , and . + + The class is a structure that provides the same functionality as , but with faster performance. is faster because it is a value type and therefore allocated on the stack, whereas is a reference type and, therefore, allocated on the heap. + + can store exactly 32 bits, whereas can store a variable number of bits. stores both bit flags and small integers, thereby making it ideal for data that is not exposed to the user. However, if the number of required bit flags is unknown, is variable, or is greater than 32, use instead. + + is in the namespace; is in the namespace. + + Elements in this collection can be accessed using an integer index. Indexes in this collection are zero-based. + + + +## Examples + The following code example shows how to create and initialize a and how to print out its values. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic BitArray Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections/BitArray/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic BitArray Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic BitArray Example/VB/source.vb" id="Snippet1"::: + ]]> - Public static ( in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe. - - This implementation does not provide a synchronized (thread safe) wrapper for a . - + Public static ( in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe. + + This implementation does not provide a synchronized (thread safe) wrapper for a . + 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. @@ -162,11 +162,11 @@ An array of Booleans to copy. Initializes a new instance of the class that contains bit values copied from the specified array of Booleans. - @@ -213,13 +213,13 @@ An array of bytes containing the values to copy, where each byte represents eight consecutive bits. Initializes a new instance of the class that contains bit values copied from the specified array of bytes. - @@ -267,11 +267,11 @@ The to copy. Initializes a new instance of the class that contains bit values copied from the specified . - @@ -318,11 +318,11 @@ The number of bit values in the new . Initializes a new instance of the class that can hold the specified number of bit values, which are initially set to . - @@ -369,13 +369,13 @@ An array of integers containing the values to copy, where each integer represents 32 consecutive bits. Initializes a new instance of the class that contains bit values copied from the specified array of 32-bit integers. - @@ -425,11 +425,11 @@ The Boolean value to assign to each bit. Initializes a new instance of the class that can hold the specified number of bit values, which are initially set to the specified value. - @@ -480,22 +480,22 @@ Performs the bitwise AND operation between the elements of the current object and the corresponding elements in the specified array. The current object will be modified to store the result of the bitwise AND operation. An array containing the result of the bitwise AND operation, which is a reference to the current object. - . - - - -## Examples - The following code example shows how to perform the bitwise AND operation between two objects. - + . + + + +## Examples + The following code example shows how to perform the bitwise AND operation between two objects. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic BitArray.And Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections/BitArray/And/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic BitArray.And Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic BitArray.And Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -546,15 +546,15 @@ Creates a shallow copy of the . A shallow copy of the . - . - + . + ]]> @@ -597,32 +597,32 @@ System.Void - - + + The one-dimensional that is the destination of the elements copied from . The must have zero-based indexing. The zero-based index in at which copying begins. Copies the entire to a compatible one-dimensional , starting at the specified index of the target array. - to copy the elements. - - This method is an `O(n)` operation, where `n` is . - - - -## Examples - The following code example shows how to copy a into a one-dimensional . - + to copy the elements. + + This method is an `O(n)` operation, where `n` is . + + + +## Examples + The following code example shows how to copy a into a one-dimensional . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic BitArray.CopyTo Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections/BitArray/CopyTo/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic BitArray.CopyTo Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic BitArray.CopyTo Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -630,10 +630,10 @@ is less than zero. - is multidimensional. - - -or- - + is multidimensional. + + -or- + The number of elements in the source is greater than the available space from to the end of the destination . The type of the source cannot be cast automatically to the type of the destination . @@ -680,13 +680,13 @@ Gets the number of elements contained in the . The number of elements contained in the . - and return the same value. can be set to a specific value, but is read-only. - - Retrieving the value of this property is an `O(1)` operation. - + and return the same value. can be set to a specific value, but is read-only. + + Retrieving the value of this property is an `O(1)` operation. + ]]> @@ -735,27 +735,27 @@ Gets the value of the bit at a specific position in the . The value of the bit at position . - . - + . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic BitArray.Get Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections/BitArray/Get/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic BitArray.Get Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic BitArray.Get Example/VB/source.vb" id="Snippet1"::: + ]]> - is less than zero. - - -or- - + is less than zero. + + -or- + is greater than or equal to the number of elements in the . @@ -803,25 +803,25 @@ Returns an enumerator that iterates through the . An for the entire . - also brings the enumerator back to this position. At this position, 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. - - 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. - - The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - - This method is an `O(1)` operation. - + also brings the enumerator back to this position. At this position, 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. + + 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. + + The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. + + This method is an `O(1)` operation. + ]]> @@ -925,17 +925,17 @@ Gets a value indicating whether the is read-only. This property is always . - implements the property because it is required by the interface. - - A collection that is read-only does not allow the addition, removal, or modification of elements after the collection is created. - - A collection that is read-only is simply a collection with a wrapper that prevents modifying the collection; therefore, if changes are made to the underlying collection, the read-only collection reflects those changes. - - This method is an `O(1)` operation. - + implements the property because it is required by the interface. + + A collection that is read-only does not allow the addition, removal, or modification of elements after the collection is created. + + A collection that is read-only is simply a collection with a wrapper that prevents modifying the collection; therefore, if changes are made to the underlying collection, the read-only collection reflects those changes. + + This method is an `O(1)` operation. + ]]> @@ -981,24 +981,24 @@ Gets a value indicating whether access to the is synchronized (thread safe). This property is always . - implements the property because it is required by the interface. - - 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. - - - -## Examples - The following code example shows how to lock the collection using the during the entire enumeration. - + implements the property because it is required by the interface. + + 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. + + + +## Examples + The following code example shows how to lock the collection using the during the entire enumeration. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic BitArray Example/CPP/source2.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Collections/BitArray/Overview/source2.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic BitArray Example/VB/source2.vb" id="Snippet2"::: - - This method is an `O(1)` operation. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic BitArray Example/VB/source2.vb" id="Snippet2"::: + + This method is an `O(1)` operation. + ]]> @@ -1048,22 +1048,22 @@ Gets or sets the value of the bit at a specific position in the . The value of the bit at position . - property. Visual Basic implements as a default property, which provides the same indexing functionality. - - Retrieving the value of this property is an `O(1)` operation; setting the property is also an `O(1)` operation. - + property. Visual Basic implements as a default property, which provides the same indexing functionality. + + Retrieving the value of this property is an `O(1)` operation; setting the property is also an `O(1)` operation. + ]]> - is less than zero. - - -or- - + is less than zero. + + -or- + is equal to or greater than . @@ -1157,17 +1157,17 @@ The current is updated and returned. Gets or sets the number of elements in the . The number of elements in the . - and return the same value. can be set to a specific value, but is read-only. - - If is set to a value that is less than , the is truncated and the elements after the index `value` -1 are deleted. - - If is set to a value that is greater than , the new elements are set to `false`. - - Retrieving the value of this property is an `O(1)` operation. Setting this property is an `O(n)` operation. - + and return the same value. can be set to a specific value, but is read-only. + + If is set to a value that is less than , the is truncated and the elements after the index `value` -1 are deleted. + + If is set to a value that is greater than , the new elements are set to `false`. + + Retrieving the value of this property is an `O(1)` operation. Setting this property is an `O(n)` operation. + ]]> The property is set to a value that is less than zero. @@ -1214,20 +1214,20 @@ The current is updated and returned. Inverts all the bit values in the current , so that elements set to are changed to , and elements set to are changed to . The current instance with inverted bit values. - . - - - -## Examples - The following code example shows how to apply NOT to a . - + . + + + +## Examples + The following code example shows how to apply NOT to a . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic BitArray.Not Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections/BitArray/Not/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic BitArray.Not Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic BitArray.Not Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -1276,22 +1276,22 @@ The current is updated and returned. Performs the bitwise OR operation between the elements of the current object and the corresponding elements in the specified array. The current object will be modified to store the result of the bitwise OR operation. An array containing the result of the bitwise OR operation, which is a reference to the current object. - . - - - -## Examples - The following code example shows how to perform the OR operation between two objects. - + . + + + +## Examples + The following code example shows how to perform the OR operation between two objects. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic BitArray.Or Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections/BitArray/Or/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic BitArray.Or Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic BitArray.Or Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -1394,27 +1394,27 @@ The current is updated and returned. The Boolean value to assign to the bit. Sets the bit at a specific position in the to the specified value. - . - + . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic BitArray.Get Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections/BitArray/Get/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic BitArray.Get Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic BitArray.Get Example/VB/source.vb" id="Snippet1"::: + ]]> - is less than zero. - - -or- - + is less than zero. + + -or- + is greater than or equal to the number of elements in the . @@ -1461,20 +1461,20 @@ The current is updated and returned. The Boolean value to assign to all bits. Sets all bits in the to the specified value. - . - - - -## Examples - The following code example shows how to set and get specific elements in a . - + . + + + +## Examples + The following code example shows how to set and get specific elements in a . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic BitArray.Get Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections/BitArray/Get/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic BitArray.Get Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic BitArray.Get Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -1520,24 +1520,24 @@ The current is updated and returned. Gets an object that can be used to synchronize access to the . An object that can be used to synchronize access to 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. - - 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. - - - -## Examples - The following code example shows how to lock the collection using the during the entire enumeration. - + 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. + + 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. + + + +## Examples + The following code example shows how to lock the collection using the during the entire enumeration. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic BitArray Example/CPP/source2.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Collections/BitArray/Overview/source2.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic BitArray Example/VB/source2.vb" id="Snippet2"::: - - Retrieving the value of this property is an `O(1)` operation. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic BitArray Example/VB/source2.vb" id="Snippet2"::: + + Retrieving the value of this property is an `O(1)` operation. + ]]> @@ -1738,22 +1738,22 @@ This member is an explicit interface member implementation. It can be used only Performs the bitwise exclusive OR operation between the elements of the current object against the corresponding elements in the specified array. The current object will be modified to store the result of the bitwise exclusive OR operation. An array containing the result of the bitwise exclusive OR operation, which is a reference to the current object. - . - - - -## Examples - The following code example shows how to perform the XOR operation between two objects. - + . + + + +## Examples + The following code example shows how to perform the XOR operation between two objects. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic BitArray.Xor Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections/BitArray/Xor/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic BitArray.Xor Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic BitArray.Xor Example/VB/source.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.Collections/Comparer.xml b/xml/System.Collections/Comparer.xml index feded51a8fa..5b54a6d264a 100644 --- a/xml/System.Collections/Comparer.xml +++ b/xml/System.Collections/Comparer.xml @@ -94,22 +94,22 @@ Compares two objects for equivalence, where string comparisons are case-sensitive. - interface. The class is the implementation of the interface that performs case-insensitive string comparisons. is the generic equivalent of this class. - - Comparison procedures use the of the current thread unless otherwise specified. String comparisons might have different results depending on the culture. For more information on culture-specific comparisons, see the namespace and [Globalization and Localization](/dotnet/standard/globalization-localization/). - - - -## Examples - The following code example shows how returns different values depending on the culture associated with the . - + interface. The class is the implementation of the interface that performs case-insensitive string comparisons. is the generic equivalent of this class. + + Comparison procedures use the of the current thread unless otherwise specified. String comparisons might have different results depending on the culture. For more information on culture-specific comparisons, see the namespace and [Globalization and Localization](/dotnet/standard/globalization-localization/). + + + +## Examples + The following code example shows how returns different values depending on the culture associated with the . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Collections.Comparer/CPP/comparercultures.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections/Comparer/Overview/comparercultures.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Comparer/VB/comparercultures.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Comparer/VB/comparercultures.vb" id="Snippet1"::: + ]]> @@ -167,20 +167,20 @@ The to use for the new . Initializes a new instance of the class using the specified . - to determine the sort order and casing rules. String comparisons might have different results depending on the culture. For more information on culture-specific comparisons, see the namespace and [Globalization and Localization](/dotnet/standard/globalization-localization/). - - - -## Examples - The following code example shows how returns different values depending on the culture associated with the . - + to determine the sort order and casing rules. String comparisons might have different results depending on the culture. For more information on culture-specific comparisons, see the namespace and [Globalization and Localization](/dotnet/standard/globalization-localization/). + + + +## Examples + The following code example shows how returns different values depending on the culture associated with the . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Collections.Comparer/CPP/comparercultures.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections/Comparer/Overview/comparercultures.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Comparer/VB/comparercultures.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Comparer/VB/comparercultures.vb" id="Snippet1"::: + ]]> @@ -249,50 +249,50 @@ The first object to compare. The second object to compare. Performs a case-sensitive comparison of two objects of the same type and returns a value indicating whether one is less than, equal to, or greater than the other. - A signed integer that indicates the relative values of and , as shown in the following table. - - Value - - Meaning - - Less than zero - - is less than . - - Zero - - equals . - - Greater than zero - - is greater than . - + A signed integer that indicates the relative values of and , as shown in the following table. + + Value + + Meaning + + Less than zero + + is less than . + + Zero + + equals . + + Greater than zero + + is greater than . + - , then `a`. `CompareTo` (`b`) is returned; otherwise, if `b` implements , then the negated result of `b`. `CompareTo` (`a`) is returned. - - Comparing `null` with any type is allowed and does not generate an exception when using . When sorting, `null` is considered to be less than any other object. - - String comparisons might have different results depending on the culture. For more information on culture-specific comparisons, see the namespace and [Globalization and Localization](/dotnet/standard/globalization-localization/). - - - -## Examples - The following code example shows how returns different values depending on the culture associated with the . - + , then `a`. `CompareTo` (`b`) is returned; otherwise, if `b` implements , then the negated result of `b`. `CompareTo` (`a`) is returned. + + Comparing `null` with any type is allowed and does not generate an exception when using . When sorting, `null` is considered to be less than any other object. + + String comparisons might have different results depending on the culture. For more information on culture-specific comparisons, see the namespace and [Globalization and Localization](/dotnet/standard/globalization-localization/). + + + +## Examples + The following code example shows how returns different values depending on the culture associated with the . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Collections.Comparer/CPP/comparercultures.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections/Comparer/Overview/comparercultures.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Comparer/VB/comparercultures.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Comparer/VB/comparercultures.vb" id="Snippet1"::: + ]]> - Neither nor implements the interface. - - -or- - + Neither nor implements the interface. + + -or- + and are of different types and neither one can handle comparisons with the other. @@ -345,11 +345,11 @@ Represents an instance of that is associated with the of the current thread. This field is read-only. - of the current thread to determine the sort order and casing rules. String comparisons might have different results depending on the culture. For more information on culture-specific comparisons, see the namespace and [Globalization and Localization](/dotnet/standard/globalization-localization/). - + of the current thread to determine the sort order and casing rules. String comparisons might have different results depending on the culture. For more information on culture-specific comparisons, see the namespace and [Globalization and Localization](/dotnet/standard/globalization-localization/). + ]]> @@ -401,20 +401,20 @@ Represents an instance of that is associated with . This field is read-only. - to determine the sort order and casing rules. String comparisons might have different results depending on the culture. For more information on culture-specific comparisons, see the namespace and [Globalization and Localization](/dotnet/standard/globalization-localization/). - - - -## Examples - The following code example shows how returns different values depending on the culture associated with the . - + to determine the sort order and casing rules. String comparisons might have different results depending on the culture. For more information on culture-specific comparisons, see the namespace and [Globalization and Localization](/dotnet/standard/globalization-localization/). + + + +## Examples + The following code example shows how returns different values depending on the culture associated with the . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Collections.Comparer/CPP/comparercultures.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections/Comparer/Overview/comparercultures.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Comparer/VB/comparercultures.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Comparer/VB/comparercultures.vb" id="Snippet1"::: + ]]> @@ -479,19 +479,19 @@ System.Void - - + + The object to populate with data. The context information about the source or destination of the serialization. Populates a object with the data required for serialization. - method is not visible to COM clients by default, inheriting the class can expose it and can cause undesirable behavior in COM clients. - + method is not visible to COM clients by default, inheriting the class can expose it and can cause undesirable behavior in COM clients. + ]]> diff --git a/xml/System.Collections/Hashtable.xml b/xml/System.Collections/Hashtable.xml index 4156a2799a9..9c3e1e61017 100644 --- a/xml/System.Collections/Hashtable.xml +++ b/xml/System.Collections/Hashtable.xml @@ -116,61 +116,61 @@ Represents a collection of key/value pairs that are organized based on the hash code of the key. - object. A key cannot be `null`, but a value can be. +Each element is a key/value pair stored in a object. A key cannot be `null`, but a value can be. > [!IMPORTANT] > We don't recommend that you use the `Hashtable` class for new development. Instead, we recommend that you use the generic class. For more information, see [Non-generic collections shouldn't be used](https://github.com/dotnet/platform-compat/blob/master/docs/DE0006.md) on GitHub. - - The objects used as keys by a are required to override the method (or the interface) and the method (or the interface). The implementation of both methods and interfaces must handle case sensitivity the same way; otherwise, the might behave incorrectly. For example, when creating a , you must use the class (or any case-insensitive implementation) with the class (or any case-insensitive implementation). - - Furthermore, these methods must produce the same results when called with the same parameters while the key exists in the . An alternative is to use a constructor with an parameter. If key equality were simply reference equality, the inherited implementation of and would suffice. - - Key objects must be immutable as long as they are used as keys in the . - - When an element is added to the , the element is placed into a bucket based on the hash code of the key. Subsequent lookups of the key use the hash code of the key to search in only one particular bucket, thus substantially reducing the number of key comparisons required to find an element. - - The load factor of a determines the maximum ratio of elements to buckets. Smaller load factors cause faster average lookup times at the cost of increased memory consumption. The default load factor of 1.0 generally provides the best balance between speed and size. A different load factor can also be specified when the is created. - - As elements are added to a , the actual load factor of the increases. When the actual load factor reaches the specified load factor, the number of buckets in the is automatically increased to the smallest prime number that is larger than twice the current number of buckets. - - Each key object in the must provide its own hash function, which can be accessed by calling . However, any object implementing can be passed to a constructor, and that hash function is used for all objects in the table. - - The capacity of a is the number of elements the can hold. As elements are added to a , the capacity is automatically increased as required through reallocation. - - **.NET Framework only:** For very large objects, you can increase the maximum capacity to 2 billion elements on a 64-bit system by setting the `enabled` attribute of the [``](/dotnet/framework/configure-apps/file-schema/runtime/gcallowverylargeobjects-element) configuration element to `true` in the run-time environment. - - The `foreach` statement of the C# language (`For Each` in Visual Basic) returns an object of the type of the elements in the collection. Since each element of the is a key/value pair, the element type is not the type of the key or the type of the value. Instead, the element type is . For example: - + + The objects used as keys by a are required to override the method (or the interface) and the method (or the interface). The implementation of both methods and interfaces must handle case sensitivity the same way; otherwise, the might behave incorrectly. For example, when creating a , you must use the class (or any case-insensitive implementation) with the class (or any case-insensitive implementation). + + Furthermore, these methods must produce the same results when called with the same parameters while the key exists in the . An alternative is to use a constructor with an parameter. If key equality were simply reference equality, the inherited implementation of and would suffice. + + Key objects must be immutable as long as they are used as keys in the . + + When an element is added to the , the element is placed into a bucket based on the hash code of the key. Subsequent lookups of the key use the hash code of the key to search in only one particular bucket, thus substantially reducing the number of key comparisons required to find an element. + + The load factor of a determines the maximum ratio of elements to buckets. Smaller load factors cause faster average lookup times at the cost of increased memory consumption. The default load factor of 1.0 generally provides the best balance between speed and size. A different load factor can also be specified when the is created. + + As elements are added to a , the actual load factor of the increases. When the actual load factor reaches the specified load factor, the number of buckets in the is automatically increased to the smallest prime number that is larger than twice the current number of buckets. + + Each key object in the must provide its own hash function, which can be accessed by calling . However, any object implementing can be passed to a constructor, and that hash function is used for all objects in the table. + + The capacity of a is the number of elements the can hold. As elements are added to a , the capacity is automatically increased as required through reallocation. + + **.NET Framework only:** For very large objects, you can increase the maximum capacity to 2 billion elements on a 64-bit system by setting the `enabled` attribute of the [``](/dotnet/framework/configure-apps/file-schema/runtime/gcallowverylargeobjects-element) configuration element to `true` in the run-time environment. + + The `foreach` statement of the C# language (`For Each` in Visual Basic) returns an object of the type of the elements in the collection. Since each element of the is a key/value pair, the element type is not the type of the key or the type of the value. Instead, the element type is . For example: + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Collections.Hashtable_ClassExample/cpp/remarks.cpp" id="Snippet01"::: :::code language="csharp" source="~/snippets/csharp/System.Collections/Hashtable/Overview/remarks.cs" id="Snippet01"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Hashtable_ClassExample/vb/remarks.vb" id="Snippet01"::: - - The `foreach` statement is a wrapper around the enumerator, which only allows reading from, not writing to, the collection. - - Because serializing and deserializing an enumerator for a can cause the elements to become reordered, it is not possible to continue enumeration without calling the method. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Hashtable_ClassExample/vb/remarks.vb" id="Snippet01"::: + + The `foreach` statement is a wrapper around the enumerator, which only allows reading from, not writing to, the collection. + + Because serializing and deserializing an enumerator for a can cause the elements to become reordered, it is not possible to continue enumeration without calling the method. + > [!NOTE] -> Because keys can be inherited and their behavior changed, their absolute uniqueness cannot be guaranteed by comparisons using the method. - - - -## Examples - The following example shows how to create, initialize and perform various functions to a and how to print out its keys and values. - +> Because keys can be inherited and their behavior changed, their absolute uniqueness cannot be guaranteed by comparisons using the method. + + + +## Examples + The following example shows how to create, initialize and perform various functions to a and how to print out its keys and values. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Collections.Hashtable_ClassExample/cpp/hashtable_example.cpp" id="Snippet00"::: :::code language="csharp" source="~/snippets/csharp/System.Collections/Hashtable/Overview/hashtable_example.cs" id="Snippet00"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Hashtable_ClassExample/vb/hashtable_example.vb" id="Snippet00"::: - :::code language="powershell" source="~/snippets/powershell/VS_Snippets_CLR_System/system.collections.hashtable.class/ps/hashtable.ps1" id="Snippet00"::: - + :::code language="powershell" source="~/snippets/powershell/VS_Snippets_CLR_System/system.collections.hashtable.class/ps/hashtable.ps1" id="Snippet00"::: + ]]> - is thread safe for use by multiple reader threads and a single writing thread. It is thread safe for multi-thread use when only one of the threads perform write (update) operations, which allows for lock-free reads provided that the writers are serialized to the . To support multiple writers all operations on the must be done through the wrapper returned by the method, provided that there are no threads reading the object. - + is thread safe for use by multiple reader threads and a single writing thread. It is thread safe for multi-thread use when only one of the threads perform write (update) operations, which allows for lock-free reads provided that the writers are serialized to the . To support multiple writers all operations on the must be done through the wrapper returned by the method, provided that there are no threads reading the object. + 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. @@ -232,30 +232,30 @@ Each element is a key/value pair stored in a Initializes a new, empty instance of the class using the default initial capacity, load factor, hash code provider, and comparer. - object. The default hash code provider is the key's implementation of . - - The comparer determines whether two keys are equal. Every key in a must be unique. The default comparer is the key's implementation of . - - This constructor is an `O(1)` operation. - - - -## Examples - The following code example creates hash tables using different constructors and demonstrates the differences in the behavior of the hash tables, even if each one contains the same elements. - + object. The default hash code provider is the key's implementation of . + + The comparer determines whether two keys are equal. Every key in a must be unique. The default comparer is the key's implementation of . + + This constructor is an `O(1)` operation. + + + +## Examples + The following code example creates hash tables using different constructors and demonstrates the differences in the behavior of the hash tables, even if each one contains the same elements. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Collections.Hashtable_ctor/CPP/hashtable_ctor.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections/Hashtable/.ctor/hashtable_ctor.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Hashtable_ctor/VB/hashtable_ctor.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Hashtable_ctor/VB/hashtable_ctor.vb" id="Snippet1"::: + ]]> @@ -308,32 +308,32 @@ Each element is a key/value pair stored in a The object to copy to a new object. Initializes a new instance of the class by copying the elements from the specified dictionary to the new object. The new object has an initial capacity equal to the number of elements copied, and uses the default load factor, hash code provider, and comparer. - object. The default hash code provider is the key's implementation of . - - The comparer determines whether two keys are equal. Every key in a must be unique. The default comparer is the key's implementation of . - - The elements of the new are sorted in the same order in which the enumerator iterates through the object. - - This constructor is an `O(n)` operation, where `n` is the number of elements in the `d` parameter. - - - -## Examples - The following code example creates hash tables using different constructors and demonstrates the differences in the behavior of the hash tables, even if each one contains the same elements. - + object. The default hash code provider is the key's implementation of . + + The comparer determines whether two keys are equal. Every key in a must be unique. The default comparer is the key's implementation of . + + The elements of the new are sorted in the same order in which the enumerator iterates through the object. + + This constructor is an `O(n)` operation, where `n` is the number of elements in the `d` parameter. + + + +## Examples + The following code example creates hash tables using different constructors and demonstrates the differences in the behavior of the hash tables, even if each one contains the same elements. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Collections.Hashtable_ctorDictionary/CPP/hashtable_ctordictionary.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections/Hashtable/.ctor/hashtable_ctordictionary.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Hashtable_ctorDictionary/VB/hashtable_ctordictionary.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Hashtable_ctorDictionary/VB/hashtable_ctordictionary.vb" id="Snippet1"::: + ]]> @@ -392,41 +392,41 @@ Each element is a key/value pair stored in a - The object that defines the hash code provider and the comparer to use with the object. - - -or- - + The object that defines the hash code provider and the comparer to use with the object. + + -or- + to use the default hash code provider and the default comparer. The default hash code provider is each key's implementation of and the default comparer is each key's implementation of . Initializes a new, empty instance of the class using the default initial capacity and load factor, and the specified object. - object includes both the hash code provider and the comparer. If an is used in the constructor, the objects used as keys in the object are not required to override the and methods. - - The hash code provider dispenses hash codes for keys in the . The default hash code provider is the key's implementation of . - - The comparer determines whether two keys are equal. Every key in a must be unique. The default comparer is the key's implementation of . - - The enables scenarios such as doing lookups with case-insensitive strings. - - This constructor is an `O(1)` operation. - - - -## Examples - The following code example creates hash tables using different constructors and demonstrates the differences in the behavior of the hash tables, even if each one contains the same elements. - + object includes both the hash code provider and the comparer. If an is used in the constructor, the objects used as keys in the object are not required to override the and methods. + + The hash code provider dispenses hash codes for keys in the . The default hash code provider is the key's implementation of . + + The comparer determines whether two keys are equal. Every key in a must be unique. The default comparer is the key's implementation of . + + The enables scenarios such as doing lookups with case-insensitive strings. + + This constructor is an `O(1)` operation. + + + +## Examples + The following code example creates hash tables using different constructors and demonstrates the differences in the behavior of the hash tables, even if each one contains the same elements. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Collections.Hashtable_ctor/CPP/hashtable_ctor.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections/Hashtable/.ctor/hashtable_ctor.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Hashtable_ctor/VB/hashtable_ctor.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Hashtable_ctor/VB/hashtable_ctor.vb" id="Snippet1"::: + ]]> @@ -478,30 +478,30 @@ Each element is a key/value pair stored in a The approximate number of elements that the object can initially contain. Initializes a new, empty instance of the class using the specified initial capacity, and the default load factor, hash code provider, and comparer. - object. Capacity is automatically increased as required based on the load factor. - - The load factor is the maximum ratio of elements to buckets. A smaller load factor means faster lookup at the cost of increased memory consumption. - - When the actual load factor reaches the specified load factor, the number of buckets is automatically increased to the smallest prime number that is larger than twice the current number of buckets. - - The hash code provider dispenses hash codes for keys in the . The default hash code provider is the key's implementation of . - - The comparer determines whether two keys are equal. Every key in a must be unique. The default comparer is the key's implementation of . - - This constructor is an `O(n)` operation, where `n` is `capacity`. - - - -## Examples - The following code example creates hash tables using different constructors and demonstrates the differences in the behavior of the hash tables, even if each one contains the same elements. - + object. Capacity is automatically increased as required based on the load factor. + + The load factor is the maximum ratio of elements to buckets. A smaller load factor means faster lookup at the cost of increased memory consumption. + + When the actual load factor reaches the specified load factor, the number of buckets is automatically increased to the smallest prime number that is larger than twice the current number of buckets. + + The hash code provider dispenses hash codes for keys in the . The default hash code provider is the key's implementation of . + + The comparer determines whether two keys are equal. Every key in a must be unique. The default comparer is the key's implementation of . + + This constructor is an `O(n)` operation, where `n` is `capacity`. + + + +## Examples + The following code example creates hash tables using different constructors and demonstrates the differences in the behavior of the hash tables, even if each one contains the same elements. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Collections.Hashtable_ctorInt/CPP/hashtable_ctorint.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections/Hashtable/.ctor/hashtable_ctorint.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Hashtable_ctorInt/VB/hashtable_ctorint.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Hashtable_ctorInt/VB/hashtable_ctorint.vb" id="Snippet1"::: + ]]> @@ -562,43 +562,43 @@ Each element is a key/value pair stored in a The object to copy to a new object. - The object that defines the hash code provider and the comparer to use with the . - - -or- - + The object that defines the hash code provider and the comparer to use with the . + + -or- + to use the default hash code provider and the default comparer. The default hash code provider is each key's implementation of and the default comparer is each key's implementation of . Initializes a new instance of the class by copying the elements from the specified dictionary to a new object. The new object has an initial capacity equal to the number of elements copied, and uses the default load factor and the specified object. - object includes both the hash code provider and the comparer. If an is used in the constructor, the objects used as keys in the object are not required to override the and methods. - - The hash code provider dispenses hash codes for keys in the . The default hash code provider is the key's implementation of . - - The comparer determines whether two keys are equal. Every key in a must be unique. The default comparer is the key's implementation of . - - The enables scenarios such as doing lookups with case-insensitive strings. - - The elements of the new are sorted in the same order in which the enumerator iterates through the object. - - This constructor is an `O(n)` operation, where `n` is the number of elements in the `d` parameter. - - - -## Examples - The following code example creates hash tables using different constructors and demonstrates the differences in the behavior of the hash tables, even if each one contains the same elements. - + object includes both the hash code provider and the comparer. If an is used in the constructor, the objects used as keys in the object are not required to override the and methods. + + The hash code provider dispenses hash codes for keys in the . The default hash code provider is the key's implementation of . + + The comparer determines whether two keys are equal. Every key in a must be unique. The default comparer is the key's implementation of . + + The enables scenarios such as doing lookups with case-insensitive strings. + + The elements of the new are sorted in the same order in which the enumerator iterates through the object. + + This constructor is an `O(n)` operation, where `n` is the number of elements in the `d` parameter. + + + +## Examples + The following code example creates hash tables using different constructors and demonstrates the differences in the behavior of the hash tables, even if each one contains the same elements. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Collections.Hashtable_ctorDictionary/CPP/hashtable_ctordictionary.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections/Hashtable/.ctor/hashtable_ctordictionary.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Hashtable_ctorDictionary/VB/hashtable_ctordictionary.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Hashtable_ctorDictionary/VB/hashtable_ctordictionary.vb" id="Snippet1"::: + ]]> @@ -655,41 +655,41 @@ Each element is a key/value pair stored in a A number in the range from 0.1 through 1.0 that is multiplied by the default value which provides the best performance. The result is the maximum ratio of elements to buckets. Initializes a new instance of the class by copying the elements from the specified dictionary to the new object. The new object has an initial capacity equal to the number of elements copied, and uses the specified load factor, and the default hash code provider and comparer. - object. The default hash code provider is the key's implementation of . - - The comparer determines whether two keys are equal. Every key in a must be unique. The default comparer is the key's implementation of . - - The elements of the new are sorted in the same order in which the enumerator iterates through the object. - - This constructor is an `O(n)` operation, where `n` is the number of elements in the `d` parameter. - - - -## Examples - The following code example creates hash tables using different constructors and demonstrates the differences in the behavior of the hash tables, even if each one contains the same elements. - + object. The default hash code provider is the key's implementation of . + + The comparer determines whether two keys are equal. Every key in a must be unique. The default comparer is the key's implementation of . + + The elements of the new are sorted in the same order in which the enumerator iterates through the object. + + This constructor is an `O(n)` operation, where `n` is the number of elements in the `d` parameter. + + + +## Examples + The following code example creates hash tables using different constructors and demonstrates the differences in the behavior of the hash tables, even if each one contains the same elements. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Collections.Hashtable_ctorDictionaryFloat/CPP/hashtable_ctordictionaryfloat.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections/Hashtable/.ctor/hashtable_ctordictionaryfloat.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Hashtable_ctorDictionaryFloat/VB/hashtable_ctordictionaryfloat.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Hashtable_ctorDictionaryFloat/VB/hashtable_ctordictionaryfloat.vb" id="Snippet1"::: + ]]> is . - is less than 0.1. - - -or- - + is less than 0.1. + + -or- + is greater than 1.0. @@ -753,48 +753,48 @@ Each element is a key/value pair stored in a - - + + - The object that supplies the hash codes for all keys in the object. - - -or- - + The object that supplies the hash codes for all keys in the object. + + -or- + to use the default hash code provider, which is each key's implementation of . - The object to use to determine whether two keys are equal. - - -or- - + The object to use to determine whether two keys are equal. + + -or- + to use the default comparer, which is each key's implementation of . Initializes a new, empty instance of the class using the default initial capacity and load factor, and the specified hash code provider and comparer. - object. The default hash code provider is the key's implementation of . - - The comparer determines whether two keys are equal. Every key in a must be unique. The default comparer is the key's implementation of . - - The custom hash code provider and the custom comparer enable scenarios such as doing lookups with case-insensitive strings. - - This constructor is an `O(1)` operation. - - - -## Examples - The following code example creates hash tables using different constructors and demonstrates the differences in the behavior of the hash tables, even if each one contains the same elements. - + object. The default hash code provider is the key's implementation of . + + The comparer determines whether two keys are equal. Every key in a must be unique. The default comparer is the key's implementation of . + + The custom hash code provider and the custom comparer enable scenarios such as doing lookups with case-insensitive strings. + + This constructor is an `O(1)` operation. + + + +## Examples + The following code example creates hash tables using different constructors and demonstrates the differences in the behavior of the hash tables, even if each one contains the same elements. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Collections.Hashtable_ctor/CPP/hashtable_ctor.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections/Hashtable/.ctor/hashtable_ctor.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Hashtable_ctor/VB/hashtable_ctor.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Hashtable_ctor/VB/hashtable_ctor.vb" id="Snippet1"::: + ]]> @@ -854,41 +854,41 @@ Each element is a key/value pair stored in a The approximate number of elements that the object can initially contain. - The object that defines the hash code provider and the comparer to use with the . - - -or- - + The object that defines the hash code provider and the comparer to use with the . + + -or- + to use the default hash code provider and the default comparer. The default hash code provider is each key's implementation of and the default comparer is each key's implementation of . Initializes a new, empty instance of the class using the specified initial capacity and , and the default load factor. - object. Capacity is automatically increased as required based on the load factor. - - The load factor is the maximum ratio of elements to buckets. A smaller load factor means faster lookup at the cost of increased memory consumption. - - When the actual load factor reaches the specified load factor, the number of buckets is automatically increased to the smallest prime number that is larger than twice the current number of buckets. - - The object includes both the hash code provider and the comparer. If an is used in the constructor, the objects used as keys in the are not required to override the and methods. - - The hash code provider dispenses hash codes for keys in the . The default hash code provider is the key's implementation of . - - The comparer determines whether two keys are equal. Every key in a must be unique. The default comparer is the key's implementation of . - - The enables scenarios such as doing lookups with case-insensitive strings. - - This constructor is an `O(n)` operation, where `n` is the `capacity` parameter. - - - -## Examples - The following code example creates hash tables using different constructors and demonstrates the differences in the behavior of the hash tables, even if each one contains the same elements. - + object. Capacity is automatically increased as required based on the load factor. + + The load factor is the maximum ratio of elements to buckets. A smaller load factor means faster lookup at the cost of increased memory consumption. + + When the actual load factor reaches the specified load factor, the number of buckets is automatically increased to the smallest prime number that is larger than twice the current number of buckets. + + The object includes both the hash code provider and the comparer. If an is used in the constructor, the objects used as keys in the are not required to override the and methods. + + The hash code provider dispenses hash codes for keys in the . The default hash code provider is the key's implementation of . + + The comparer determines whether two keys are equal. Every key in a must be unique. The default comparer is the key's implementation of . + + The enables scenarios such as doing lookups with case-insensitive strings. + + This constructor is an `O(n)` operation, where `n` is the `capacity` parameter. + + + +## Examples + The following code example creates hash tables using different constructors and demonstrates the differences in the behavior of the hash tables, even if each one contains the same elements. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Collections.Hashtable_ctorInt/CPP/hashtable_ctorint.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections/Hashtable/.ctor/hashtable_ctorint.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Hashtable_ctorInt/VB/hashtable_ctorint.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Hashtable_ctorInt/VB/hashtable_ctorint.vb" id="Snippet1"::: + ]]> @@ -944,41 +944,41 @@ Each element is a key/value pair stored in a A number in the range from 0.1 through 1.0 that is multiplied by the default value which provides the best performance. The result is the maximum ratio of elements to buckets. Initializes a new, empty instance of the class using the specified initial capacity and load factor, and the default hash code provider and comparer. - object. Capacity is automatically increased as required based on the load factor. - - The load factor is the maximum ratio of elements to buckets. A smaller load factor means faster lookup at the cost of increased memory consumption. A load factor of 1.0 is the best balance between speed and size. - - When the actual load factor reaches the specified load factor, the number of buckets is automatically increased to the smallest prime number that is larger than twice the current number of buckets. - - The hash code provider dispenses hash codes for keys in the . The default hash code provider is the key's implementation of . - - The comparer determines whether two keys are equal. Every key in a must be unique. The default comparer is the key's implementation of . - - This constructor is an `O(n)` operation, where `n` is the `capacity` parameter. - - - -## Examples - The following code example creates hash tables using different constructors and demonstrates the differences in the behavior of the hash tables, even if each one contains the same elements. - + object. Capacity is automatically increased as required based on the load factor. + + The load factor is the maximum ratio of elements to buckets. A smaller load factor means faster lookup at the cost of increased memory consumption. A load factor of 1.0 is the best balance between speed and size. + + When the actual load factor reaches the specified load factor, the number of buckets is automatically increased to the smallest prime number that is larger than twice the current number of buckets. + + The hash code provider dispenses hash codes for keys in the . The default hash code provider is the key's implementation of . + + The comparer determines whether two keys are equal. Every key in a must be unique. The default comparer is the key's implementation of . + + This constructor is an `O(n)` operation, where `n` is the `capacity` parameter. + + + +## Examples + The following code example creates hash tables using different constructors and demonstrates the differences in the behavior of the hash tables, even if each one contains the same elements. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Collections.Hashtable_ctorIntFloat/CPP/hashtable_ctorintfloat.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections/Hashtable/.ctor/hashtable_ctorintfloat.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Hashtable_ctorIntFloat/VB/hashtable_ctorintfloat.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Hashtable_ctorIntFloat/VB/hashtable_ctorintfloat.vb" id="Snippet1"::: + ]]> - is less than zero. - - -or- - - is less than 0.1. - - -or- - + is less than zero. + + -or- + + is less than 0.1. + + -or- + is greater than 1.0. is causing an overflow. @@ -1034,31 +1034,31 @@ Each element is a key/value pair stored in a - - + + A object containing the information required to serialize the object. A object containing the source and destination of the serialized stream associated with the . Initializes a new, empty instance of the class that is serializable using the specified and objects. - object. The default hash code provider is the key's implementation of . - - The comparer determines whether two keys are equal. Every key in a must be unique. The default comparer is the key's implementation of . - - This constructor is an `O(n)` operation, where `n` is . - - Because serializing and deserializing an enumerator for a can cause the elements to become reordered, it is not possible to continue enumeration without calling the method. - + object. The default hash code provider is the key's implementation of . + + The comparer determines whether two keys are equal. Every key in a must be unique. The default comparer is the key's implementation of . + + This constructor is an `O(n)` operation, where `n` is . + + Because serializing and deserializing an enumerator for a can cause the elements to become reordered, it is not possible to continue enumeration without calling the method. + ]]> @@ -1124,7 +1124,7 @@ Each element is a key/value pair stored in a - + [System.Runtime.CompilerServices.Nullable(1)] @@ -1132,51 +1132,51 @@ Each element is a key/value pair stored in a - - + + The object to copy to a new object. - The object that supplies the hash codes for all keys in the . - - -or- - + The object that supplies the hash codes for all keys in the . + + -or- + to use the default hash code provider, which is each key's implementation of . - The object to use to determine whether two keys are equal. - - -or- - + The object to use to determine whether two keys are equal. + + -or- + to use the default comparer, which is each key's implementation of . Initializes a new instance of the class by copying the elements from the specified dictionary to the new object. The new object has an initial capacity equal to the number of elements copied, and uses the default load factor, and the specified hash code provider and comparer. This API is obsolete. For an alternative, see . - object. The default hash code provider is the key's implementation of . - - The comparer determines whether two keys are equal. Every key in a must be unique. The default comparer is the key's implementation of . - - The custom hash code provider and the custom comparer enable scenarios such as doing lookups with case-insensitive strings. - - The elements of the new are sorted in the same order in which the enumerator iterates through the object. - - This constructor is an `O(n)` operation, where `n` is the number of elements in the `d` parameter. - - - -## Examples - The following code example creates hash tables using different constructors and demonstrates the differences in the behavior of the hash tables, even if each one contains the same elements. - + object. The default hash code provider is the key's implementation of . + + The comparer determines whether two keys are equal. Every key in a must be unique. The default comparer is the key's implementation of . + + The custom hash code provider and the custom comparer enable scenarios such as doing lookups with case-insensitive strings. + + The elements of the new are sorted in the same order in which the enumerator iterates through the object. + + This constructor is an `O(n)` operation, where `n` is the number of elements in the `d` parameter. + + + +## Examples + The following code example creates hash tables using different constructors and demonstrates the differences in the behavior of the hash tables, even if each one contains the same elements. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Collections.Hashtable_ctorDictionary/CPP/hashtable_ctordictionary.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections/Hashtable/.ctor/hashtable_ctordictionary.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Hashtable_ctorDictionary/VB/hashtable_ctordictionary.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Hashtable_ctorDictionary/VB/hashtable_ctordictionary.vb" id="Snippet1"::: + ]]> @@ -1242,52 +1242,52 @@ Each element is a key/value pair stored in a The object to copy to a new object. A number in the range from 0.1 through 1.0 that is multiplied by the default value which provides the best performance. The result is the maximum ratio of elements to buckets. - The object that defines the hash code provider and the comparer to use with the . - - -or- - + The object that defines the hash code provider and the comparer to use with the . + + -or- + to use the default hash code provider and the default comparer. The default hash code provider is each key's implementation of and the default comparer is each key's implementation of . Initializes a new instance of the class by copying the elements from the specified dictionary to the new object. The new object has an initial capacity equal to the number of elements copied, and uses the specified load factor and object. - object includes both the hash code provider and the comparer. If an is used in the constructor, the objects used as keys in the object are not required to override the and methods. - - The hash code provider dispenses hash codes for keys in the . The default hash code provider is the key's implementation of . - - The comparer determines whether two keys are equal. Every key in a must be unique. The default comparer is the key's implementation of . - - The enables scenarios such as doing lookups with case-insensitive strings. - - The elements of the new are sorted in the same order in which the enumerator iterates through the object. - - This constructor is an `O(n)` operation, where `n` is the number of elements in the `d` parameter. - - - -## Examples - The following code example creates hash tables using different constructors and demonstrates the differences in the behavior of the hash tables, even if each one contains the same elements. - + object includes both the hash code provider and the comparer. If an is used in the constructor, the objects used as keys in the object are not required to override the and methods. + + The hash code provider dispenses hash codes for keys in the . The default hash code provider is the key's implementation of . + + The comparer determines whether two keys are equal. Every key in a must be unique. The default comparer is the key's implementation of . + + The enables scenarios such as doing lookups with case-insensitive strings. + + The elements of the new are sorted in the same order in which the enumerator iterates through the object. + + This constructor is an `O(n)` operation, where `n` is the number of elements in the `d` parameter. + + + +## Examples + The following code example creates hash tables using different constructors and demonstrates the differences in the behavior of the hash tables, even if each one contains the same elements. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Collections.Hashtable_ctorDictionaryFloat/CPP/hashtable_ctordictionaryfloat.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections/Hashtable/.ctor/hashtable_ctordictionaryfloat.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Hashtable_ctorDictionaryFloat/VB/hashtable_ctordictionaryfloat.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Hashtable_ctorDictionaryFloat/VB/hashtable_ctordictionaryfloat.vb" id="Snippet1"::: + ]]> is . - is less than 0.1. - - -or- - + is less than 0.1. + + -or- + is greater than 1.0. @@ -1345,50 +1345,50 @@ Each element is a key/value pair stored in a - - - + + + The approximate number of elements that the object can initially contain. - The object that supplies the hash codes for all keys in the . - - -or- - + The object that supplies the hash codes for all keys in the . + + -or- + to use the default hash code provider, which is each key's implementation of . - The object to use to determine whether two keys are equal. - - -or- - + The object to use to determine whether two keys are equal. + + -or- + to use the default comparer, which is each key's implementation of . Initializes a new, empty instance of the class using the specified initial capacity, hash code provider, comparer, and the default load factor. - object. Capacity is automatically increased as required based on the load factor. - - The load factor is the maximum ratio of elements to buckets. A smaller load factor means faster lookup at the cost of increased memory consumption. - - When the actual load factor reaches the specified load factor, the number of buckets is automatically increased to the smallest prime number that is larger than twice the current number of buckets. - - The hash code provider dispenses hash codes for keys in the . The default hash code provider is the key's implementation of . - - The comparer determines whether two keys are equal. Every key in a must be unique. The default comparer is the key's implementation of . - - The custom hash code provider and the custom comparer enable scenarios such as doing lookups with case-insensitive strings. - - This constructor is an `O(n)` operation, where `n` is the `capacity` parameter. - - - -## Examples - The following code example creates hash tables using different constructors and demonstrates the differences in the behavior of the hash tables, even if each one contains the same elements. - + object. Capacity is automatically increased as required based on the load factor. + + The load factor is the maximum ratio of elements to buckets. A smaller load factor means faster lookup at the cost of increased memory consumption. + + When the actual load factor reaches the specified load factor, the number of buckets is automatically increased to the smallest prime number that is larger than twice the current number of buckets. + + The hash code provider dispenses hash codes for keys in the . The default hash code provider is the key's implementation of . + + The comparer determines whether two keys are equal. Every key in a must be unique. The default comparer is the key's implementation of . + + The custom hash code provider and the custom comparer enable scenarios such as doing lookups with case-insensitive strings. + + This constructor is an `O(n)` operation, where `n` is the `capacity` parameter. + + + +## Examples + The following code example creates hash tables using different constructors and demonstrates the differences in the behavior of the hash tables, even if each one contains the same elements. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Collections.Hashtable_ctorInt/CPP/hashtable_ctorint.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections/Hashtable/.ctor/hashtable_ctorint.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Hashtable_ctorInt/VB/hashtable_ctorint.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Hashtable_ctorInt/VB/hashtable_ctorint.vb" id="Snippet1"::: + ]]> @@ -1452,52 +1452,52 @@ Each element is a key/value pair stored in a The approximate number of elements that the object can initially contain. A number in the range from 0.1 through 1.0 that is multiplied by the default value which provides the best performance. The result is the maximum ratio of elements to buckets. - The object that defines the hash code provider and the comparer to use with the . - - -or- - + The object that defines the hash code provider and the comparer to use with the . + + -or- + to use the default hash code provider and the default comparer. The default hash code provider is each key's implementation of and the default comparer is each key's implementation of . Initializes a new, empty instance of the class using the specified initial capacity, load factor, and object. - object. Capacity is automatically increased as required based on the load factor. - - The load factor is the maximum ratio of elements to buckets. A smaller load factor means faster lookup at the cost of increased memory consumption. A load factor of 1.0 is the best balance between speed and size. - - When the actual load factor reaches the specified load factor, the number of buckets is automatically increased to the smallest prime number that is larger than twice the current number of buckets. - - The object includes both the hash code provider and the comparer. If an is used in the constructor, the objects used as keys in the are not required to override the and methods. - - The hash code provider dispenses hash codes for keys in the . The default hash code provider is the key's implementation of . - - The comparer determines whether two keys are equal. Every key in a must be unique. The default comparer is the key's implementation of . - - The enables scenarios such as doing lookups with case-insensitive strings. - - This constructor is an `O(n)` operation, where `n` is the `capacity` parameter. - - - -## Examples - The following code example creates hash tables using different constructors and demonstrates the differences in the behavior of the hash tables, even if each one contains the same elements. - + object. Capacity is automatically increased as required based on the load factor. + + The load factor is the maximum ratio of elements to buckets. A smaller load factor means faster lookup at the cost of increased memory consumption. A load factor of 1.0 is the best balance between speed and size. + + When the actual load factor reaches the specified load factor, the number of buckets is automatically increased to the smallest prime number that is larger than twice the current number of buckets. + + The object includes both the hash code provider and the comparer. If an is used in the constructor, the objects used as keys in the are not required to override the and methods. + + The hash code provider dispenses hash codes for keys in the . The default hash code provider is the key's implementation of . + + The comparer determines whether two keys are equal. Every key in a must be unique. The default comparer is the key's implementation of . + + The enables scenarios such as doing lookups with case-insensitive strings. + + This constructor is an `O(n)` operation, where `n` is the `capacity` parameter. + + + +## Examples + The following code example creates hash tables using different constructors and demonstrates the differences in the behavior of the hash tables, even if each one contains the same elements. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Collections.Hashtable_ctorIntFloat/CPP/hashtable_ctorintfloat.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections/Hashtable/.ctor/hashtable_ctorintfloat.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Hashtable_ctorIntFloat/VB/hashtable_ctorintfloat.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Hashtable_ctorIntFloat/VB/hashtable_ctorintfloat.vb" id="Snippet1"::: + ]]> - is less than zero. - - -or- - - is less than 0.1. - - -or- - + is less than zero. + + -or- + + is less than 0.1. + + -or- + is greater than 1.0. @@ -1555,7 +1555,7 @@ Each element is a key/value pair stored in a - + [System.Runtime.CompilerServices.Nullable(1)] @@ -1563,62 +1563,62 @@ Each element is a key/value pair stored in a - - - + + + The object to copy to a new object. A number in the range from 0.1 through 1.0 that is multiplied by the default value which provides the best performance. The result is the maximum ratio of elements to buckets. - The object that supplies the hash codes for all keys in the . - - -or- - + The object that supplies the hash codes for all keys in the . + + -or- + to use the default hash code provider, which is each key's implementation of . - The object to use to determine whether two keys are equal. - - -or- - + The object to use to determine whether two keys are equal. + + -or- + to use the default comparer, which is each key's implementation of . Initializes a new instance of the class by copying the elements from the specified dictionary to the new object. The new object has an initial capacity equal to the number of elements copied, and uses the specified load factor, hash code provider, and comparer. - object. The default hash code provider is the key's implementation of . - - The comparer determines whether two keys are equal. Every key in a must be unique. The default comparer is the key's implementation of . - - The custom hash code provider and the custom comparer enable scenarios such as doing lookups with case-insensitive strings. - - The elements of the new are sorted in the same order in which the enumerator iterates through the object. - - This constructor is an `O(n)` operation, where `n` is the number of elements in the `d` parameter. - - - -## Examples - The following code example creates hash tables using different constructors and demonstrates the differences in the behavior of the hash tables, even if each one contains the same elements. - + object. The default hash code provider is the key's implementation of . + + The comparer determines whether two keys are equal. Every key in a must be unique. The default comparer is the key's implementation of . + + The custom hash code provider and the custom comparer enable scenarios such as doing lookups with case-insensitive strings. + + The elements of the new are sorted in the same order in which the enumerator iterates through the object. + + This constructor is an `O(n)` operation, where `n` is the number of elements in the `d` parameter. + + + +## Examples + The following code example creates hash tables using different constructors and demonstrates the differences in the behavior of the hash tables, even if each one contains the same elements. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Collections.Hashtable_ctorDictionaryFloat/CPP/hashtable_ctordictionaryfloat.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections/Hashtable/.ctor/hashtable_ctordictionaryfloat.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Hashtable_ctorDictionaryFloat/VB/hashtable_ctordictionaryfloat.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Hashtable_ctorDictionaryFloat/VB/hashtable_ctordictionaryfloat.vb" id="Snippet1"::: + ]]> is . - is less than 0.1. - - -or- - + is less than 0.1. + + -or- + is greater than 1.0. @@ -1675,63 +1675,63 @@ Each element is a key/value pair stored in a - - - - + + + + The approximate number of elements that the object can initially contain. A number in the range from 0.1 through 1.0 that is multiplied by the default value which provides the best performance. The result is the maximum ratio of elements to buckets. - The object that supplies the hash codes for all keys in the . - - -or- - + The object that supplies the hash codes for all keys in the . + + -or- + to use the default hash code provider, which is each key's implementation of . - The object to use to determine whether two keys are equal. - - -or- - + The object to use to determine whether two keys are equal. + + -or- + to use the default comparer, which is each key's implementation of . Initializes a new, empty instance of the class using the specified initial capacity, load factor, hash code provider, and comparer. - object. Capacity is automatically increased as required based on the load factor. - - The load factor is the maximum ratio of elements to buckets. A smaller load factor means faster lookup at the cost of increased memory consumption. A load factor of 1.0 is the best balance between speed and size. - - When the actual load factor reaches the specified load factor, the number of buckets is automatically increased to the smallest prime number that is larger than twice the current number of buckets. - - The hash code provider dispenses hash codes for keys in the . The default hash code provider is the key's implementation of . - - The comparer determines whether two keys are equal. Every key in a must be unique. The default comparer is the key's implementation of . - - The custom hash code provider and the custom comparer enable scenarios such as doing lookups with case-insensitive strings. - - This constructor is an `O(n)` operation, where `n` is the `capacity` parameter. - - - -## Examples - The following code example creates hash tables using different constructors and demonstrates the differences in the behavior of the hash tables, even if each one contains the same elements. - + object. Capacity is automatically increased as required based on the load factor. + + The load factor is the maximum ratio of elements to buckets. A smaller load factor means faster lookup at the cost of increased memory consumption. A load factor of 1.0 is the best balance between speed and size. + + When the actual load factor reaches the specified load factor, the number of buckets is automatically increased to the smallest prime number that is larger than twice the current number of buckets. + + The hash code provider dispenses hash codes for keys in the . The default hash code provider is the key's implementation of . + + The comparer determines whether two keys are equal. Every key in a must be unique. The default comparer is the key's implementation of . + + The custom hash code provider and the custom comparer enable scenarios such as doing lookups with case-insensitive strings. + + This constructor is an `O(n)` operation, where `n` is the `capacity` parameter. + + + +## Examples + The following code example creates hash tables using different constructors and demonstrates the differences in the behavior of the hash tables, even if each one contains the same elements. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Collections.Hashtable_ctorIntFloat/CPP/hashtable_ctorintfloat.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections/Hashtable/.ctor/hashtable_ctorintfloat.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Hashtable_ctorIntFloat/VB/hashtable_ctorintfloat.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.Hashtable_ctorIntFloat/VB/hashtable_ctorintfloat.vb" id="Snippet1"::: + ]]> - is less than zero. - - -or- - - is less than 0.1. - - -or- - + is less than zero. + + -or- + + is less than 0.1. + + -or- + is greater than 1.0. @@ -1807,35 +1807,35 @@ Each element is a key/value pair stored in a The value of the element to add. The value can be . Adds an element with the specified key and value into the . - property to add new elements by setting the value of a key that does not exist in the ; for example, `myCollection["myNonexistentKey"] = myValue`. However, if the specified key already exists in the , setting the property overwrites the old value. In contrast, the method does not modify existing elements. - - If is less than the capacity of the , this method is an `O(1)` operation. If the capacity needs to be increased to accommodate the new element, this method becomes an `O(n)` operation, where `n` is . - - - -## Examples - The following example shows how to add elements to the . - + property to add new elements by setting the value of a key that does not exist in the ; for example, `myCollection["myNonexistentKey"] = myValue`. However, if the specified key already exists in the , setting the property overwrites the old value. In contrast, the method does not modify existing elements. + + If is less than the capacity of the , this method is an `O(1)` operation. If the capacity needs to be increased to accommodate the new element, this method becomes an `O(n)` operation, where `n` is . + + + +## Examples + The following example shows how to add elements to the . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Hashtable.Add Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections/Hashtable/Add/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Hashtable.Add Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Hashtable.Add Example/VB/source.vb" id="Snippet1"::: + ]]> is . An element with the same key already exists in the . - The is read-only. - - -or- - + The is read-only. + + -or- + The has a fixed size. @@ -1897,22 +1897,22 @@ Each element is a key/value pair stored in a Removes all elements from the . - is set to zero, and references to other objects from elements of the collection are also released. The capacity remains unchanged. - - This method is an `O(n)` operation, where `n` is . - - - -## Examples - The following example shows how to clear the values of the . - + is set to zero, and references to other objects from elements of the collection are also released. The capacity remains unchanged. + + This method is an `O(n)` operation, where `n` is . + + + +## Examples + The following example shows how to clear the values of the . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Hashtable.Clear Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections/Hashtable/Clear/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Hashtable.Clear Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Hashtable.Clear Example/VB/source.vb" id="Snippet1"::: + ]]> The is read-only. @@ -1969,17 +1969,17 @@ Each element is a key/value pair stored in a Creates a shallow copy of the . A shallow copy of the . - clone has the same count, the same capacity, the same implementation, and the same implementation as the original . - - This method is an `O(n)` operation, where `n` is . - + clone has the same count, the same capacity, the same implementation, and the same implementation as the original . + + This method is an `O(n)` operation, where `n` is . + ]]> @@ -2052,11 +2052,11 @@ Each element is a key/value pair stored in a Gets or sets the to use for the . The to use for the . - The property is set to a value, but the hash table was created using an . @@ -2123,24 +2123,24 @@ Each element is a key/value pair stored in a if the contains an element with the specified key; otherwise, . - implements . It behaves exactly as . - - This method is an `O(1)` operation. - - Starting with the .NET Framework 2.0, this method uses the collection's objects' and methods on `item` to determine whether item exists. In the earlier versions of the .NET Framework, this determination was made by using the and methods of the `item` parameter on the objects in the collection. - - - -## Examples - The following example shows how to determine whether the contains a specific element. - + implements . It behaves exactly as . + + This method is an `O(1)` operation. + + Starting with the .NET Framework 2.0, this method uses the collection's objects' and methods on `item` to determine whether item exists. In the earlier versions of the .NET Framework, this determination was made by using the and methods of the `item` parameter on the objects in the collection. + + + +## Examples + The following example shows how to determine whether the contains a specific element. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Hashtable.Contains Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections/Hashtable/Contains/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Hashtable.Contains Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Hashtable.Contains Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -2200,24 +2200,24 @@ Each element is a key/value pair stored in a if the contains an element with the specified key; otherwise, . - . - - This method is an `O(1)` operation. - - Starting with the .NET Framework 2.0, this method uses the collection's objects' and methods on `item` to determine whether item exists. In the earlier versions of the .NET Framework, this determination was made by using the and methods of the `item` parameter on the objects in the collection. - - - -## Examples - The following example shows how to determine whether the contains a specific element. - + . + + This method is an `O(1)` operation. + + Starting with the .NET Framework 2.0, this method uses the collection's objects' and methods on `item` to determine whether item exists. In the earlier versions of the .NET Framework, this determination was made by using the and methods of the `item` parameter on the objects in the collection. + + + +## Examples + The following example shows how to determine whether the contains a specific element. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Hashtable.Contains Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections/Hashtable/Contains/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Hashtable.Contains Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Hashtable.Contains Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -2284,24 +2284,24 @@ Each element is a key/value pair stored in a if the contains an element with the specified ; otherwise, . - are compared to the specified value using the method. - - This method performs a linear search; therefore, this method is an `O(n)` operation, where `n` is . - - Starting with the .NET Framework 2.0, this method uses the collection's objects' and methods on `item` to determine whether item exists. In the earlier versions of the .NET Framework, this determination was made by using the and methods of the `item` parameter on the objects in the collection. - - - -## Examples - The following example shows how to determine whether the contains a specific element. - + are compared to the specified value using the method. + + This method performs a linear search; therefore, this method is an `O(n)` operation, where `n` is . + + Starting with the .NET Framework 2.0, this method uses the collection's objects' and methods on `item` to determine whether item exists. In the earlier versions of the .NET Framework, this determination was made by using the and methods of the `item` parameter on the objects in the collection. + + + +## Examples + The following example shows how to determine whether the contains a specific element. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Hashtable.Contains Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections/Hashtable/Contains/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Hashtable.Contains Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Hashtable.Contains Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -2362,26 +2362,26 @@ Each element is a key/value pair stored in a The zero-based index in at which copying begins. Copies the elements to a one-dimensional instance at the specified index. - in the same order in which the enumerator iterates through the . - - To copy only the keys in the , use `Hashtable.Keys.CopyTo`. - - To copy only the values in the , use `Hashtable.Values.CopyTo`. - - This method is an `O(n)` operation, where `n` is . - - - -## Examples - The following example shows how to copy the list of keys or the list of values in a into a one-dimensional . - + in the same order in which the enumerator iterates through the . + + To copy only the keys in the , use `Hashtable.Keys.CopyTo`. + + To copy only the values in the , use `Hashtable.Values.CopyTo`. + + This method is an `O(n)` operation, where `n` is . + + + +## Examples + The following example shows how to copy the list of keys or the list of values in a into a one-dimensional . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Hashtable.CopyTo Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections/Hashtable/CopyTo/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Hashtable.CopyTo Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Hashtable.CopyTo Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -2389,10 +2389,10 @@ Each element is a key/value pair stored in a is less than zero. - is multidimensional. - - -or- - + is multidimensional. + + -or- + The number of elements in the source is greater than the available space from to the end of the destination . The type of the source cannot be cast automatically to the type of the destination . @@ -2449,11 +2449,11 @@ Each element is a key/value pair stored in a Gets the number of key/value pairs contained in the . The number of key/value pairs contained in the . - @@ -2514,13 +2514,13 @@ Each element is a key/value pair stored in a Gets the to use for the . The to use for the . - includes both the comparer and the hash code provider. If an is used in the constructor, the objects used as keys in the are not required to override the and methods. - - Retrieving the value of this property is an `O(1)` operation. - + includes both the comparer and the hash code provider. If an is used in the constructor, the objects used as keys in the are not required to override the and methods. + + Retrieving the value of this property is an `O(1)` operation. + ]]> The property is set to a value, but the hash table was created using an and an . @@ -2584,37 +2584,37 @@ Each element is a key/value pair stored in a Returns an that iterates through the . An for the . - also brings the enumerator back to this position. At this position, 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. - - 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. - - The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - - This method is an `O(1)` operation. - - Because serializing and deserializing an enumerator for a can cause the elements to become reordered, it is not possible to continue enumeration without calling the method. - - - -## Examples - The following example compares the use of and `foreach` to enumerate the contents of a . - + also brings the enumerator back to this position. At this position, 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. + + 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. + + The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. + + This method is an `O(1)` operation. + + Because serializing and deserializing an enumerator for a can cause the elements to become reordered, it is not possible to continue enumeration without calling the method. + + + +## Examples + The following example compares the use of and `foreach` to enumerate the contents of a . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Hashtable Example/CPP/source2.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Collections/Hashtable/GetEnumerator/source2.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Hashtable Example/VB/source2.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Hashtable Example/VB/source2.vb" id="Snippet2"::: + ]]> @@ -2677,13 +2677,13 @@ Each element is a key/value pair stored in a Returns the hash code for the specified key. The hash code for . - implementation, this method uses that hash code provider; otherwise, it uses the implementation of `key`. - - This method is an `O(1)` operation. - + implementation, this method uses that hash code provider; otherwise, it uses the implementation of `key`. + + This method is an `O(1)` operation. + ]]> @@ -2751,19 +2751,19 @@ Each element is a key/value pair stored in a System.Void - - + + A object containing the information required to serialize the . A object containing the source and destination of the serialized stream associated with the . Implements the interface and returns the data needed to serialize the . - . - + . + ]]> @@ -2842,11 +2842,11 @@ Each element is a key/value pair stored in a Gets or sets the object that can dispense hash codes. The object that can dispense hash codes. - The property is set to a value, but the hash table was created using an . @@ -2903,15 +2903,15 @@ Each element is a key/value pair stored in a if the has a fixed size; otherwise, . The default is . - @@ -2966,15 +2966,15 @@ Each element is a key/value pair stored in a if the is read-only; otherwise, . The default is . - @@ -3029,28 +3029,28 @@ Each element is a key/value pair stored in a if access to the is synchronized (thread safe); otherwise, . The default is . - can support one writer and multiple readers concurrently. To support multiple writers, all operations must be done through the wrapper returned by the method. - - 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: - + can support one writer and multiple readers concurrently. To support multiple writers, all operations must be done through the wrapper returned by the method. + + 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: + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Hashtable.IsSynchronized Example/CPP/remarks.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Collections/Hashtable/IsSynchronized/remarks.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Hashtable.IsSynchronized Example/VB/remarks.vb" id="Snippet2"::: - - - -## Examples - The following example shows how to synchronize a , determine if a is synchronized, and use a synchronized . - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Hashtable.IsSynchronized Example/VB/remarks.vb" id="Snippet2"::: + + + +## Examples + The following example shows how to synchronize a , determine if a is synchronized, and use a synchronized . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Hashtable.IsSynchronized Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections/Hashtable/IsSynchronized/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Hashtable.IsSynchronized Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Hashtable.IsSynchronized Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -3121,27 +3121,27 @@ Each element is a key/value pair stored in a Gets or sets the value associated with the specified key. The value associated with the specified key. If the specified key is not found, attempting to get it returns , and attempting to set it creates a new element using the specified key. - property to add new elements by setting the value of a key that does not exist in the ; for example, `myCollection["myNonexistentKey"] = myValue`. However, if the specified key already exists in the , setting the property overwrites the old value. In contrast, the method does not modify existing elements. - - A key cannot be `null`, but a value can be. To distinguish between `null` that is returned because the specified key is not found and `null` that is returned because the value of the specified key is `null`, use the method or the method to determine if the key exists in the list. - - Retrieving the value of this property is an `O(1)` operation; setting the property is also an `O(1)` operation. - - The C# language uses the [`this`](/dotnet/csharp/language-reference/keywords/this) keyword to define the indexers instead of implementing the property. Visual Basic implements as a default property, which provides the same indexing functionality. - + property to add new elements by setting the value of a key that does not exist in the ; for example, `myCollection["myNonexistentKey"] = myValue`. However, if the specified key already exists in the , setting the property overwrites the old value. In contrast, the method does not modify existing elements. + + A key cannot be `null`, but a value can be. To distinguish between `null` that is returned because the specified key is not found and `null` that is returned because the value of the specified key is `null`, use the method or the method to determine if the key exists in the list. + + Retrieving the value of this property is an `O(1)` operation; setting the property is also an `O(1)` operation. + + The C# language uses the [`this`](/dotnet/csharp/language-reference/keywords/this) keyword to define the indexers instead of implementing the property. Visual Basic implements as a default property, which provides the same indexing functionality. + ]]> is . - The property is set and the is read-only. - - -or- - + The property is set and the is read-only. + + -or- + The property is set, does not exist in the collection, and the has a fixed size. @@ -3207,20 +3207,20 @@ Each element is a key/value pair stored in a if and are equal; otherwise, . - implementation, this method uses that comparer; that is, (`item`, `key`). Otherwise, it uses `item.Equals(key)`. - - This method is an `O(1)` operation. - + implementation, this method uses that comparer; that is, (`item`, `key`). Otherwise, it uses `item.Equals(key)`. + + This method is an `O(1)` operation. + ]]> - is . - - -or- - + is . + + -or- + is . @@ -3282,15 +3282,15 @@ Each element is a key/value pair stored in a Gets an containing the keys in the . An containing the keys in the . - is unspecified, but it is the same order as the associated values in the returned by the method. - - The returned is not a static copy; instead, the refers back to the keys in the original . Therefore, changes to the continue to be reflected in the . - - Retrieving the value of this property is an `O(1)` operation. - + is unspecified, but it is the same order as the associated values in the returned by the method. + + The returned is not a static copy; instead, the refers back to the keys in the original . Therefore, changes to the continue to be reflected in the . + + Retrieving the value of this property is an `O(1)` operation. + ]]> @@ -3348,19 +3348,19 @@ Each element is a key/value pair stored in a System.Void - + The source of the deserialization event. Implements the interface and raises the deserialization event when the deserialization is complete. - . - - Because serializing and deserializing an enumerator for a can cause the elements to become reordered, it is not possible to continue enumeration without calling the method. - + . + + Because serializing and deserializing an enumerator for a can cause the elements to become reordered, it is not possible to continue enumeration without calling the method. + ]]> The object associated with the current is invalid. @@ -3426,30 +3426,30 @@ Each element is a key/value pair stored in a The key of the element to remove. Removes the element with the specified key from the . - does not contain an element with the specified key, the remains unchanged. No exception is thrown. - - This method is an `O(1)` operation. - - - -## Examples - The following example shows how to remove elements from the . - + does not contain an element with the specified key, the remains unchanged. No exception is thrown. + + This method is an `O(1)` operation. + + + +## Examples + The following example shows how to remove elements from the . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Hashtable.Remove Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections/Hashtable/Remove/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Hashtable.Remove Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Hashtable.Remove Example/VB/source.vb" id="Snippet1"::: + ]]> is . - The is read-only. - - -or- - + The is read-only. + + -or- + The has a fixed size. @@ -3505,30 +3505,30 @@ Each element is a key/value pair stored in a Returns a synchronized (thread-safe) wrapper for the . A synchronized (thread-safe) wrapper for the . - method is thread safe for multiple readers and writers. Furthermore, the synchronized wrapper ensures that there is only one writer writing at a time. - - 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: - + method is thread safe for multiple readers and writers. Furthermore, the synchronized wrapper ensures that there is only one writer writing at a time. + + 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: + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Hashtable.IsSynchronized Example/CPP/remarks.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Collections/Hashtable/IsSynchronized/remarks.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Hashtable.IsSynchronized Example/VB/remarks.vb" id="Snippet2"::: - - This method is an `O(1)` operation. - - - -## Examples - The following example shows how to synchronize a , determine if a is synchronized, and use a synchronized . - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Hashtable.IsSynchronized Example/VB/remarks.vb" id="Snippet2"::: + + This method is an `O(1)` operation. + + + +## Examples + The following example shows how to synchronize a , determine if a is synchronized, and use a synchronized . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Hashtable.IsSynchronized Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections/Hashtable/IsSynchronized/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Hashtable.IsSynchronized Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Hashtable.IsSynchronized Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -3586,19 +3586,19 @@ Each element is a key/value pair stored in a Gets an object that can be used to synchronize access to the . An object that can be used to synchronize access to the . - , use the method. However, derived classes can provide their own synchronized version 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. - - 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: - + , use the method. However, derived classes can provide their own synchronized version 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. + + 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: + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Hashtable.IsSynchronized Example/CPP/remarks.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Collections/Hashtable/IsSynchronized/remarks.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Hashtable.IsSynchronized Example/VB/remarks.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Hashtable.IsSynchronized Example/VB/remarks.vb" id="Snippet2"::: + ]]> @@ -3661,26 +3661,26 @@ Each element is a key/value pair stored in a Returns an enumerator that iterates through a collection. An that can be used to iterate through the collection. - also brings the enumerator back to this position. At this position, calling throws an exception. 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. - - 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`, calling throws an exception. 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 can be invalidated and the next call to or throws an . If the collection is modified between and , returns the element that it is set to, even if the enumerator is already invalidated. - - The enumerator does not have exclusive access to the collection; therefore, 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. - - This method is an `O(1)` operation. - + also brings the enumerator back to this position. At this position, calling throws an exception. 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. + + 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`, calling throws an exception. 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 can be invalidated and the next call to or throws an . If the collection is modified between and , returns the element that it is set to, even if the enumerator is already invalidated. + + The enumerator does not have exclusive access to the collection; therefore, 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. + + This method is an `O(1)` operation. + ]]> @@ -3741,15 +3741,15 @@ Each element is a key/value pair stored in a Gets an containing the values in the . An containing 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 continue to be reflected in the . - - Retrieving the value of this property is an `O(1)` operation. - + 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 continue to be reflected in the . + + Retrieving the value of this property is an `O(1)` operation. + ]]> diff --git a/xml/System.ComponentModel.Composition.Primitives/ComposablePartException.xml b/xml/System.ComponentModel.Composition.Primitives/ComposablePartException.xml index a1cb8719284..02ba6bcf9eb 100644 --- a/xml/System.ComponentModel.Composition.Primitives/ComposablePartException.xml +++ b/xml/System.ComponentModel.Composition.Primitives/ComposablePartException.xml @@ -142,8 +142,8 @@ - - + + An object that holds the serialized object data for the . @@ -322,8 +322,8 @@ System.Void - - + + After calling the method, contains serialized object data about the . diff --git a/xml/System.ComponentModel.DataAnnotations/ValidationException.xml b/xml/System.ComponentModel.DataAnnotations/ValidationException.xml index 471f0b4f91b..5dd9bf9b057 100644 --- a/xml/System.ComponentModel.DataAnnotations/ValidationException.xml +++ b/xml/System.ComponentModel.DataAnnotations/ValidationException.xml @@ -49,13 +49,13 @@ Represents the exception that occurs during validation of a data field when the class is used. - value, a validation exception occurs. - - This class uses the class to customize validations. A is thrown if a validation error occurs. The exception is thrown when the method is called. All the exceptions that are thrown during validation are contained in the collection. You can retrieve each validation exception by iterating through the collection. - + value, a validation exception occurs. + + This class uses the class to customize validations. A is thrown if a validation error occurs. The exception is thrown when the method is called. All the exceptions that are thrown during validation are contained in the collection. You can retrieve each validation exception by iterating through the collection. + ]]> @@ -106,11 +106,11 @@ Initializes a new instance of the class using an error message generated by the system. - class. - + class. + ]]> @@ -156,11 +156,11 @@ A specified message that states the error. Initializes a new instance of the class using a specified error message. - @@ -209,19 +209,19 @@ - - + + The object that holds the serialized data. Context information about the source or destination of the serialized object. Initializes a new instance of the class using serialized data. - @@ -269,11 +269,11 @@ The collection of validation exceptions. Initializes a new instance of the class using a specified error message and a collection of inner exception instances. - property, not `innerException`. - + property, not `innerException`. + ]]> @@ -364,11 +364,11 @@ The value of the object that caused the attribute to trigger validation error. Initializes a new instance of the class using a specified error message, a validation attribute, and the value of the current exception. - @@ -407,12 +407,12 @@ Context information about the source or destination of the exception. Gets information about the exception and adds it to the object. - object that is targeted for serialization. + object that is targeted for serialization. During deserialization, the exception is reconstituted from the class that is transmitted over the stream in the . - + ]]> @@ -458,15 +458,15 @@ During deserialization, the exception is reconstituted from the Gets the instance of the class that triggered this exception. An instance of the validation attribute type that triggered this exception. - class triggers a . - - This class can be overridden to create custom validation attributes. - - - + class triggers a . + + This class can be overridden to create custom validation attributes. + + + ]]> diff --git a/xml/System.ComponentModel/BaseNumberConverter.xml b/xml/System.ComponentModel/BaseNumberConverter.xml index 46b9f4d80da..943a651f211 100644 --- a/xml/System.ComponentModel/BaseNumberConverter.xml +++ b/xml/System.ComponentModel/BaseNumberConverter.xml @@ -56,11 +56,11 @@ - - - - - + + + + + Constructor System.ComponentModel.TypeConverter diff --git a/xml/System.ComponentModel/DefaultValueAttribute.xml b/xml/System.ComponentModel/DefaultValueAttribute.xml index 8ec881f3cd9..97ba1f7aa23 100644 --- a/xml/System.ComponentModel/DefaultValueAttribute.xml +++ b/xml/System.ComponentModel/DefaultValueAttribute.xml @@ -65,33 +65,33 @@ Specifies the default value for a property. - with any value. A member's default value is typically its initial value. A visual designer can use the default value to reset the member's value. Code generators can use the default values also to determine whether code should be generated for the member. - + with any value. A member's default value is typically its initial value. A visual designer can use the default value to reset the member's value. Code generators can use the default values also to determine whether code should be generated for the member. + > [!NOTE] -> A will not cause a member to be automatically initialized with the attribute's value. You must set the initial value in your code. - - For more information, see [Attributes](/dotnet/standard/attributes/). - - - -## Examples - The following example sets the default value of `MyProperty` to `false`. - +> A will not cause a member to be automatically initialized with the attribute's value. You must set the initial value in your code. + + For more information, see [Attributes](/dotnet/standard/attributes/). + + + +## Examples + The following example sets the default value of `MyProperty` to `false`. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/Classic DefaultValueAttribute Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/DefaultValueAttribute/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Winforms/Classic DefaultValueAttribute Example/VB/source.vb" id="Snippet1"::: - - The next example checks the default value of `MyProperty`. First the code gets a with all the properties for the object. Next it indexes into the to get `MyProperty`. Then it returns the attributes for this property and saves them in the attributes variable. - - The example then prints the default value by retrieving the from the , and writing its name to the console screen. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Winforms/Classic DefaultValueAttribute Example/VB/source.vb" id="Snippet1"::: + + The next example checks the default value of `MyProperty`. First the code gets a with all the properties for the object. Next it indexes into the to get `MyProperty`. Then it returns the attributes for this property and saves them in the attributes variable. + + The example then prints the default value by retrieving the from the , and writing its name to the console screen. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/Classic DefaultValueAttribute Example/CPP/source.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/DefaultValueAttribute/Overview/source.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Winforms/Classic DefaultValueAttribute Example/VB/source.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Winforms/Classic DefaultValueAttribute Example/VB/source.vb" id="Snippet2"::: + ]]> @@ -938,7 +938,7 @@ System.Void - + The default value. diff --git a/xml/System.ComponentModel/TypeConverter+StandardValuesCollection.xml b/xml/System.ComponentModel/TypeConverter+StandardValuesCollection.xml index 4e2b167b2c0..35d4273f300 100644 --- a/xml/System.ComponentModel/TypeConverter+StandardValuesCollection.xml +++ b/xml/System.ComponentModel/TypeConverter+StandardValuesCollection.xml @@ -56,11 +56,11 @@ Represents a collection of values. - . - + . + ]]> @@ -174,11 +174,11 @@ The index to start from. Copies the contents of this collection to an array. - to access that . For example, to get the third , you need to specify `myColl[2]`. - + to access that . For example, to get the third , you need to specify `myColl[2]`. + ]]> @@ -228,11 +228,11 @@ Gets the number of objects in the collection. The number of objects in the collection. - property can be used to set the limits of a loop that iterates through a collection of objects. Since collection is zero-based, be sure to use `Count - 1` as the upper bound of the loop. - + property can be used to set the limits of a loop that iterates through a collection of objects. Since collection is zero-based, be sure to use `Count - 1` as the upper bound of the loop. + ]]> @@ -350,11 +350,11 @@ Gets the object at the specified index number. The with the specified index. - to access that . For example, to get the third , you need to specify `myColl[2]`. - + to access that . For example, to get the third , you need to specify `myColl[2]`. + ]]> @@ -393,8 +393,8 @@ System.Void - - + + The array to copy to. @@ -483,11 +483,11 @@ in all cases. - is not synchronized. Since it is read-only, there is no need to synchronize it. - + is not synchronized. Since it is read-only, there is no need to synchronize it. + ]]> @@ -541,11 +541,11 @@ in all cases. - is not synchronized. - + is not synchronized. + ]]> diff --git a/xml/System.ComponentModel/Win32Exception.xml b/xml/System.ComponentModel/Win32Exception.xml index 400036628c9..727d4bb1d58 100644 --- a/xml/System.ComponentModel/Win32Exception.xml +++ b/xml/System.ComponentModel/Win32Exception.xml @@ -75,20 +75,20 @@ Throws an exception for a Win32 error code. - to access the numeric representation of the error code associated with this exception. For more information about the error codes, see [Win32 Error Codes](https://docs.microsoft.com/openspecs/windows_protocols/ms-erref/18d8fbe8-a967-4f1c-ae50-99ca8e491d2d). - - - -## Examples - The following code example shows how to catch a Win32 exception and interpret its content. The example attempts to start a nonexistent executable, which results in a Win32 exception. Upon catching the exception, the example fetches the respective error message, code, and origin of the exception. - + to access the numeric representation of the error code associated with this exception. For more information about the error codes, see [Win32 Error Codes](https://docs.microsoft.com/openspecs/windows_protocols/ms-erref/18d8fbe8-a967-4f1c-ae50-99ca8e491d2d). + + + +## Examples + The following code example shows how to catch a Win32 exception and interpret its content. The example attempts to start a nonexistent executable, which results in a Win32 exception. Upon catching the exception, the example fetches the respective error message, code, and origin of the exception. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/Win32Exception/CPP/win32exception.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/Win32Exception/Overview/win32exception.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Winforms/Win32Exception/VB/win32exception.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Winforms/Win32Exception/VB/win32exception.vb" id="Snippet1"::: + ]]> @@ -139,13 +139,13 @@ Initializes a new instance of the class with the last Win32 error that occurred. - method of to get its error code. - + method of to get its error code. + ]]> @@ -190,11 +190,11 @@ The Win32 error code associated with this exception. Initializes a new instance of the class with the specified error. - @@ -300,11 +300,11 @@ A detailed description of the error. Initializes a new instance of the class with the specified error and the specified detailed description. - @@ -351,8 +351,8 @@ - - + + The associated with this exception. @@ -459,8 +459,8 @@ System.Void - - + + A . diff --git a/xml/System.Data.Common/DbCommand.xml b/xml/System.Data.Common/DbCommand.xml index e1fb8197540..07044fd3bec 100644 --- a/xml/System.Data.Common/DbCommand.xml +++ b/xml/System.Data.Common/DbCommand.xml @@ -168,11 +168,11 @@ Attempts to cancel the execution of a . - ADO.NET Overview @@ -230,11 +230,11 @@ Gets or sets the text command to run against the data source. The text command to execute. The default value is an empty string (""). - 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. - + 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. + ]]> ADO.NET Overview @@ -282,13 +282,13 @@ Gets or sets the wait time (in seconds) before terminating the attempt to execute the command and generating an error. The time in seconds to wait for the command to execute. - is generated if the assigned property value is less than 0. - - Note to implementers, it is recommended that 0 mean no timeout. - + is generated if the assigned property value is less than 0. + + Note to implementers, it is recommended that 0 mean no timeout. + ]]> ADO.NET Overview @@ -346,11 +346,11 @@ Gets or sets how the property is interpreted. One of the enumeration values that specifies how a command string is interpreted. The default is . - 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. - + 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. + ]]> ADO.NET Overview @@ -821,13 +821,13 @@ Asynchronously diposes the command object. A representing the asynchronous operation. - , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . ]]> @@ -923,18 +923,18 @@ An instance of , specifying options for command execution and data retrieval. A token to cancel the asynchronous operation. - Providers should implement this method to provide a non-default implementation for overloads. - - The default implementation invokes the synchronous method and returns a completed task, blocking the calling thread. The default implementation will return a cancelled task if passed an already cancelled cancellation token. Exceptions thrown by ExecuteReader will be communicated via the returned Task Exception property. - + Providers should implement this method to provide a non-default implementation for overloads. + + The default implementation invokes the synchronous method and returns a completed task, blocking the calling thread. The default implementation will return a cancelled task if passed an already cancelled cancellation token. Exceptions thrown by ExecuteReader will be communicated via the returned Task Exception property. + This method accepts a cancellation token that can be used to request the operation to be cancelled early. Implementations may ignore this request. A task representing the asynchronous operation. - , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . ]]> @@ -988,15 +988,15 @@ Executes the command against its connection object, returning the number of rows affected. The number of rows affected. - 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. - - 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. - + 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. + + 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. + ]]> ADO.NET Overview @@ -1010,11 +1010,11 @@ This method implements the asynchronous version of , but returns a synchronously, blocking the calling thread. - An error occurred while executing the command. @@ -1058,15 +1058,15 @@ An asynchronous version of , which executes the command against its connection object, returning the number of rows affected. - + Invokes with CancellationToken.None. A task representing the asynchronous operation. - , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . ]]> @@ -1114,18 +1114,18 @@ A token to cancel the asynchronous operation. - This is the asynchronous version of . Providers should override with an appropriate implementation. The cancellation token may optionally be ignored. - - The default implementation invokes the synchronous method and returns a completed task, blocking the calling thread. The default implementation will return a cancelled task if passed an already cancelled cancellation token. Exceptions thrown by will be communicated via the returned Task Exception property. - + This is the asynchronous version of . Providers should override with an appropriate implementation. The cancellation token may optionally be ignored. + + The default implementation invokes the synchronous method and returns a completed task, blocking the calling thread. The default implementation will return a cancelled task if passed an already cancelled cancellation token. Exceptions thrown by will be communicated via the returned Task Exception property. + Do not invoke other methods and properties of the object until the returned Task is complete. A task representing the asynchronous operation. - , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . ]]> @@ -1243,11 +1243,11 @@ An asynchronous version of , which executes the command against its connection, returning a which can be used to access the results. - in . For more information about asynchronous programming, see [Asynchronous Programming](/dotnet/framework/data/adonet/asynchronous-programming). - + in . For more information about asynchronous programming, see [Asynchronous Programming](/dotnet/framework/data/adonet/asynchronous-programming). + ]]> ADO.NET Overview @@ -1290,15 +1290,15 @@ An asynchronous version of , which executes the command against its connection, returning a which can be used to access the results. - + Invokes with CancellationToken.None. A task representing the asynchronous operation. - in . For more information about asynchronous programming, see [Asynchronous Programming](/dotnet/framework/data/adonet/asynchronous-programming). - + 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 . ]]> @@ -1348,15 +1348,15 @@ One of the enumeration values that specifies how the command should execute and how data should be retrieved. An asynchronous version of , which executes the command against its connection, returning a which can be used to access the results. - + Invokes . A task representing the asynchronous operation. - in . For more information about asynchronous programming, see [Asynchronous Programming](/dotnet/framework/data/adonet/asynchronous-programming). - + 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 . ]]> @@ -1406,15 +1406,15 @@ A token to cancel the asynchronous operation. An asynchronous version of , which executes the command against its connection, returning a which can be used to access the results. - + Invokes . A task representing the asynchronous operation. - in . For more information about asynchronous programming, see [Asynchronous Programming](/dotnet/framework/data/adonet/asynchronous-programming). - + 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 . ]]> @@ -1469,11 +1469,11 @@ Invokes . A task representing the asynchronous operation. - in . For more information about asynchronous programming, see [Asynchronous Programming](/dotnet/framework/data/adonet/asynchronous-programming). - + 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 . ]]> @@ -1534,13 +1534,13 @@ Executes the command and returns the first column of the first row in the first returned result set. All other columns, rows and result sets are ignored. The first column of the first row in the first result set. - 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`. - + 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`. + ]]> ADO.NET Overview @@ -1554,11 +1554,11 @@ Implements the asynchronous version of , but returns a synchronously, blocking the calling thread. - ADO.NET Overview @@ -1601,16 +1601,16 @@ - An asynchronous version of , which executes the command and returns the first column of the first row in the first returned result set. All other columns, rows and result sets are ignored. - + An asynchronous version of , which executes the command and returns the first column of the first row in the first returned result set. All other columns, rows and result sets are ignored. + Invokes with CancellationToken.None. A task representing the asynchronous operation. - , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . ]]> @@ -1659,18 +1659,18 @@ A token to cancel the asynchronous operation. - This is the asynchronous version of . Providers should override with an appropriate implementation. The cancellation token may optionally be ignored. - - The default implementation invokes the synchronous method and returns a completed task, blocking the calling thread. The default implementation will return a cancelled task if passed an already cancelled cancellation token. Exceptions thrown by ExecuteScalar will be communicated via the returned Task Exception property. - + This is the asynchronous version of . Providers should override with an appropriate implementation. The cancellation token may optionally be ignored. + + The default implementation invokes the synchronous method and returns a completed task, blocking the calling thread. The default implementation will return a cancelled task if passed an already cancelled cancellation token. Exceptions thrown by ExecuteScalar will be communicated via the returned Task Exception property. + Do not invoke other methods and properties of the object until the returned Task is complete. A task representing the asynchronous operation. - , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . ]]> @@ -1774,11 +1774,11 @@ Creates a prepared (or compiled) version of the command on the data source. - 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. - + 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. + ]]> ADO.NET Overview @@ -1819,15 +1819,15 @@ Asynchronously creates a prepared (or compiled) version of the command on the data source. A representing the asynchronous operation. - 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 . ]]> @@ -1883,11 +1883,11 @@ Gets or sets the used by this instance of the . The connection to the data source. - . - + . + ]]> ADO.NET Overview @@ -1935,13 +1935,13 @@ Creates a new instance of an object. An object. - instance is cast to an interface. - - For more information, see . - + instance is cast to an interface. + + For more information, see . + ]]> ADO.NET Overview @@ -2000,13 +2000,13 @@ Executes the against the and builds an . An object. - instance is cast to an interface. - - For more information, see . - + instance is cast to an interface. + + For more information, see . + ]]> ADO.NET Overview @@ -2050,20 +2050,20 @@ System.Data.IDataReader - + One of the enumeration values that specifies the command behavior. Executes the against the , and builds an using one of the values. An object. - instance is cast to an interface. - - For more information, see . - + instance is cast to an interface. + + For more information, see . + ]]> ADO.NET Overview @@ -2110,13 +2110,13 @@ Gets the . The parameters of the SQL statement or stored procedure. - instance is cast to an interface. - - For more information, see . - + instance is cast to an interface. + + For more information, see . + ]]> ADO.NET Overview @@ -2170,11 +2170,11 @@ Gets or sets the within which this object executes. The transaction within which a object of a .NET Framework data provider executes. The default value is a null reference ( in Visual Basic). - . - + . + ]]> ADO.NET Overview @@ -2297,11 +2297,11 @@ Gets or sets how command results are applied to the when used by the Update method of a . One of the enumeration values that indicates how command results are applied. The default is unless the command is automatically generated. Then the default is . - if the value entered was not one of the values. - + if the value entered was not one of the values. + ]]> ADO.NET Overview diff --git a/xml/System.Data.Common/DbConnection.xml b/xml/System.Data.Common/DbConnection.xml index 7733e908d27..8b7e65153e2 100644 --- a/xml/System.Data.Common/DbConnection.xml +++ b/xml/System.Data.Common/DbConnection.xml @@ -174,11 +174,11 @@ When overridden in a derived class, starts a database transaction. An object representing the new transaction. - ADO.NET Overview @@ -222,13 +222,13 @@ Asynchronously starts a database transaction. A task whose property is an object representing the new transaction. - , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . ]]> @@ -244,11 +244,11 @@ Starts a database transaction. - Transactions and Concurrency (ADO.NET) @@ -295,11 +295,11 @@ Starts a database transaction. An object representing the new transaction. - Transactions and Concurrency (ADO.NET) @@ -388,15 +388,15 @@ Asynchronously begins a database transaction. A task whose property is an object representing the new transaction. - , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . ]]> @@ -441,13 +441,13 @@ Asynchronously begins a database transaction. A task whose property is an object representing the new transaction. - , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . ]]> @@ -482,9 +482,9 @@ if this instance supports the class; otherwise, . The default is . - should override this to return `true`. @@ -537,11 +537,11 @@ This property returns `false` by default; providers that implement The name of the database for the connection to use. When overridden in a derived class, changes the current database for an open connection. - ADO.NET Overview @@ -584,13 +584,13 @@ This property returns `false` by default; providers that implement Asynchronously changes the current database for an open connection. A task representing the asynchronous operation. - , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . @@ -642,18 +642,18 @@ This property returns `false` by default; providers that implement When overridden in a derived class, closes the connection to the database. - 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. - - 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. - + 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. + + 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. + > [!CAUTION] -> Do not close or dispose a `DbConnection`, a `DbDataReader`, 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 close or dispose a `DbConnection`, a `DbDataReader`, 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/). + ]]> @@ -694,22 +694,22 @@ This property returns `false` by default; providers that implement Asynchronously closes the connection to the database. A representing the asynchronous operation. - 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. - - 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. - + + 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. + + 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. + > [!CAUTION] -> Do not close or dispose a `DbConnection`, a `DbDataReader`, 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 close or dispose a `DbConnection`, a `DbDataReader`, 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/). + 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 . ]]> @@ -776,11 +776,11 @@ This property returns `false` by default; providers that implement When overridden in a derived class, gets or sets the string used to open the connection. The connection string used to establish the initial connection. The exact contents of the connection string depend on the specific data source for this connection. The default value is an empty string. - Connection Strings (ADO.NET) @@ -972,11 +972,11 @@ This property returns `false` by default; providers that implement When overridden in a derived class, creates and returns a object associated with the current connection. A object. - object. - + object. + ]]> Commands (ADO.NET) @@ -1025,11 +1025,11 @@ This property returns `false` by default; providers that implement When overridden in a derived class, gets the name of the current database after a connection is opened, or the database name specified in the connection string before the connection is opened. The name of the current database or the name of the database to be used after a connection is opened. The default value is an empty string. - ADO.NET Overview @@ -1074,11 +1074,11 @@ This property returns `false` by default; providers that implement When overridden in a derived class, gets the name of the database server to which to connect. The name of the database server to which to connect. The default value is an empty string. - 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. - + 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. + ]]> Connection Strings (ADO.NET) @@ -1229,13 +1229,13 @@ This property returns `false` by default; providers that implement Asynchronously diposes the connection object. A representing the asynchronous operation. - , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . ]]> @@ -1283,17 +1283,17 @@ This property returns `false` by default; providers that implement System.Void - + A reference to an existing in which to enlist. Enlists in the specified transaction. - instance, `EnlistTransaction` takes advantage of functionality available in the namespace for managing distributed transactions. Once a connection is explicitly enlisted in a transaction, it cannot be unenlisted or enlisted in another transaction until the first transaction finishes. - + instance, `EnlistTransaction` takes advantage of functionality available in the namespace for managing distributed transactions. Once a connection is explicitly enlisted in a transaction, it cannot be unenlisted or enlisted in another transaction until the first transaction finishes. + ]]> Transactions and Concurrency (ADO.NET) @@ -1309,11 +1309,11 @@ This property returns `false` by default; providers that implement Returns schema information for the data source of this . - Obtaining Schema Information from a Database @@ -1358,11 +1358,11 @@ This property returns `false` by default; providers that implement Returns schema information for the data source of this . A that contains schema information. - Obtaining Schema Information from a Database @@ -1403,18 +1403,18 @@ This property returns `false` by default; providers that implement System.Data.DataTable - + Specifies the name of the schema to return. Returns schema information for the data source of this using the specified string for the schema name. A that contains schema information. - @@ -1458,8 +1458,8 @@ This property returns `false` by default; providers that implement System.Data.DataTable - - + + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 2 })] @@ -1474,15 +1474,15 @@ This property returns `false` by default; providers that implement Returns schema information for the data source of this using the specified string for the schema name and the specified string array for the restriction values. A that contains schema information. - @@ -1657,11 +1657,11 @@ This property returns `false` by default; providers that implement A that contains the event data. Raises the event. - @@ -1712,11 +1712,11 @@ This property returns `false` by default; providers that implement When overridden in a derived class, opens a database connection with the settings specified by the . - will throw an exception if called again without first being closed. - + will throw an exception if called again without first being closed. + ]]> ADO.NET Overview @@ -1731,11 +1731,11 @@ This property returns `false` by default; providers that implement An error occurred while opening the connection. This method implements an asynchronous version of . - ADO.NET Overview @@ -1780,15 +1780,15 @@ This property returns `false` by default; providers that implement An asynchronous version of , which opens a database connection with the settings specified by the . This method invokes the virtual method with CancellationToken.None. A task representing the asynchronous operation. - , 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. - - For more information about asynchronous programming in the .NET Framework Data Provider for SQL Server, see [Asynchronous Programming](/dotnet/framework/data/adonet/asynchronous-programming). - + , 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. + + For more information about asynchronous programming in the .NET Framework Data Provider for SQL Server, 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 . ]]> @@ -1835,22 +1835,22 @@ This property returns `false` by default; providers that implement The cancellation instruction. - This is the asynchronous version of . Providers should override with an appropriate implementation. The cancellation token can optionally be honored. - - The default implementation invokes the synchronous call and returns a completed task. The default implementation will return a cancelled task if passed an already cancelled cancellationToken. Exceptions thrown by Open will be communicated via the returned Task Exception property. - + This is the asynchronous version of . Providers should override with an appropriate implementation. The cancellation token can optionally be honored. + + The default implementation invokes the synchronous call and returns a completed task. The default implementation will return a cancelled task if passed an already cancelled cancellationToken. Exceptions thrown by Open will be communicated via the returned Task Exception property. + Do not invoke other methods and properties of the object until the returned Task is complete. A task representing the asynchronous operation. - , 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. - - For more information about asynchronous programming in the .NET Framework Data Provider for SQL Server, see [Asynchronous Programming](/dotnet/framework/data/adonet/asynchronous-programming). - + , 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. + + For more information about asynchronous programming in the .NET Framework Data Provider for SQL Server, 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 . ]]> @@ -2013,11 +2013,11 @@ This property returns `false` by default; providers that implement Occurs when the state of the connection changes. - event occurs when the state of the connection changes from closed to opened or from opened to closed. - + event occurs when the state of the connection changes from closed to opened or from opened to closed. + ]]> ADO.NET Overview @@ -2076,13 +2076,13 @@ This property returns `false` by default; providers that implement Begins a database transaction. An object that represents the new transaction. - instance is cast to an interface. - - For more information, see . - + instance is cast to an interface. + + For more information, see . + ]]> ADO.NET Overview @@ -2126,18 +2126,18 @@ This property returns `false` by default; providers that implement System.Data.IDbTransaction - + One of the enumeration values that specifies the isolation level for the transaction to use. Begins a database transaction with the specified isolation level. An object that represents the new transaction. - . - + . + ]]> ADO.NET Overview @@ -2185,11 +2185,11 @@ This property returns `false` by default; providers that implement Creates and returns a object that is associated with the current connection. A object that is associated with the connection. - . - + . + ]]> ADO.NET Overview diff --git a/xml/System.Data.Common/DbConnectionStringBuilder.xml b/xml/System.Data.Common/DbConnectionStringBuilder.xml index 601c4ad5d85..426afec405c 100644 --- a/xml/System.Data.Common/DbConnectionStringBuilder.xml +++ b/xml/System.Data.Common/DbConnectionStringBuilder.xml @@ -208,7 +208,7 @@ initial catalog="AdventureWorks;NewValue=Bad" 9.0.0.0 - + @@ -421,9 +421,9 @@ initial catalog="AdventureWorks;NewValue=Bad" System.Void - - - + + + [System.Runtime.CompilerServices.Nullable(2)] @@ -431,7 +431,7 @@ initial catalog="AdventureWorks;NewValue=Bad" - + The to which to add the key/value pair. @@ -957,7 +957,7 @@ builder2.EquivalentTo(builder3) = False System.Void - + The to be filled with information about this . @@ -2338,7 +2338,7 @@ This member is an explicit interface member implementation. It can be used only System.Object - + A that represents the editor for this object. @@ -2463,7 +2463,7 @@ This member is an explicit interface member implementation. It can be used only System.ComponentModel.EventDescriptorCollection - + An array of type that is used as a filter. @@ -2594,7 +2594,7 @@ This member is an explicit interface member implementation. It can be used only System.ComponentModel.PropertyDescriptorCollection - + An array of type that is used as a filter. @@ -2650,7 +2650,7 @@ This member is an explicit interface member implementation. It can be used only System.Object - + A that represents the property whose owner is to be found. diff --git a/xml/System.Data.Common/DbDataReader.xml b/xml/System.Data.Common/DbDataReader.xml index 41a30fa3e39..94fe84d603a 100644 --- a/xml/System.Data.Common/DbDataReader.xml +++ b/xml/System.Data.Common/DbDataReader.xml @@ -215,13 +215,13 @@ Asynchronously closes the object. A task representing the asynchronous operation. - , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . ]]> @@ -270,11 +270,11 @@ Gets a value indicating the depth of nesting for the current row. The depth of nesting for the current row. - ADO.NET Overview @@ -339,16 +339,16 @@ Releases all resources used by the current instance of the class. - . Calling one of these methods leaves the in an unusable state. After disposing, 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). - + . Calling one of these methods leaves the in an unusable state. After disposing, 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 dispose 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 dispose 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. + ]]> ADO.NET Overview @@ -397,11 +397,11 @@ to release managed and unmanaged resources; to release only unmanaged resources. Releases the unmanaged resources used by the and optionally releases the managed resources. - . - + . + ]]> ADO.NET Overview @@ -443,18 +443,18 @@ Asynchronously releases all resources used by the current instance of the class. A representing the asynchronous operation. - . Calling one of these methods leaves the in an unusable state. After disposing, 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). - + . Calling one of these methods leaves the in an unusable state. After disposing, 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 dispose 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 dispose 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. + The default implementation of this asynchronous method delegates to its synchronous counterpart and returns a completed `ValueTask`, potentially blocking the calling thread. - + Data providers that support [asynchronous programming](/dotnet/framework/data/adonet/asynchronous-programming) should override the default implementation using asynchronous I/O operations. 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 . @@ -505,11 +505,11 @@ When overridden in a derived class, gets the number of columns in the current row. The number of columns in the current row. - to exclude hidden fields. - + to exclude hidden fields. + ]]> There is no current connection to an instance of SQL Server. @@ -935,20 +935,20 @@ When overridden in a derived class, gets name of the data type of the specified column. The name of the data type. - The column index is out of range. @@ -1213,13 +1213,13 @@ private static void GetDataTypes(String connectionString) When overridden in a derived class, returns an enumerator that can be used to iterate through the rows in the data reader. An enumerator that can be used to iterate through the rows in the data reader. - or ensure that your enumerator returns objects. - + or ensure that your enumerator returns objects. + ]]> ADO.NET Overview @@ -1329,19 +1329,19 @@ private static void GetDataTypes(String connectionString) 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- @@ -1413,9 +1413,9 @@ private static void GetDataTypes(String connectionString) A task whose contains the value of the specified column. - 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- @@ -1438,7 +1438,7 @@ private static void GetDataTypes(String connectionString) -or- - Tried to read a previously-read column in sequential mode. + Tried to read a previously-read column in sequential mode. -or- @@ -1503,9 +1503,9 @@ private static void GetDataTypes(String connectionString) A task whose contains the value of the specified column. - 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- @@ -1529,7 +1529,7 @@ private static void GetDataTypes(String connectionString) -or- - Tried to read a previously-read column in sequential mode. + Tried to read a previously-read column in sequential mode. -or- @@ -1738,33 +1738,33 @@ private static void GetDataTypes(String connectionString) When overridden in a derived class, gets the value of the specified column as a 32-bit signed integer. The value of the specified column. - The column index is out of range. @@ -2024,11 +2024,11 @@ private static void GetCredits(String connectionString) Gets the value of the specified column as an instance of a provider-specific type. The value of the specified column. - . - + . + ]]> ADO.NET Overview @@ -2224,25 +2224,25 @@ Returns if the executed command returned no resultset, o 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- @@ -2344,25 +2344,25 @@ Returns if the executed command returned no resultset, o 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- @@ -2610,11 +2610,11 @@ Returns if the executed command returned no resultset, o 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 column index is out of range. @@ -2676,7 +2676,7 @@ Returns if the executed command returned no resultset, o if the executed command returned no resultset, o ]]> - 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- @@ -2756,7 +2756,7 @@ Returns if the executed command returned no resultset, o if the executed command returned no resultset, o Data providers that support [asynchronous programming](/dotnet/framework/data/adonet/asynchronous-programming) should override the default implementation 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 column index is out of range. The cancellation token was canceled. This exception is stored into the returned task. @@ -2946,11 +2946,11 @@ Returns if the executed command returned no resultset, o if there are more result sets; otherwise, . - ADO.NET Overview @@ -2964,11 +2964,11 @@ Returns if the executed command returned no resultset, o Asynchronously advances the reader to the next result when reading the results of a batch of statements. - ADO.NET Overview @@ -3013,8 +3013,8 @@ Returns if the executed command returned no resultset, o Asynchronously advances the reader to the next result when reading the results of a batch of statements. A task whose property is if there are more result sets or if there aren't. - if the executed command returned no resultset, o Asynchronously advances the reader to the next result when reading the results of a batch of statements. A whose property is if there are more result sets or if there aren't. - , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . @@ -3132,11 +3132,11 @@ Returns if the executed command returned no resultset, o if there are more rows; otherwise, . - to begin accessing data. - + to begin accessing data. + ]]> ADO.NET Overview @@ -3150,11 +3150,11 @@ Returns if the executed command returned no resultset, o Asynchronously advances the reader to the next record in a result set. - ADO.NET Overview @@ -3199,12 +3199,12 @@ Returns if the executed command returned no resultset, o Asynchronously advances the reader to the next record in a result set. A whose property is if there are more rows or if there aren't. - , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . @@ -3257,14 +3257,14 @@ Returns if the executed command returned no resultset, o Asynchronously advances the reader to the next record in a result set. A whose property is if there are more rows or if there aren't. - , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . @@ -3318,11 +3318,11 @@ Returns if the executed command returned no resultset, o When overridden in a derived class, gets the number of rows changed, inserted, or deleted by execution of the SQL statement. The number of rows changed, inserted, or deleted. -1 for SELECT statements; 0 if no rows were affected or the statement failed. - @@ -3446,18 +3446,18 @@ This member is an explicit interface member implementation. It can be used only System.Data.IDataReader - + The zero-based column ordinal. For a description of this member, see . An instance of to be used when the field points to more remote structured data. - instance is cast to an interface. - + instance is cast to an interface. + ]]> ADO.NET Overview @@ -3502,11 +3502,11 @@ This member is an explicit interface member implementation. It can be used only Gets the number of fields in the that are not hidden. The number of fields that are not hidden. - are visible. For example, a SELECT on a partial primary key returns the remaining parts of the key as hidden fields. The hidden fields are always appended behind the visible fields. - + are visible. For example, a SELECT on a partial primary key returns the remaining parts of the key as hidden fields. The hidden fields are always appended behind the visible fields. + ]]> ADO.NET Overview diff --git a/xml/System.Data.Common/DbException.xml b/xml/System.Data.Common/DbException.xml index a154892f1ab..72c88721880 100644 --- a/xml/System.Data.Common/DbException.xml +++ b/xml/System.Data.Common/DbException.xml @@ -64,13 +64,13 @@ The base class for all exceptions thrown on behalf of the data source. - class is an abstract class used as the base class for provider-specific exception class implementations. - - For general information about handling exceptions for a .NET Framework data provider, see . - + class is an abstract class used as the base class for provider-specific exception class implementations. + + For general information about handling exceptions for a .NET Framework data provider, see . + ]]> DbProviderFactories (ADO.NET) @@ -85,11 +85,11 @@ Initializes a new instance of the class. - class is an abstract class used as the base class for provider-specific exception class implementations. - + class is an abstract class used as the base class for provider-specific exception class implementations. + ]]> ADO.NET Overview @@ -130,11 +130,11 @@ Initializes a new instance of the class. - class is an abstract class used as the base class for provider-specific exception class implementations. - + class is an abstract class used as the base class for provider-specific exception class implementations. + ]]> ADO.NET Overview @@ -180,11 +180,11 @@ The message to display for this exception. Initializes a new instance of the class with the specified error message. - class is an abstract class used as the base class for provider-specific exception class implementations. - + class is an abstract class used as the base class for provider-specific exception class implementations. + ]]> ADO.NET Overview @@ -235,19 +235,19 @@ - - + + The that holds the serialized object data about the exception being thrown. The that contains contextual information about the source or destination. Initializes a new instance of the class with the specified serialization information and context. - class is an abstract class used as the base class for provider-specific exception class implementations. - + class is an abstract class used as the base class for provider-specific exception class implementations. + ]]> ADO.NET Overview @@ -295,11 +295,11 @@ The inner exception reference. Initializes a new instance of the class with the specified error message and a reference to the inner exception that is the cause of this exception. - class is an abstract class used as the base class for provider-specific exception class implementations. - + class is an abstract class used as the base class for provider-specific exception class implementations. + ]]> ADO.NET Overview @@ -337,19 +337,19 @@ 9.0.0.0 - - + + The error message that explains the reason for the exception. The error code for the exception. Initializes a new instance of the class with the specified error message and error code. - class is an abstract class used as the base class for provider-specific exception class implementations. - + class is an abstract class used as the base class for provider-specific exception class implementations. + ]]> ADO.NET Overview @@ -380,11 +380,11 @@ If this was thrown when executing a , references the specific which triggered the exception. The specific which triggered the exception. - wasn't thrown when executing a , contains `null`. - + ]]> @@ -414,12 +414,12 @@ When overridden in a derived class, if this was thrown when executing a , references the specific which triggered the exception. The specific which triggered the exception. - wasn't thrown when executing a , the value is `null`. - + ]]> diff --git a/xml/System.Data.Common/DbParameterCollection.xml b/xml/System.Data.Common/DbParameterCollection.xml index f1807891d9b..263b4e19f80 100644 --- a/xml/System.Data.Common/DbParameterCollection.xml +++ b/xml/System.Data.Common/DbParameterCollection.xml @@ -1741,13 +1741,13 @@ This member is an explicit interface member implementation. It can be used only Gets or sets the element at the 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 . + ]]> ADO.NET Overview @@ -1834,20 +1834,20 @@ This member is an explicit interface member implementation. System.Object - + The name of the parameter to retrieve. Gets or sets the parameter at the specified index. An at the specified index. - 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/DbProviderFactory.xml b/xml/System.Data.Common/DbProviderFactory.xml index 9b66c732fd8..d56cd564723 100644 --- a/xml/System.Data.Common/DbProviderFactory.xml +++ b/xml/System.Data.Common/DbProviderFactory.xml @@ -96,11 +96,11 @@ Initializes a new instance of the class. - . - + . + ]]> DbProviderFactories (ADO.NET) @@ -134,9 +134,9 @@ if this instance supports the class; otherwise, . The default is . - should override this to return `true`. @@ -698,7 +698,7 @@ This property returns `false` by default; providers that implement System.Security.CodeAccessPermission - + One of the values. diff --git a/xml/System.Data.Odbc/OdbcConnection.xml b/xml/System.Data.Odbc/OdbcConnection.xml index b5aa6438582..ffb3c4e842b 100644 --- a/xml/System.Data.Odbc/OdbcConnection.xml +++ b/xml/System.Data.Odbc/OdbcConnection.xml @@ -51,30 +51,30 @@ Represents an open connection to a data source. - 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. - + 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. + > [!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. - - If one of the `Execute` methods of the class causes a fatal (for example, a SQL Server severity level of 20 or greater), the may close. However, the user can reopen the connection and continue. - - An application that creates an instance of the object can require all direct and indirect callers to have sufficient permission to the code by setting declarative or imperative security demands. creates security demands by using the object. Users can verify that their code has sufficient 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 computer, user, and enterprise levels. For more information, see [Code Access Security and ADO.NET](/dotnet/framework/data/adonet/code-access-security). - - For more information about handling warning and informational messages from the data source, see [Connection Events](/dotnet/framework/data/adonet/connection-events). - - - -## 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. - +> 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. + + If one of the `Execute` methods of the class causes a fatal (for example, a SQL Server severity level of 20 or greater), the may close. However, the user can reopen the connection and continue. + + An application that creates an instance of the object can require all direct and indirect callers to have sufficient permission to the code by setting declarative or imperative security demands. creates security demands by using the object. Users can verify that their code has sufficient 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 computer, user, and enterprise levels. For more information, see [Code Access Security and ADO.NET](/dotnet/framework/data/adonet/code-access-security). + + For more information about handling warning and informational messages from the data source, see [Connection Events](/dotnet/framework/data/adonet/connection-events). + + + +## 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. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OdbcConnection/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData OdbcConnection/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData OdbcConnection/VB/source.vb" id="Snippet1"::: + ]]> Connecting to Data Sources @@ -118,27 +118,27 @@ Initializes a new instance of the class. - is created, the write-only and read-only properties are set to the following initial values unless they are specifically set using their associated keywords in the property. - -|Properties|Initial value| -|----------------|-------------------| -||empty string ("")| -||15| -||empty string ("")| - - You can change the value for these properties only by using the property. - - - -## Examples - The following example creates and opens an . - + is created, the write-only and read-only properties are set to the following initial values unless they are specifically set using their associated keywords in the property. + +|Properties|Initial value| +|----------------|-------------------| +||empty string ("")| +||15| +||empty string ("")| + + You can change the value for these properties only by using the property. + + + +## Examples + The following example creates and opens an . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OdbcConnection.OdbcConnection/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData OdbcConnection.OdbcConnection/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData OdbcConnection.OdbcConnection/VB/source.vb" id="Snippet1"::: + ]]> Connecting to Data Sources @@ -183,27 +183,27 @@ The connection used to open the data source. Initializes a new instance of the class with the specified connection string. - is created, the write-only and read-only properties are set to the following initial values unless they are specifically set using their associated keywords in the property. - -|Properties|Initial value| -|----------------|-------------------| -||`connectionString`| -||15| -||empty string ("")| - - You can change the value for these properties only by using the property. - - - -## Examples - The following example creates and opens an . - + is created, the write-only and read-only properties are set to the following initial values unless they are specifically set using their associated keywords in the property. + +|Properties|Initial value| +|----------------|-------------------| +||`connectionString`| +||15| +||empty string ("")| + + You can change the value for these properties only by using the property. + + + +## Examples + The following example creates and opens an . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OdbcConnection.OdbcConnection1/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData OdbcConnection.OdbcConnection1/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData OdbcConnection.OdbcConnection1/VB/source.vb" id="Snippet1"::: + ]]> Connecting to Data Sources @@ -290,24 +290,24 @@ Starts a transaction at the data source. An object representing the new transaction. - 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. - + 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. - - - -## Examples - The following example creates an and an . It also demonstrates how to use the , , and methods. - +> 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. + :::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/VS_Snippets_ADO.NET/Classic WebData OdbcConnection.BeginTransaction1/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData OdbcConnection.BeginTransaction1/VB/source.vb" id="Snippet1"::: + ]]> A transaction is currently active. Parallel transactions are not supported. @@ -351,21 +351,21 @@ Starts a transaction at the data source with the specified value. An object representing the new transaction. - 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. - + 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. + :::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/VS_Snippets_ADO.NET/Classic WebData OdbcConnection.BeginTransaction1/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData OdbcConnection.BeginTransaction1/VB/source.vb" id="Snippet1"::: + ]]> A transaction is currently active. Parallel transactions are not supported. @@ -415,19 +415,19 @@ The database name. Changes the current database associated with an open . - and changes the current database. - + and changes the current database. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OdbcConnection.Database/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData OdbcConnection.Database/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData OdbcConnection.Database/VB/source.vb" id="Snippet1"::: + ]]> The database name is not valid. @@ -476,27 +476,27 @@ Closes the connection to the data source. - 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. - + 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. + > [!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. - +> 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/). - - - -## Examples - The following example creates an , opens it, displays some of its properties, and then closes the connection. - +> 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/). + + + +## Examples + The following example creates an , opens it, displays some of its properties, and then closes the connection. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OdbcConnection.Close/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData OdbcConnection.Close/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData OdbcConnection.Close/VB/source.vb" id="Snippet1"::: + ]]> Connecting to Data Sources @@ -570,63 +570,63 @@ Gets or sets the string used to open a data source. The ODBC driver connection string that includes settings, such as the data source name, needed to establish the initial connection. The default value is an empty string (""). The maximum length is 1024 characters. - 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. - -``` -"Driver={SQL Server};Server=(local);Trusted_Connection=Yes;Database=AdventureWorks;" - -"Driver={Microsoft ODBC for Oracle};Server=ORACLE8i7;Persist Security Info=False;Trusted_Connection=Yes" - -"Driver={Microsoft Access Driver (*.mdb)};DBQ=c:\bin\Northwind.mdb" - -"Driver={Microsoft Excel Driver (*.xls)};DBQ=c:\bin\book1.xls" - -"Driver={Microsoft Text Driver (*.txt; *.csv)};DBQ=c:\bin" - -"DSN=dsnname" -``` - + 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. + +``` +"Driver={SQL Server};Server=(local);Trusted_Connection=Yes;Database=AdventureWorks;" + +"Driver={Microsoft ODBC for Oracle};Server=ORACLE8i7;Persist Security Info=False;Trusted_Connection=Yes" + +"Driver={Microsoft Access Driver (*.mdb)};DBQ=c:\bin\Northwind.mdb" + +"Driver={Microsoft Excel Driver (*.xls)};DBQ=c:\bin\book1.xls" + +"Driver={Microsoft Text Driver (*.txt; *.csv)};DBQ=c:\bin" + +"DSN=dsnname" +``` + > [!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 . - - 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 . - - In the Microsoft .NET Framework version 1.0, validation of the connection string does not occur until an application calls the method. It is the responsibility of the underlying ODBC driver to validate the connection string. If the connection string contains invalid or unsupported properties, the driver may raise an at run time. - - However, in the .NET Framework version 1.1 and later versions, 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: - -``` -connection-string ::= empty-string[;] | attribute[;] | attribute; connection-string -empty-string ::= -attribute ::= attribute-keyword=attribute-value | DRIVER=[{]attribute-value[}] -attribute-keyword ::= DSN | UID | PWD - | driver-defined-attribute-keyword -attribute-value ::= character-string -driver-defined-attribute-keyword ::= identifier -``` - - where `character-string` has zero or more characters; `identifier` has one or more characters; `attribute-keyword` is not case sensitive; `attribute-value` can be case sensitive; and the value of the DSN keyword does not consist only of blanks. - - Because of connection string and initialization file grammar, keywords and attribute values should be avoided that contain the characters []{}(),;?*=!@ not enclosed with braces. The value of the DSN keyword cannot consist only of blanks and should not contain leading blanks. Because of the grammar of the system information, keywords and data source names cannot contain the backslash (\\) character. - - Applications do not have to add braces around the attribute value after the Driver keyword unless the attribute contains a semicolon (;), in which case the braces are required. If the attribute value that the driver receives includes braces, the driver should not remove them but they should be part of the returned connection string. - - A DSN or connection string value enclosed with braces ({}) that contains any of the characters []{}(),;?*=!@ is passed intact to the driver. However, when you use these characters in a keyword, the Driver Manager returns an error when you work with file DSNs, but passes the connection string to the driver for regular connection strings. Avoid using embedded braces in a keyword value. - - The connection string may include any number of driver-defined keywords. Because the DRIVER keyword does not use information from the system, the driver must define enough keywords so that a driver can connect to a data source using only the information in the connection string. The driver defines which keywords are required to connect to the data source. - - If any keywords are repeated in the connection string, there is no guarantee which value will be selected. - +> 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 . + + In the Microsoft .NET Framework version 1.0, validation of the connection string does not occur until an application calls the method. It is the responsibility of the underlying ODBC driver to validate the connection string. If the connection string contains invalid or unsupported properties, the driver may raise an at run time. + + However, in the .NET Framework version 1.1 and later versions, 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: + +``` +connection-string ::= empty-string[;] | attribute[;] | attribute; connection-string +empty-string ::= +attribute ::= attribute-keyword=attribute-value | DRIVER=[{]attribute-value[}] +attribute-keyword ::= DSN | UID | PWD + | driver-defined-attribute-keyword +attribute-value ::= character-string +driver-defined-attribute-keyword ::= identifier +``` + + where `character-string` has zero or more characters; `identifier` has one or more characters; `attribute-keyword` is not case sensitive; `attribute-value` can be case sensitive; and the value of the DSN keyword does not consist only of blanks. + + Because of connection string and initialization file grammar, keywords and attribute values should be avoided that contain the characters []{}(),;?*=!@ not enclosed with braces. The value of the DSN keyword cannot consist only of blanks and should not contain leading blanks. Because of the grammar of the system information, keywords and data source names cannot contain the backslash (\\) character. + + Applications do not have to add braces around the attribute value after the Driver keyword unless the attribute contains a semicolon (;), in which case the braces are required. If the attribute value that the driver receives includes braces, the driver should not remove them but they should be part of the returned connection string. + + A DSN or connection string value enclosed with braces ({}) that contains any of the characters []{}(),;?*=!@ is passed intact to the driver. However, when you use these characters in a keyword, the Driver Manager returns an error when you work with file DSNs, but passes the connection string to the driver for regular connection strings. Avoid using embedded braces in a keyword value. + + The connection string may include any number of driver-defined keywords. Because the DRIVER keyword does not use information from the system, the driver must define enough keywords so that a driver can connect to a data source using only the information in the connection string. The driver defines which keywords are required to connect to the data source. + + If any keywords are repeated in the connection string, there is no guarantee which value will be selected. + > [!NOTE] -> If an ODBC driver supports connection strings longer than 1024 characters, you can use a data source name (DSN) to exceed the maximum length limitation. - +> If an ODBC driver supports connection strings longer than 1024 characters, you can use a data source name (DSN) to exceed the maximum length limitation. + ]]> Connecting to Data Sources @@ -674,11 +674,11 @@ driver-defined-attribute-keyword ::= identifier Gets or sets the time to wait (in seconds) while trying to establish a connection before terminating the attempt and generating an error. The time in seconds to wait for a connection to open. The default value is 15 seconds. - property before calling . This is equivalent to setting the ODBC `SQLSetConnectAttr` SQL_ATTR_LOGIN_TIMOUT attribute. - + property before calling . This is equivalent to setting the ODBC `SQLSetConnectAttr` SQL_ATTR_LOGIN_TIMOUT attribute. + ]]> The value set is less than 0. @@ -800,21 +800,21 @@ driver-defined-attribute-keyword ::= identifier Gets the name of the current database or the database to be used after a connection is opened. The name of the current database. The default value is an empty string ("") until the connection is opened. - 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. - - - -## Examples - The following example creates an and changes the current database. - + 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. + + + +## Examples + The following example creates an and changes the current database. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OdbcConnection.Database/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData OdbcConnection.Database/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData OdbcConnection.Database/VB/source.vb" id="Snippet1"::: + ]]> Connecting to Data Sources @@ -865,19 +865,19 @@ driver-defined-attribute-keyword ::= identifier Gets the server name or file name of the data source. The server name or file name of the data source. The default value is an empty string ("") until the connection is opened. - property is equivalent to calling the ODBC function `SQLGetInfo` with the `InfoType` parameter set to SQL_SERVER_NAME. - - - -## Examples - The following example creates an and displays the backend data source name. - + property is equivalent to calling the ODBC function `SQLGetInfo` with the `InfoType` parameter set to SQL_SERVER_NAME. + + + +## Examples + The following example creates an and displays the backend data source name. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OdbcConnection.DataSource/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData OdbcConnection.DataSource/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData OdbcConnection.DataSource/VB/source.vb" id="Snippet1"::: + ]]> Connecting to Data Sources @@ -962,11 +962,11 @@ driver-defined-attribute-keyword ::= identifier Gets the name of the ODBC driver specified for the current connection. The name of the ODBC driver. This typically is the DLL name (for example, Sqlsrv32.dll). The default value is an empty string ("") until the connection is opened. - property is equivalent to calling the ODBC function `SQLGetInfo` with the `InfoType` parameter set to SQL_DRIVER_NAME. - + property is equivalent to calling the ODBC function `SQLGetInfo` with the `InfoType` parameter set to SQL_DRIVER_NAME. + ]]> Connecting to Data Sources @@ -993,21 +993,21 @@ driver-defined-attribute-keyword ::= identifier System.Void - + A reference to an existing in which to enlist. Enlists in the specified transaction as a distributed transaction. - 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 . - + 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 . + ]]> @@ -1032,17 +1032,17 @@ driver-defined-attribute-keyword ::= identifier System.Void - + A reference to an existing in which to enlist. Enlists in the specified transaction as a distributed transaction. - 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). + ]]> @@ -1114,21 +1114,21 @@ driver-defined-attribute-keyword ::= identifier System.Data.DataTable - + Specifies the name of the schema to return. Returns schema information for the data source of this using the specified name for the schema name. A that contains schema information. - contains information about all available metadata and any restrictions. - + contains information about all available metadata and any restrictions. + > [!NOTE] -> All restrictions that apply to the `SQLStatistics` method also apply to the `ODBCConnection.GetSchema("indexes")` collection. - +> All restrictions that apply to the `SQLStatistics` method also apply to the `ODBCConnection.GetSchema("indexes")` collection. + ]]> Obtaining Schema Information from a Database @@ -1160,8 +1160,8 @@ driver-defined-attribute-keyword ::= identifier System.Data.DataTable - - + + [System.Runtime.CompilerServices.Nullable(2)] @@ -1176,18 +1176,18 @@ driver-defined-attribute-keyword ::= identifier Returns schema information for the data source of this using the specified string for the schema name and the specified string array for the restriction values. A that contains schema information. - contains information about all the metadata that is available, and its restrictions. - - The `restrictionValues` parameter can supply *n* depth of values which are specified by the restrictions collection for a specific collection. In order to set values on a given restriction, and not set the values of other restrictions, you must set the preceding restrictions to null and then put the appropriate value in for the restriction that you would like to specify a value for. - - 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," then you would need to pass in at least 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. - + contains information about all the metadata that is available, and its restrictions. + + The `restrictionValues` parameter can supply *n* depth of values which are specified by the restrictions collection for a specific collection. In order to set values on a given restriction, and not set the values of other restrictions, you must set the preceding restrictions to null and then put the appropriate value in for the restriction that you would like to specify a value for. + + 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," then you would need to pass in at least 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. + > [!NOTE] -> All restrictions that apply to SQLStatistics method will apply to the ODBCConnection.GetSchema("indexes") collection. - +> All restrictions that apply to SQLStatistics method will apply to the ODBCConnection.GetSchema("indexes") collection. + ]]> Obtaining Schema Information from a Database @@ -1239,11 +1239,11 @@ driver-defined-attribute-keyword ::= identifier Occurs when the ODBC driver sends a warning or an informational message. - delegate to listen to this event. - + delegate to listen to this event. + ]]> Connecting to Data Sources @@ -1289,14 +1289,14 @@ driver-defined-attribute-keyword ::= identifier Opens a connection to a data source with the property settings specified by the . - draws an open connection from the connection pool if one is available. Otherwise, it establishes a new connection to the data source. - + 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. + ]]> The functionality of this method is unsupported in the base class and must be implemented in a derived class instead. @@ -1335,25 +1335,25 @@ driver-defined-attribute-keyword ::= identifier Indicates that the ODBC Driver Manager environment handle can be released when the last underlying connection is released. - to release the object from the environment. - -2. Allow each connection object to time out. - -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. - - After an environment handle is released, a request for a new creates a new environment. - + to release the object from the environment. + +2. Allow each connection object to time out. + +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. + + After an environment handle is released, a request for a new creates a new environment. + ]]> Connecting to Data Sources @@ -1404,13 +1404,13 @@ driver-defined-attribute-keyword ::= identifier Gets a string that contains the version of the server to which the client is connected. The version of the connected server. - 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. - + 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. + ]]> The connection is closed. @@ -1465,18 +1465,18 @@ driver-defined-attribute-keyword ::= identifier Gets the current state of the connection. A bitwise combination of the values. The default is . - method. - -- From `Open` to `Closed`, using either the or **Dispose** method. - + 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. - +> 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. + ]]> Connecting to Data Sources @@ -1639,11 +1639,11 @@ This member is an explicit interface member implementation. It can be used only For a description of this member, see . A new that is a copy of this instance. - instance is cast to an interface. - + instance is cast to an interface. + ]]> diff --git a/xml/System.Data.Odbc/OdbcFactory.xml b/xml/System.Data.Odbc/OdbcFactory.xml index d3d5e98c262..cff9cc2af47 100644 --- a/xml/System.Data.Odbc/OdbcFactory.xml +++ b/xml/System.Data.Odbc/OdbcFactory.xml @@ -62,21 +62,21 @@ Returns a strongly-typed instance. A new strongly-typed instance of . - instance: - -```vb -Dim newFactory As OdbcFactory = OdbcFactory.Instance -Dim cmd As DbCommand = newFactory.CreateCommand() -``` - -```csharp -OdbcFactory newFactory = OdbcFactory.Instance; -DbCommand cmd = newFactory.CreateCommand(); -``` - + instance: + +```vb +Dim newFactory As OdbcFactory = OdbcFactory.Instance +Dim cmd As DbCommand = newFactory.CreateCommand() +``` + +```csharp +OdbcFactory newFactory = OdbcFactory.Instance; +DbCommand cmd = newFactory.CreateCommand(); +``` + ]]> @@ -113,21 +113,21 @@ DbCommand cmd = newFactory.CreateCommand(); Returns a strongly-typed instance. A new strongly-typed instance of . - instance: - -```vb -Dim newFactory As OdbcFactory = OdbcFactory.Instance -Dim cmd As DbCommandBuilder = newFactory.CreateCommandBuilder() -``` - -```csharp -OdbcFactory newFactory = OdbcFactory.Instance; -DbCommandBuilder cmd = newFactory.CreateCommandBuilder(); -``` - + instance: + +```vb +Dim newFactory As OdbcFactory = OdbcFactory.Instance +Dim cmd As DbCommandBuilder = newFactory.CreateCommandBuilder() +``` + +```csharp +OdbcFactory newFactory = OdbcFactory.Instance; +DbCommandBuilder cmd = newFactory.CreateCommandBuilder(); +``` + ]]> @@ -164,21 +164,21 @@ DbCommandBuilder cmd = newFactory.CreateCommandBuilder(); Returns a strongly-typed instance. A new strongly-typed instance of . - instance: - -```vb -Dim newFactory As OdbcFactory = OdbcFactory.Instance -Dim cmd As DbConnection = newFactory.CreateConnection() -``` - -```csharp -OdbcFactory newFactory = OdbcFactory.Instance; -DbConnection cmd = newFactory.CreateConnection(); -``` - + instance: + +```vb +Dim newFactory As OdbcFactory = OdbcFactory.Instance +Dim cmd As DbConnection = newFactory.CreateConnection() +``` + +```csharp +OdbcFactory newFactory = OdbcFactory.Instance; +DbConnection cmd = newFactory.CreateConnection(); +``` + ]]> @@ -215,21 +215,21 @@ DbConnection cmd = newFactory.CreateConnection(); Returns a strongly-typed instance. A new strongly-typed instance of . - instance: - -```vb -Dim newFactory As OdbcFactory = OdbcFactory.Instance -Dim cmd As DbConnectionStringBuilder = newFactory.CreateConnectionStringBuilder() -``` - -```csharp -OdbcFactory newFactory = OdbcFactory.Instance; -DbConnectionStringBuilder cmd = newFactory.CreateConnectionStringBuilder(); -``` - + instance: + +```vb +Dim newFactory As OdbcFactory = OdbcFactory.Instance +Dim cmd As DbConnectionStringBuilder = newFactory.CreateConnectionStringBuilder() +``` + +```csharp +OdbcFactory newFactory = OdbcFactory.Instance; +DbConnectionStringBuilder cmd = newFactory.CreateConnectionStringBuilder(); +``` + ]]> @@ -266,21 +266,21 @@ DbConnectionStringBuilder cmd = newFactory.CreateConnectionStringBuilder(); Returns a strongly-typed instance. A new strongly-typed instance of . - instance: - -```vb -Dim newFactory As OdbcFactory = OdbcFactory.Instance -Dim cmd As DbDataAdapter = newFactory.CreateDataAdapter() -``` - -```csharp -OdbcFactory newFactory = OdbcFactory.Instance; -DbDataAdapter cmd = newFactory.CreateDataAdapter(); -``` - + instance: + +```vb +Dim newFactory As OdbcFactory = OdbcFactory.Instance +Dim cmd As DbDataAdapter = newFactory.CreateDataAdapter() +``` + +```csharp +OdbcFactory newFactory = OdbcFactory.Instance; +DbDataAdapter cmd = newFactory.CreateDataAdapter(); +``` + ]]> @@ -317,21 +317,21 @@ DbDataAdapter cmd = newFactory.CreateDataAdapter(); Returns a strongly-typed instance. A new strongly-typed instance of . - instance: - -```vb -Dim newFactory As OdbcFactory = OdbcFactory.Instance -Dim cmd As DbParameter = newFactory.CreateParameter() -``` - -```csharp -OdbcFactory newFactory = OdbcFactory.Instance; -DbParameter cmd = newFactory.CreateParameter(); -``` - + instance: + +```vb +Dim newFactory As OdbcFactory = OdbcFactory.Instance +Dim cmd As DbParameter = newFactory.CreateParameter() +``` + +```csharp +OdbcFactory newFactory = OdbcFactory.Instance; +DbParameter cmd = newFactory.CreateParameter(); +``` + ]]> @@ -356,7 +356,7 @@ DbParameter cmd = newFactory.CreateParameter(); System.Security.CodeAccessPermission - + A member of the enumeration. @@ -395,21 +395,21 @@ DbParameter cmd = newFactory.CreateParameter(); Gets an instance of the , which can be used to retrieve strongly-typed data objects. - field to retrieve an instance, and then return a strongly-typed instance: - -```vb -Dim newFactory As OdbcFactory = OdbcFactory.Instance -Dim cmd As DbCommand = newFactory.CreateCommand() -``` - -```csharp -OdbcFactory newFactory = OdbcFactory.Instance; -DbCommand cmd = newFactory.CreateCommand(); -``` - + field to retrieve an instance, and then return a strongly-typed instance: + +```vb +Dim newFactory As OdbcFactory = OdbcFactory.Instance +Dim cmd As DbCommand = newFactory.CreateCommand() +``` + +```csharp +OdbcFactory newFactory = OdbcFactory.Instance; +DbCommand cmd = newFactory.CreateCommand(); +``` + ]]> diff --git a/xml/System.Data.OleDb/OleDbConnection.xml b/xml/System.Data.OleDb/OleDbConnection.xml index cb723de1c49..350896c42f5 100644 --- a/xml/System.Data.OleDb/OleDbConnection.xml +++ b/xml/System.Data.OleDb/OleDbConnection.xml @@ -62,37 +62,37 @@ Represents an open connection to a data source. - object represents a unique connection to a data source. With a client/server database system, it is equivalent to a network connection to the server. Depending on the functionality supported by the native OLE DB provider, some methods or properties of an object may not be available. - - When you create an instance of , all properties are set to their initial values. For a list of these values, see the constructor. - - 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. - + object represents a unique connection to a data source. With a client/server database system, it is equivalent to a network connection to the server. Depending on the functionality supported by the native OLE DB provider, some methods or properties of an object may not be available. + + When you create an instance of , all properties are set to their initial values. For a list of these values, see the constructor. + + 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. + > [!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). - - If a fatal (for example, a SQL Server severity level of 20 or greater) is generated by the method executing an , the might be closed. However, the user can reopen the connection and continue. - - An application that creates an instance of the object can require all direct and indirect callers to have sufficient permission to the code by setting declarative or imperative security demands. makes security demands using the object. Users can verify that their code has sufficient permissions by using the object. Users and administrators can also use the [Caspol.exe (Code Access Security Policy Tool)](/dotnet/framework/tools/caspol-exe-code-access-security-policy-tool) to modify security policy at the computer, user, and enterprise levels. For more information, see [Code Access Security and ADO.NET](/dotnet/framework/data/adonet/code-access-security). - - For more information about handling warning and informational messages from the data server, see [Connection Events](/dotnet/framework/data/adonet/connection-events). - +> 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). + + If a fatal (for example, a SQL Server severity level of 20 or greater) is generated by the method executing an , the might be closed. However, the user can reopen the connection and continue. + + An application that creates an instance of the object can require all direct and indirect callers to have sufficient permission to the code by setting declarative or imperative security demands. makes security demands using the object. Users can verify that their code has sufficient permissions by using the object. Users and administrators can also use the [Caspol.exe (Code Access Security Policy Tool)](/dotnet/framework/tools/caspol-exe-code-access-security-policy-tool) to modify security policy at the computer, user, and enterprise levels. For more information, see [Code Access Security and ADO.NET](/dotnet/framework/data/adonet/code-access-security). + + For more information about handling warning and informational messages from the data server, see [Connection Events](/dotnet/framework/data/adonet/connection-events). + > [!NOTE] -> The object does not support setting or retrieving dynamic properties specific to an OLE DB provider. Only properties that can be passed in the connection string for the OLE DB provider are supported. - - - -## 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 object does not support setting or retrieving dynamic properties specific to an OLE DB provider. Only properties that can be passed in the connection string for the OLE DB provider are supported. + + + +## 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. + :::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/VS_Snippets_ADO.NET/Classic WebData OleDbConnection Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData OleDbConnection Example/VB/source.vb" id="Snippet1"::: + ]]> Connecting to Data Sources @@ -135,28 +135,28 @@ Initializes a new instance of the class. - is created, the read/write properties are set to the following initial values unless they are specifically set using their associated keywords in the property. - -|Properties|Initial value| -|----------------|-------------------| -||empty string ("")| -||15| -||empty string ("")| -||empty string ("")| - - You can change the value for these properties only by using the property. - - - -## Examples - The following example creates and opens an . - + is created, the read/write properties are set to the following initial values unless they are specifically set using their associated keywords in the property. + +|Properties|Initial value| +|----------------|-------------------| +||empty string ("")| +||15| +||empty string ("")| +||empty string ("")| + + You can change the value for these properties only by using the property. + + + +## Examples + The following example creates and opens an . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OleDbConnection.OleDbConnection Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData OleDbConnection.OleDbConnection Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData OleDbConnection.OleDbConnection Example/VB/source.vb" id="Snippet1"::: + ]]> Connecting to Data Sources @@ -200,28 +200,28 @@ The connection used to open the database. Initializes a new instance of the class with the specified connection string. - is created, the read/write properties are set to the following initial values unless they are specifically set using their associated keywords in the property. - -|Properties|Initial value| -|----------------|-------------------| -||`connectionString`| -||15| -||empty string ("")| -||empty string ("")| - - You can change the value for these properties only by using the property. - - - -## Examples - The following example creates and opens an . - + is created, the read/write properties are set to the following initial values unless they are specifically set using their associated keywords in the property. + +|Properties|Initial value| +|----------------|-------------------| +||`connectionString`| +||15| +||empty string ("")| +||empty string ("")| + + You can change the value for these properties only by using the property. + + + +## Examples + The following example creates and opens an . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OleDbConnection.OleDbConnection1 Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData OleDbConnection.OleDbConnection1 Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData OleDbConnection.OleDbConnection1 Example/VB/source.vb" id="Snippet1"::: + ]]> Connecting to Data Sources @@ -306,19 +306,19 @@ Starts a database transaction with the current value. An object representing the new transaction. - 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. - + 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. + :::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/VS_Snippets_ADO.NET/Classic WebData OleDbConnection.BeginTransaction Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData OleDbConnection.BeginTransaction Example/VB/source.vb" id="Snippet1"::: + ]]> Parallel transactions are not supported. @@ -361,22 +361,22 @@ Starts a database transaction with the specified isolation level. An object representing the new transaction. - 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. - + 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. - - - -## Examples - The following example creates an and an . It also demonstrates how to use the , a , and methods. - +> 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. + :::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/VS_Snippets_ADO.NET/Classic WebData OleDbConnection.BeginTransaction1 Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData OleDbConnection.BeginTransaction1 Example/VB/source.vb" id="Snippet1"::: + ]]> Parallel transactions are not supported. @@ -425,19 +425,19 @@ The database name. Changes the current database for an open . - and displays some of its read-only properties. - + and displays some of its read-only properties. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OleDbConnection.Database Example/CS/source.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData OleDbConnection.Database Example/VB/source.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData OleDbConnection.Database Example/VB/source.vb" id="Snippet2"::: + ]]> The database name is not valid. @@ -485,16 +485,16 @@ Closes the connection to the data source. - 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. - + 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. + > [!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/). + ]]> Connecting to Data Sources @@ -571,65 +571,65 @@ Gets or sets the string used to open a database. The OLE DB provider connection string that includes the data source name, and other parameters needed to establish the initial connection. The default value is an empty string. - 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`. - - You can use the property to connect to a variety of data sources. The following example illustrates several possible connection strings. - -``` -"Provider=MSDAORA; Data Source=ORACLE8i7;Persist Security Info=False;Integrated Security=Yes" - -"Provider=Microsoft.Jet.OLEDB.4.0; Data Source=c:\bin\LocalAccess40.mdb" - -"Provider=SQLOLEDB;Data Source=(local);Integrated Security=SSPI" -``` - - If the `Data Source` keyword is not specified in the connection string, the provider will try to connect to the local server if one is available. - - 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 . - - 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. - + 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`. + + You can use the property to connect to a variety of data sources. The following example illustrates several possible connection strings. + +``` +"Provider=MSDAORA; Data Source=ORACLE8i7;Persist Security Info=False;Integrated Security=Yes" + +"Provider=Microsoft.Jet.OLEDB.4.0; Data Source=c:\bin\LocalAccess40.mdb" + +"Provider=SQLOLEDB;Data Source=(local);Integrated Security=SSPI" +``` + + If the `Data Source` keyword is not specified in the connection string, the provider will try to connect to the local server if one is available. + + 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 . + + 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. + > [!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. - - The basic format of a connection string includes a series of keyword/value pairs separated by semicolons. The equal sign (=) connects each keyword and its value. To include values that contain a semicolon, single-quote character, or double-quote character, the value must be enclosed in double quotation marks. If the value contains both a semicolon and a double-quote character, the value can be enclosed in single quotation marks. The single quotation mark is also useful if the value starts with a double-quote character. Conversely, the double quotation mark can be used if the value starts with a single quotation mark. If the value contains both single-quote and double-quote characters, the quotation-mark character used to enclose the value must be doubled every time it occurs within the value. - - To include preceding or trailing spaces in the string value, the value must be enclosed in either single quotation marks or double quotation marks. Any leading or trailing spaces around integer, Boolean, or enumerated values are ignored, even if enclosed in quotation marks. However, spaces within a string literal keyword or value are preserved. Single or double quotation marks may be used within a connection string without using delimiters (for example, `Data Source= my'Server` or `Data Source= my"Server`) unless a quotation-mark character is the first or last character in the value. - - To include an equal sign (=) in a keyword or value, it must be preceded by another equal sign. For example, in the hypothetical connection string - -``` -"key==word=value" -``` - - the keyword is "key=word" and the value is "value". - - If a specific keyword in a keyword=value pair occurs multiple times in a connection string, the last occurrence listed is used in the value set. - - Keywords are not case sensitive. - +> 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. + + The basic format of a connection string includes a series of keyword/value pairs separated by semicolons. The equal sign (=) connects each keyword and its value. To include values that contain a semicolon, single-quote character, or double-quote character, the value must be enclosed in double quotation marks. If the value contains both a semicolon and a double-quote character, the value can be enclosed in single quotation marks. The single quotation mark is also useful if the value starts with a double-quote character. Conversely, the double quotation mark can be used if the value starts with a single quotation mark. If the value contains both single-quote and double-quote characters, the quotation-mark character used to enclose the value must be doubled every time it occurs within the value. + + To include preceding or trailing spaces in the string value, the value must be enclosed in either single quotation marks or double quotation marks. Any leading or trailing spaces around integer, Boolean, or enumerated values are ignored, even if enclosed in quotation marks. However, spaces within a string literal keyword or value are preserved. Single or double quotation marks may be used within a connection string without using delimiters (for example, `Data Source= my'Server` or `Data Source= my"Server`) unless a quotation-mark character is the first or last character in the value. + + To include an equal sign (=) in a keyword or value, it must be preceded by another equal sign. For example, in the hypothetical connection string + +``` +"key==word=value" +``` + + the keyword is "key=word" and the value is "value". + + If a specific keyword in a keyword=value pair occurs multiple times in a connection string, the last occurrence listed is used in the value set. + + Keywords are not case sensitive. + > [!CAUTION] -> You should use caution when constructing a connection string based on user input, for example, when retrieving user ID and password information from a dialog box and appending it to the connection string. The application should make sure that a user cannot embed additional connection-string parameters in these values, for example, entering a password as "validpassword;database= somedb" in an attempt to attach to a different database. If you use the Extended Properties connection string parameter for OLE DB connections, avoid passing user IDs and passwords because you should avoid storing user IDs and passwords in clear text if you can, and because the default setting of `Persist Security Info= false` does not affect the `Extended Properties` parameter. - - - -## Examples - The following example creates an and sets some of its properties in the connection string. - +> You should use caution when constructing a connection string based on user input, for example, when retrieving user ID and password information from a dialog box and appending it to the connection string. The application should make sure that a user cannot embed additional connection-string parameters in these values, for example, entering a password as "validpassword;database= somedb" in an attempt to attach to a different database. If you use the Extended Properties connection string parameter for OLE DB connections, avoid passing user IDs and passwords because you should avoid storing user IDs and passwords in clear text if you can, and because the default setting of `Persist Security Info= false` does not affect the `Extended Properties` parameter. + + + +## Examples + The following example creates an and sets some of its properties in the connection string. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OleDbConnection.DataSource Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData OleDbConnection.DataSource Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData OleDbConnection.DataSource Example/VB/source.vb" id="Snippet1"::: + ]]> An invalid connection string argument has been supplied or a required connection string argument has not been supplied. @@ -683,19 +683,19 @@ Gets the time to wait (in seconds) while trying to establish a connection before terminating the attempt and generating an error. The time in seconds to wait for a connection to open. The default value is 15 seconds. - because an attempt to connect will wait indefinitely. - - - -## Examples - The following example creates an and sets some of its properties in the connection string. - + because an attempt to connect will wait indefinitely. + + + +## Examples + The following example creates an and sets some of its properties in the connection string. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OleDbConnection.ConnectionTimeout Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData OleDbConnection.ConnectionTimeout Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData OleDbConnection.ConnectionTimeout Example/VB/source.vb" id="Snippet1"::: + ]]> The value set is less than 0. @@ -821,19 +821,19 @@ Gets the name of the current database or the database to be used after a connection is opened. The name of the current database or the name of the database to be used after a connection is opened. The default value is an empty string. - 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. - - - -## Examples - The following example creates an and displays some of its read-only properties. - + 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. + + + +## Examples + The following example creates an and displays some of its read-only properties. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OleDbConnection.Database Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData OleDbConnection.Database Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData OleDbConnection.Database Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -890,19 +890,19 @@ Gets the server name or file name of the data source. The server name or file name of the data source. The default value is an empty string. - and displays some of its read-only properties. - + and displays some of its read-only properties. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OleDbConnection.DataSource Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData OleDbConnection.DataSource Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData OleDbConnection.DataSource Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -968,21 +968,21 @@ System.Void - + A reference to an existing in which to enlist. Enlists in the specified transaction as a distributed transaction. - 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 won't receive notice that the local transaction was rolled back and are responsible for managing any local transactions not started using . - + 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 won't receive notice that the local transaction was rolled back and are responsible for managing any local transactions not started using . + ]]> Connecting to Data Sources @@ -1028,11 +1028,11 @@ A reference to an existing in which to enlist. Enlists in the specified transaction as a distributed transaction. - 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). - + 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). + ]]> Connecting to Data Sources @@ -1082,31 +1082,31 @@ Returns schema information from a data source as indicated by a GUID, and after it applies the specified restrictions. A that contains the requested schema information. - that has the same format as the OLE DB schema rowset specified by the `schema` parameter. Use the `restrictions` parameter to filter the rows to be returned in the (for example, by specifying restrictions for table name, type, owner, or schema). When you pass values in the array, include empty strings or nulls for array elements that do not contain values. If you pass an empty array to `restrictions`, all rows (one for each table) are returned in default order. Values in the array correspond to the order of the columns in the source table and . Each element in the restrictions array is compared with the content of the corresponding column in the schema rowset. For example, the first element in the restrictions array is compared to first column in the rowset. If a restriction element is not null, only rows from the schema rowset that exactly match the value of the restriction are added to the resulting . - - The method calls the underlying OLE DB **IDBSchemaRowset::GetRowset** method using standard common language runtime conversion rules. For more information, see [COM Data Types](https://docs.microsoft.com/previous-versions/dotnet/netframework-4.0/sak564ww(v=vs.100)). - - You can retrieve information about literals by using . This provides information equivalent to calling the OLE DB **IDBInfo::GetLiteralInfo** interface, or the ADO **Connection.OpenSchema** method with the `adSchemaDBInfoLiterals` constant. - - - -## Examples - The following sample returns a list of tables in a database. - + that has the same format as the OLE DB schema rowset specified by the `schema` parameter. Use the `restrictions` parameter to filter the rows to be returned in the (for example, by specifying restrictions for table name, type, owner, or schema). When you pass values in the array, include empty strings or nulls for array elements that do not contain values. If you pass an empty array to `restrictions`, all rows (one for each table) are returned in default order. Values in the array correspond to the order of the columns in the source table and . Each element in the restrictions array is compared with the content of the corresponding column in the schema rowset. For example, the first element in the restrictions array is compared to first column in the rowset. If a restriction element is not null, only rows from the schema rowset that exactly match the value of the restriction are added to the resulting . + + The method calls the underlying OLE DB **IDBSchemaRowset::GetRowset** method using standard common language runtime conversion rules. For more information, see [COM Data Types](https://docs.microsoft.com/previous-versions/dotnet/netframework-4.0/sak564ww(v=vs.100)). + + You can retrieve information about literals by using . This provides information equivalent to calling the OLE DB **IDBInfo::GetLiteralInfo** interface, or the ADO **Connection.OpenSchema** method with the `adSchemaDBInfoLiterals` constant. + + + +## Examples + The following sample returns a list of tables in a database. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OleDbConnection.GetOleDbSchemaTable Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData OleDbConnection.GetOleDbSchemaTable Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData OleDbConnection.GetOleDbSchemaTable Example/VB/source.vb" id="Snippet1"::: + ]]> The specified set of restrictions is invalid. The is closed. - The specified schema rowset is not supported by the OLE DB provider. - - -or- - + The specified schema rowset is not supported by the OLE DB provider. + + -or- + The parameter contains a value of and the parameter contains one or more restrictions. Connecting to Data Sources @@ -1189,11 +1189,11 @@ Returns schema information for the data source of this using the specified string for the schema name. A that contains schema information. - will contain information about all the metadata that is available, and its restrictions. - + will contain information about all the metadata that is available, and its restrictions. + ]]> Obtaining Schema Information from a Database @@ -1243,15 +1243,15 @@ Returns schema information for the data source of this using the specified string for the schema name and the specified string array for the restriction values. A that contains schema information. - will contain information about all the metadata that is available, and its restrictions. - - The `restrictionValues` parameter can supply *n* depth of values which are specified by the restrictions collection for a specific collection. In order to set values on a given restriction, and not set the values of other restrictions, you need to set the preceding restrictions to null and then put the appropriate value in for the restriction that you would like to specify a value for. - - 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 must 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 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. - + will contain information about all the metadata that is available, and its restrictions. + + The `restrictionValues` parameter can supply *n* depth of values which are specified by the restrictions collection for a specific collection. In order to set values on a given restriction, and not set the values of other restrictions, you need to set the preceding restrictions to null and then put the appropriate value in for the restriction that you would like to specify a value for. + + 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 must 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 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. + ]]> Obtaining Schema Information from a Database @@ -1306,15 +1306,15 @@ Occurs when the provider sends a warning or an informational message. - delegate to listen to this event. - - The event occurs when a message with low severity is returned from the data source. Low severity messages are those that do not cause an exception. For Microsoft SQL Server, this includes error messages that have a severity of 10 or less - - For more information and an example, see [Connection Events](/dotnet/framework/data/adonet/connection-events). - + delegate to listen to this event. + + The event occurs when a message with low severity is returned from the data source. Low severity messages are those that do not cause an exception. For Microsoft SQL Server, this includes error messages that have a severity of 10 or less + + For more information and an example, see [Connection Events](/dotnet/framework/data/adonet/connection-events). + ]]> @@ -1358,14 +1358,14 @@ Opens a database connection with the property settings specified by 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. - + 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. + ]]> The connection is already open. @@ -1418,14 +1418,14 @@ Gets the name of the OLE DB provider specified in the "Provider= " clause of the connection string. The name of the provider as specified in the "Provider= " clause of the connection string. The default value is an empty string. - and displays some of its read-only properties. - + and displays some of its read-only properties. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OleDbConnection.Provider Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData OleDbConnection.Provider Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData OleDbConnection.Provider Example/VB/source.vb" id="Snippet1"::: + ]]> Connecting to Data Sources @@ -1462,31 +1462,31 @@ Indicates that the object pool can be released when the last underlying connection is released. - objects. You might want to call this method if, for example, the connection object will not be used again for the amount of time that OLE DB services ordinarily keeps pooled connections active. Note that calling the method alone does not actually release the active connections that exist in the pool. - - The following must occur before the pool is finally disposed: - -1. Call to return the connection object to the pool. - -2. Allow each connection object to time out of the pool. - -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. - - - -## Examples - The following example creates an , opens it, displays some of its properties, closes the connection, and releases the object pool to conserve resources. - + objects. You might want to call this method if, for example, the connection object will not be used again for the amount of time that OLE DB services ordinarily keeps pooled connections active. Note that calling the method alone does not actually release the active connections that exist in the pool. + + The following must occur before the pool is finally disposed: + +1. Call to return the connection object to the pool. + +2. Allow each connection object to time out of the pool. + +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. + + + +## Examples + The following example creates an , opens it, displays some of its properties, closes the connection, and releases the object pool to conserve resources. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OleDbConnection.ReleaseObjectPool Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData OleDbConnection.ReleaseObjectPool Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData OleDbConnection.ReleaseObjectPool Example/VB/source.vb" id="Snippet1"::: + ]]> Connecting to Data Sources @@ -1529,11 +1529,11 @@ Updates the property of the object. - , 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. - + , 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. + ]]> Connecting to Data Sources @@ -1587,21 +1587,21 @@ Gets a string that contains the version of the server to which the client is connected. The version of the connected server. - 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. - - - -## Examples - The following example creates an and displays some of its read-only properties. - + 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. + + + +## Examples + The following example creates an and displays some of its read-only properties. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OleDbConnection.ServerVersion Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData OleDbConnection.ServerVersion Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData OleDbConnection.ServerVersion Example/VB/source.vb" id="Snippet1"::: + ]]> The connection is closed. @@ -1659,18 +1659,18 @@ Gets the current state of the connection. A bitwise combination of the values. The default is Closed. - method of the object. - -- From `Open` to `Closed`, using either the method or the **Dispose** method of the object. - + method of the object. + +- From `Open` to `Closed`, using either the method or the **Dispose** method of the object. + > [!NOTE] -> In previous version of the .NET Framework, calling the property increased application overhead because each call caused a call to the OLE DB DBPROP_CONNECTIONSTATUS property for an open connection. With the release of the .NET Framework 2.0, this is no longer an issue. - +> In previous version of the .NET Framework, calling the property increased application overhead because each call caused a call to the OLE DB DBPROP_CONNECTIONSTATUS property for an open connection. With the release of the .NET Framework 2.0, this is no longer an issue. + ]]> Connecting to Data Sources @@ -1838,11 +1838,11 @@ This member is an explicit interface member implementation. It can be used only For a description of this member, see . A new that is a copy of this instance. - instance is cast to an interface. - + instance is cast to an interface. + ]]> diff --git a/xml/System.Data.OleDb/OleDbConnectionStringBuilder.xml b/xml/System.Data.OleDb/OleDbConnectionStringBuilder.xml index 9a250d1c609..efcf63c5443 100644 --- a/xml/System.Data.OleDb/OleDbConnectionStringBuilder.xml +++ b/xml/System.Data.OleDb/OleDbConnectionStringBuilder.xml @@ -453,7 +453,7 @@ Provider=Microsoft.Jet.OLEDB.4.0;Data Source=C:\Sample.mdb;User ID="Admin;NewVal System.Void - + To be added. diff --git a/xml/System.Data.OleDb/OleDbFactory.xml b/xml/System.Data.OleDb/OleDbFactory.xml index 836ddd46fd7..27591df83d3 100644 --- a/xml/System.Data.OleDb/OleDbFactory.xml +++ b/xml/System.Data.OleDb/OleDbFactory.xml @@ -70,21 +70,21 @@ Returns a strongly-typed instance. A new strongly-typed instance of . - instance: - -```vb -Dim newFactory As OleDbFactory = OleDbFactory.Instance -Dim cmd As DbCommand = newFactory.CreateCommand() -``` - -```csharp -OleDbFactory newFactory = OleDbFactory.Instance; -DbCommand cmd = newFactory.CreateCommand(); -``` - + instance: + +```vb +Dim newFactory As OleDbFactory = OleDbFactory.Instance +Dim cmd As DbCommand = newFactory.CreateCommand() +``` + +```csharp +OleDbFactory newFactory = OleDbFactory.Instance; +DbCommand cmd = newFactory.CreateCommand(); +``` + ]]> @@ -120,21 +120,21 @@ DbCommand cmd = newFactory.CreateCommand(); Returns a strongly-typed instance. A new strongly-typed instance of . - instance: - -```vb -Dim newFactory As OleDbFactory = OleDbFactory.Instance -Dim cmd As DbCommandBuilder = newFactory.CreateCommandBuilder() -``` - -```csharp -OleDbFactory newFactory = OleDbFactory.Instance; -DbCommandBuilder cmd = newFactory.CreateCommandBuilder(); -``` - + instance: + +```vb +Dim newFactory As OleDbFactory = OleDbFactory.Instance +Dim cmd As DbCommandBuilder = newFactory.CreateCommandBuilder() +``` + +```csharp +OleDbFactory newFactory = OleDbFactory.Instance; +DbCommandBuilder cmd = newFactory.CreateCommandBuilder(); +``` + ]]> @@ -170,21 +170,21 @@ DbCommandBuilder cmd = newFactory.CreateCommandBuilder(); Returns a strongly-typed instance. A new strongly-typed instance of . - instance: - -```vb -Dim newFactory As OleDbFactory = OleDbFactory.Instance -Dim cmd As DbConnection = newFactory.CreateConnection() -``` - -```csharp -OleDbFactory newFactory = OleDbFactory.Instance; -DbConnection cmd = newFactory.CreateConnection(); -``` - + instance: + +```vb +Dim newFactory As OleDbFactory = OleDbFactory.Instance +Dim cmd As DbConnection = newFactory.CreateConnection() +``` + +```csharp +OleDbFactory newFactory = OleDbFactory.Instance; +DbConnection cmd = newFactory.CreateConnection(); +``` + ]]> @@ -220,21 +220,21 @@ DbConnection cmd = newFactory.CreateConnection(); Returns a strongly-typed instance. A new strongly-typed instance of . - instance: - -```vb -Dim newFactory As OleDbFactory = OleDbFactory.Instance -Dim cmd As DbConnectionStringBuilder = newFactory.CreateConnectionStringBuilder() -``` - -```csharp -OleDbFactory newFactory = OleDbFactory.Instance; -DbConnectionStringBuilder cmd = newFactory.CreateConnectionStringBuilder(); -``` - + instance: + +```vb +Dim newFactory As OleDbFactory = OleDbFactory.Instance +Dim cmd As DbConnectionStringBuilder = newFactory.CreateConnectionStringBuilder() +``` + +```csharp +OleDbFactory newFactory = OleDbFactory.Instance; +DbConnectionStringBuilder cmd = newFactory.CreateConnectionStringBuilder(); +``` + ]]> @@ -270,21 +270,21 @@ DbConnectionStringBuilder cmd = newFactory.CreateConnectionStringBuilder(); Returns a strongly-typed instance. A new strongly-typed instance of . - instance: - -```vb -Dim newFactory As OleDbFactory = OleDbFactory.Instance -Dim cmd As DbDataAdapter = newFactory.CreateDataAdapter() -``` - -```csharp -OleDbFactory newFactory = OleDbFactory.Instance; -DbDataAdapter cmd = newFactory.CreateDataAdapter(); -``` - + instance: + +```vb +Dim newFactory As OleDbFactory = OleDbFactory.Instance +Dim cmd As DbDataAdapter = newFactory.CreateDataAdapter() +``` + +```csharp +OleDbFactory newFactory = OleDbFactory.Instance; +DbDataAdapter cmd = newFactory.CreateDataAdapter(); +``` + ]]> @@ -320,21 +320,21 @@ DbDataAdapter cmd = newFactory.CreateDataAdapter(); Returns a strongly-typed instance. A new strongly-typed instance of . - instance: - -```vb -Dim newFactory As OleDbFactory = OleDbFactory.Instance -Dim cmd As DbParameter = newFactory.CreateParameter() -``` - -```csharp -OleDbFactory newFactory = OleDbFactory.Instance; -DbParameter cmd = newFactory.CreateParameter(); -``` - + instance: + +```vb +Dim newFactory As OleDbFactory = OleDbFactory.Instance +Dim cmd As DbParameter = newFactory.CreateParameter() +``` + +```csharp +OleDbFactory newFactory = OleDbFactory.Instance; +DbParameter cmd = newFactory.CreateParameter(); +``` + ]]> @@ -359,7 +359,7 @@ DbParameter cmd = newFactory.CreateParameter(); System.Security.CodeAccessPermission - + A member of the enumeration. @@ -397,21 +397,21 @@ DbParameter cmd = newFactory.CreateParameter(); Gets an instance of the . This can be used to retrieve strongly-typed data objects. - field to retrieve an instance, and then return a strongly-typed instance: - -```vb -Dim newFactory As OleDbFactory = OleDbFactory.Instance -Dim cmd As DbCommand = newFactory.CreateCommand() -``` - -```csharp -OleDbFactory newFactory = OleDbFactory.Instance; -DbCommand cmd = newFactory.CreateCommand(); -``` - + field to retrieve an instance, and then return a strongly-typed instance: + +```vb +Dim newFactory As OleDbFactory = OleDbFactory.Instance +Dim cmd As DbCommand = newFactory.CreateCommand() +``` + +```csharp +OleDbFactory newFactory = OleDbFactory.Instance; +DbCommand cmd = newFactory.CreateCommand(); +``` + ]]> diff --git a/xml/System.Data.SqlClient/SqlClientFactory.xml b/xml/System.Data.SqlClient/SqlClientFactory.xml index dee38e0fcb1..07d9a96bfec 100644 --- a/xml/System.Data.SqlClient/SqlClientFactory.xml +++ b/xml/System.Data.SqlClient/SqlClientFactory.xml @@ -69,19 +69,19 @@ if a can be created; otherwise, . - class provides the property so that inheritors can indicate whether they can provide a data source enumerator. The displays this property, but its value is always `true`. - - - -## Examples - The following example displays a list of all available SQL Server data sources, using code that could enumerate data sources for any provider. - + class provides the property so that inheritors can indicate whether they can provide a data source enumerator. The displays this property, but its value is always `true`. + + + +## Examples + The following example displays a list of all available SQL Server data sources, using code that could enumerate data sources for any provider. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks SqlClientFactory.DataSourceEnumerator/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/DataWorks SqlClientFactory.DataSourceEnumerator/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/DataWorks SqlClientFactory.DataSourceEnumerator/VB/source.vb" id="Snippet1"::: + ]]> ADO.NET Overview @@ -123,21 +123,21 @@ Returns a strongly typed instance. A new strongly typed instance of . - instance: - -```vb -Dim newFactory As SqlClientFactory = SqlClientFactory.Instance -Dim cmd As DbCommand = newFactory.CreateCommand() -``` - -```csharp -SqlClientFactory newFactory = SqlClientFactory.Instance; -DbCommand cmd = newFactory.CreateCommand(); -``` - + instance: + +```vb +Dim newFactory As SqlClientFactory = SqlClientFactory.Instance +Dim cmd As DbCommand = newFactory.CreateCommand() +``` + +```csharp +SqlClientFactory newFactory = SqlClientFactory.Instance; +DbCommand cmd = newFactory.CreateCommand(); +``` + ]]> ADO.NET Overview @@ -174,21 +174,21 @@ DbCommand cmd = newFactory.CreateCommand(); Returns a strongly typed instance. A new strongly typed instance of . - instance: - -```vb -Dim newFactory As SqlClientFactory = SqlClientFactory.Instance -Dim cmd As DbCommandBuilder = newFactory.CreateCommandBuilder() -``` - -```csharp -SqlClientFactory newFactory = SqlClientFactory.Instance; -DbCommandBuilder cmd = newFactory.CreateCommandBuilder(); -``` - + instance: + +```vb +Dim newFactory As SqlClientFactory = SqlClientFactory.Instance +Dim cmd As DbCommandBuilder = newFactory.CreateCommandBuilder() +``` + +```csharp +SqlClientFactory newFactory = SqlClientFactory.Instance; +DbCommandBuilder cmd = newFactory.CreateCommandBuilder(); +``` + ]]> ADO.NET Overview @@ -230,22 +230,22 @@ DbCommandBuilder cmd = newFactory.CreateCommandBuilder(); Returns a strongly typed instance. A new strongly typed instance of . - instance: - -```vb -Dim newFactory As SqlClientFactory = SqlClientFactory.Instance -Dim cmd As DbConnection = newFactory.CreateConnection() -``` - -```csharp -SqlClientFactory newFactory = SqlClientFactory.Instance; -DbConnection cmd = newFactory.CreateConnection(); - -``` - + instance: + +```vb +Dim newFactory As SqlClientFactory = SqlClientFactory.Instance +Dim cmd As DbConnection = newFactory.CreateConnection() +``` + +```csharp +SqlClientFactory newFactory = SqlClientFactory.Instance; +DbConnection cmd = newFactory.CreateConnection(); + +``` + ]]> ADO.NET Overview @@ -287,23 +287,23 @@ DbConnection cmd = newFactory.CreateConnection(); Returns a strongly typed instance. A new strongly typed instance of . - instance: - -```vb -Dim newFactory As SqlClientFactory = SqlClientFactory.Instance -Dim cmd As DbConnectionStringBuilder = _ - newFactory.CreateConnectionStringBuilder() -``` - -```csharp -SqlClientFactory newFactory = SqlClientFactory.Instance; -DbConnectionStringBuilder cmd = - newFactory.CreateConnectionStringBuilder(); -``` - + instance: + +```vb +Dim newFactory As SqlClientFactory = SqlClientFactory.Instance +Dim cmd As DbConnectionStringBuilder = _ + newFactory.CreateConnectionStringBuilder() +``` + +```csharp +SqlClientFactory newFactory = SqlClientFactory.Instance; +DbConnectionStringBuilder cmd = + newFactory.CreateConnectionStringBuilder(); +``` + ]]> ADO.NET Overview @@ -340,21 +340,21 @@ DbConnectionStringBuilder cmd = Returns a strongly typed instance. A new strongly typed instance of . - instance: - -```vb -Dim newFactory As SqlClientFactory = SqlClientFactory.Instance -Dim cmd As DbDataAdapter = newFactory.CreateDataAdapter() -``` - -```csharp -SqlClientFactory newFactory = SqlClientFactory.Instance; -DbDataAdapter cmd = newFactory.CreateDataAdapter(); -``` - + instance: + +```vb +Dim newFactory As SqlClientFactory = SqlClientFactory.Instance +Dim cmd As DbDataAdapter = newFactory.CreateDataAdapter() +``` + +```csharp +SqlClientFactory newFactory = SqlClientFactory.Instance; +DbDataAdapter cmd = newFactory.CreateDataAdapter(); +``` + ]]> ADO.NET Overview @@ -384,14 +384,14 @@ DbDataAdapter cmd = newFactory.CreateDataAdapter(); Returns a new . A new data source enumerator. - ADO.NET Overview @@ -433,21 +433,21 @@ DbDataAdapter cmd = newFactory.CreateDataAdapter(); Returns a strongly typed instance. A new strongly typed instance of . - instance: - -```vb -Dim newFactory As SqlClientFactory = SqlClientFactory.Instance -Dim cmd As DbParameter = newFactory.CreateParameter() -``` - -```csharp -SqlClientFactory newFactory = SqlClientFactory.Instance; -DbParameter cmd = newFactory.CreateParameter(); -``` - + instance: + +```vb +Dim newFactory As SqlClientFactory = SqlClientFactory.Instance +Dim cmd As DbParameter = newFactory.CreateParameter() +``` + +```csharp +SqlClientFactory newFactory = SqlClientFactory.Instance; +DbParameter cmd = newFactory.CreateParameter(); +``` + ]]> ADO.NET Overview @@ -473,7 +473,7 @@ DbParameter cmd = newFactory.CreateParameter(); System.Security.CodeAccessPermission - + A member of the enumeration. @@ -517,21 +517,21 @@ DbParameter cmd = newFactory.CreateParameter(); Gets an instance of the . This can be used to retrieve strongly typed data objects. - property to retrieve a **SqlClientFactory** instance, and then return a strongly typed instance: - -```vb -Dim newFactory As SqlClientFactory = SqlClientFactory.Instance -Dim cmd As DbCommand = newFactory.CreateCommand() -``` - -```csharp -SqlClientFactory newFactory = SqlClientFactory.Instance; -DbCommand cmd = newFactory.CreateCommand(); -``` - + property to retrieve a **SqlClientFactory** instance, and then return a strongly typed instance: + +```vb +Dim newFactory As SqlClientFactory = SqlClientFactory.Instance +Dim cmd As DbCommand = newFactory.CreateCommand() +``` + +```csharp +SqlClientFactory newFactory = SqlClientFactory.Instance; +DbCommand cmd = newFactory.CreateCommand(); +``` + ]]> ADO.NET Overview diff --git a/xml/System.Data.SqlClient/SqlCommand.xml b/xml/System.Data.SqlClient/SqlCommand.xml index 7d732f74001..4a6a63ddcca 100644 --- a/xml/System.Data.SqlClient/SqlCommand.xml +++ b/xml/System.Data.SqlClient/SqlCommand.xml @@ -77,358 +77,358 @@ Represents a Transact-SQL statement or stored procedure to execute against a SQL Server database. This class cannot be inherited. - is created, the read/write properties are set to their initial values. For a list of these values, see the constructor. - - features the following methods for executing commands at a SQL Server database: - -|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.| - - You can reset the property and reuse the object. However, you must close the before you can execute a new or previous command. - - If a is generated by the method executing a , the remains open when the severity level is 19 or less. When the severity level is 20 or greater, the server ordinarily closes the . However, the user can reopen the connection and continue. - + is created, the read/write properties are set to their initial values. For a list of these values, see the constructor. + + features the following methods for executing commands at a SQL Server database: + +|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.| + + You can reset the property and reuse the object. However, you must close the before you can execute a new or previous command. + + If a is generated by the method executing a , the remains open when the severity level is 19 or less. When the severity level is 20 or greater, the server ordinarily closes the . However, the user can reopen the connection and continue. + > [!NOTE] -> Nameless, also called ordinal, parameters are not supported by the .NET Framework Data Provider for SQL Server. - - - -## Examples - The following example creates a , a , and a . The example reads through the data, writing it to the console. Finally, the example closes the and then the as it exits the `Using` code blocks. - +> Nameless, also called ordinal, parameters are not supported by the .NET Framework Data Provider for SQL Server. + + + +## Examples + The following example creates a , a , and a . The example reads through the data, writing it to the console. Finally, the example closes the and then the as it exits the `Using` code blocks. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData SqlCommand Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData SqlCommand Example/VB/source.vb" id="Snippet1"::: - - The following sample shows how to create and execute different types of SqlCommand objects. - - First you must create the sample database, by executing the following script: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData SqlCommand Example/VB/source.vb" id="Snippet1"::: + + The following sample shows how to create and execute different types of SqlCommand objects. + + First you must create the sample database, by executing the following script: + ```sql -USE [master] -GO - -CREATE DATABASE [MySchool] -GO - -USE [MySchool] -GO - -SET ANSI_NULLS ON -GO -SET QUOTED_IDENTIFIER ON -GO -CREATE procedure [dbo].[CourseExtInfo] @CourseId int -as -select c.CourseID,c.Title,c.Credits,d.Name as DepartmentName -from Course as c left outer join Department as d on c.DepartmentID=d.DepartmentID -where c.CourseID=@CourseId - -GO - -SET ANSI_NULLS ON -GO -SET QUOTED_IDENTIFIER ON -GO -create procedure [dbo].[DepartmentInfo] @DepartmentId int,@CourseCount int output -as -select @CourseCount=Count(c.CourseID) -from course as c -where c.DepartmentID=@DepartmentId - -select d.DepartmentID,d.Name,d.Budget,d.StartDate,d.Administrator -from Department as d -where d.DepartmentID=@DepartmentId - -GO - -SET ANSI_NULLS ON -GO -SET QUOTED_IDENTIFIER ON -GO -Create PROCEDURE [dbo].[GetDepartmentsOfSpecifiedYear] -@Year int,@BudgetSum money output -AS -BEGIN - SELECT @BudgetSum=SUM([Budget]) - FROM [MySchool].[dbo].[Department] - Where YEAR([StartDate])=@Year - -SELECT [DepartmentID] - ,[Name] - ,[Budget] - ,[StartDate] - ,[Administrator] - FROM [MySchool].[dbo].[Department] - Where YEAR([StartDate])=@Year - -END -GO - -SET ANSI_NULLS ON -GO -SET QUOTED_IDENTIFIER ON -GO -CREATE TABLE [dbo].[Course]([CourseID] [nvarchar](10) NOT NULL, -[Year] [smallint] NOT NULL, -[Title] [nvarchar](100) NOT NULL, -[Credits] [int] NOT NULL, -[DepartmentID] [int] NOT NULL, - CONSTRAINT [PK_Course] PRIMARY KEY CLUSTERED -( -[CourseID] ASC, -[Year] ASC -)WITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, IGNORE_DUP_KEY = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON) ON [PRIMARY]) ON [PRIMARY] - -GO - -SET ANSI_NULLS ON -GO -SET QUOTED_IDENTIFIER ON -GO -CREATE TABLE [dbo].[Department]([DepartmentID] [int] IDENTITY(1,1) NOT NULL, -[Name] [nvarchar](50) NOT NULL, -[Budget] [money] NOT NULL, -[StartDate] [datetime] NOT NULL, -[Administrator] [int] NULL, - CONSTRAINT [PK_Department] PRIMARY KEY CLUSTERED -( -[DepartmentID] ASC -)WITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, IGNORE_DUP_KEY = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON) ON [PRIMARY]) ON [PRIMARY] - -GO - -SET ANSI_NULLS ON -GO -SET QUOTED_IDENTIFIER ON -GO -CREATE TABLE [dbo].[Person]([PersonID] [int] IDENTITY(1,1) NOT NULL, -[LastName] [nvarchar](50) NOT NULL, -[FirstName] [nvarchar](50) NOT NULL, -[HireDate] [datetime] NULL, -[EnrollmentDate] [datetime] NULL, - CONSTRAINT [PK_School.Student] PRIMARY KEY CLUSTERED -( -[PersonID] ASC -)WITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, IGNORE_DUP_KEY = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON) ON [PRIMARY]) ON [PRIMARY] - -GO - -SET ANSI_NULLS ON -GO -SET QUOTED_IDENTIFIER ON -GO -CREATE TABLE [dbo].[StudentGrade]([EnrollmentID] [int] IDENTITY(1,1) NOT NULL, -[CourseID] [nvarchar](10) NOT NULL, -[StudentID] [int] NOT NULL, -[Grade] [decimal](3, 2) NOT NULL, - CONSTRAINT [PK_StudentGrade] PRIMARY KEY CLUSTERED -( -[EnrollmentID] ASC -)WITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, IGNORE_DUP_KEY = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON) ON [PRIMARY]) ON [PRIMARY] - -GO - -SET ANSI_NULLS ON -GO -SET QUOTED_IDENTIFIER ON -GO -create view [dbo].[EnglishCourse] -as -select c.CourseID,c.Title,c.Credits,c.DepartmentID -from Course as c join Department as d on c.DepartmentID=d.DepartmentID -where d.Name=N'English' - -GO -INSERT [dbo].[Course] ([CourseID], [Year], [Title], [Credits], [DepartmentID]) VALUES (N'C1045', 2012, N'Calculus', 4, 7) -INSERT [dbo].[Course] ([CourseID], [Year], [Title], [Credits], [DepartmentID]) VALUES (N'C1061', 2012, N'Physics', 4, 1) -INSERT [dbo].[Course] ([CourseID], [Year], [Title], [Credits], [DepartmentID]) VALUES (N'C2021', 2012, N'Composition', 3, 2) -INSERT [dbo].[Course] ([CourseID], [Year], [Title], [Credits], [DepartmentID]) VALUES (N'C2042', 2012, N'Literature', 4, 2) -SET IDENTITY_INSERT [dbo].[Department] ON - -INSERT [dbo].[Department] ([DepartmentID], [Name], [Budget], [StartDate], [Administrator]) VALUES (1, N'Engineering', 350000.0000, CAST(0x0000999C00000000 AS DateTime), 2) -INSERT [dbo].[Department] ([DepartmentID], [Name], [Budget], [StartDate], [Administrator]) VALUES (2, N'English', 120000.0000, CAST(0x0000999C00000000 AS DateTime), 6) -INSERT [dbo].[Department] ([DepartmentID], [Name], [Budget], [StartDate], [Administrator]) VALUES (4, N'Economics', 200000.0000, CAST(0x0000999C00000000 AS DateTime), 4) -INSERT [dbo].[Department] ([DepartmentID], [Name], [Budget], [StartDate], [Administrator]) VALUES (7, N'Mathematics', 250024.0000, CAST(0x0000999C00000000 AS DateTime), 3) -SET IDENTITY_INSERT [dbo].[Department] OFF -SET IDENTITY_INSERT [dbo].[Person] ON - -INSERT [dbo].[Person] ([PersonID], [LastName], [FirstName], [HireDate], [EnrollmentDate]) VALUES (1, N'Hu', N'Nan', NULL, CAST(0x0000A0BF00000000 AS DateTime)) -INSERT [dbo].[Person] ([PersonID], [LastName], [FirstName], [HireDate], [EnrollmentDate]) VALUES (2, N'Norman', N'Laura', NULL, CAST(0x0000A0BF00000000 AS DateTime)) -INSERT [dbo].[Person] ([PersonID], [LastName], [FirstName], [HireDate], [EnrollmentDate]) VALUES (3, N'Olivotto', N'Nino', NULL, CAST(0x0000A0BF00000000 AS DateTime)) -INSERT [dbo].[Person] ([PersonID], [LastName], [FirstName], [HireDate], [EnrollmentDate]) VALUES (4, N'Anand', N'Arturo', NULL, CAST(0x0000A0BF00000000 AS DateTime)) -INSERT [dbo].[Person] ([PersonID], [LastName], [FirstName], [HireDate], [EnrollmentDate]) VALUES (5, N'Jai', N'Damien', NULL, CAST(0x0000A0BF00000000 AS DateTime)) -INSERT [dbo].[Person] ([PersonID], [LastName], [FirstName], [HireDate], [EnrollmentDate]) VALUES (6, N'Holt', N'Roger', CAST(0x000097F100000000 AS DateTime), NULL) -INSERT [dbo].[Person] ([PersonID], [LastName], [FirstName], [HireDate], [EnrollmentDate]) VALUES (7, N'Martin', N'Randall', CAST(0x00008B1A00000000 AS DateTime), NULL) -SET IDENTITY_INSERT [dbo].[Person] OFF -SET IDENTITY_INSERT [dbo].[StudentGrade] ON - -INSERT [dbo].[StudentGrade] ([EnrollmentID], [CourseID], [StudentID], [Grade]) VALUES (1, N'C1045', 1, CAST(3.50 AS Decimal(3, 2))) -INSERT [dbo].[StudentGrade] ([EnrollmentID], [CourseID], [StudentID], [Grade]) VALUES (2, N'C1045', 2, CAST(3.00 AS Decimal(3, 2))) -INSERT [dbo].[StudentGrade] ([EnrollmentID], [CourseID], [StudentID], [Grade]) VALUES (3, N'C1045', 3, CAST(2.50 AS Decimal(3, 2))) -INSERT [dbo].[StudentGrade] ([EnrollmentID], [CourseID], [StudentID], [Grade]) VALUES (4, N'C1045', 4, CAST(4.00 AS Decimal(3, 2))) -INSERT [dbo].[StudentGrade] ([EnrollmentID], [CourseID], [StudentID], [Grade]) VALUES (5, N'C1045', 5, CAST(3.50 AS Decimal(3, 2))) -INSERT [dbo].[StudentGrade] ([EnrollmentID], [CourseID], [StudentID], [Grade]) VALUES (6, N'C1061', 1, CAST(4.00 AS Decimal(3, 2))) -INSERT [dbo].[StudentGrade] ([EnrollmentID], [CourseID], [StudentID], [Grade]) VALUES (7, N'C1061', 3, CAST(3.50 AS Decimal(3, 2))) -INSERT [dbo].[StudentGrade] ([EnrollmentID], [CourseID], [StudentID], [Grade]) VALUES (8, N'C1061', 4, CAST(2.50 AS Decimal(3, 2))) -INSERT [dbo].[StudentGrade] ([EnrollmentID], [CourseID], [StudentID], [Grade]) VALUES (9, N'C1061', 5, CAST(1.50 AS Decimal(3, 2))) -INSERT [dbo].[StudentGrade] ([EnrollmentID], [CourseID], [StudentID], [Grade]) VALUES (10, N'C2021', 1, CAST(2.50 AS Decimal(3, 2))) -INSERT [dbo].[StudentGrade] ([EnrollmentID], [CourseID], [StudentID], [Grade]) VALUES (11, N'C2021', 2, CAST(3.50 AS Decimal(3, 2))) -INSERT [dbo].[StudentGrade] ([EnrollmentID], [CourseID], [StudentID], [Grade]) VALUES (12, N'C2021', 4, CAST(3.00 AS Decimal(3, 2))) -INSERT [dbo].[StudentGrade] ([EnrollmentID], [CourseID], [StudentID], [Grade]) VALUES (13, N'C2021', 5, CAST(3.00 AS Decimal(3, 2))) -INSERT [dbo].[StudentGrade] ([EnrollmentID], [CourseID], [StudentID], [Grade]) VALUES (14, N'C2042', 1, CAST(2.00 AS Decimal(3, 2))) -INSERT [dbo].[StudentGrade] ([EnrollmentID], [CourseID], [StudentID], [Grade]) VALUES (15, N'C2042', 2, CAST(3.50 AS Decimal(3, 2))) -INSERT [dbo].[StudentGrade] ([EnrollmentID], [CourseID], [StudentID], [Grade]) VALUES (16, N'C2042', 3, CAST(4.00 AS Decimal(3, 2))) -INSERT [dbo].[StudentGrade] ([EnrollmentID], [CourseID], [StudentID], [Grade]) VALUES (17, N'C2042', 5, CAST(3.00 AS Decimal(3, 2))) -SET IDENTITY_INSERT [dbo].[StudentGrade] OFF -ALTER TABLE [dbo].[Course] WITH CHECK ADD CONSTRAINT [FK_Course_Department] FOREIGN KEY([DepartmentID]) -REFERENCES [dbo].[Department] ([DepartmentID]) -GO -ALTER TABLE [dbo].[Course] CHECK CONSTRAINT [FK_Course_Department] -GO -ALTER TABLE [dbo].[StudentGrade] WITH CHECK ADD CONSTRAINT [FK_StudentGrade_Student] FOREIGN KEY([StudentID]) -REFERENCES [dbo].[Person] ([PersonID]) -GO -ALTER TABLE [dbo].[StudentGrade] CHECK CONSTRAINT [FK_StudentGrade_Student] -GO -``` - - Next, compile and execute the following: - +USE [master] +GO + +CREATE DATABASE [MySchool] +GO + +USE [MySchool] +GO + +SET ANSI_NULLS ON +GO +SET QUOTED_IDENTIFIER ON +GO +CREATE procedure [dbo].[CourseExtInfo] @CourseId int +as +select c.CourseID,c.Title,c.Credits,d.Name as DepartmentName +from Course as c left outer join Department as d on c.DepartmentID=d.DepartmentID +where c.CourseID=@CourseId + +GO + +SET ANSI_NULLS ON +GO +SET QUOTED_IDENTIFIER ON +GO +create procedure [dbo].[DepartmentInfo] @DepartmentId int,@CourseCount int output +as +select @CourseCount=Count(c.CourseID) +from course as c +where c.DepartmentID=@DepartmentId + +select d.DepartmentID,d.Name,d.Budget,d.StartDate,d.Administrator +from Department as d +where d.DepartmentID=@DepartmentId + +GO + +SET ANSI_NULLS ON +GO +SET QUOTED_IDENTIFIER ON +GO +Create PROCEDURE [dbo].[GetDepartmentsOfSpecifiedYear] +@Year int,@BudgetSum money output +AS +BEGIN + SELECT @BudgetSum=SUM([Budget]) + FROM [MySchool].[dbo].[Department] + Where YEAR([StartDate])=@Year + +SELECT [DepartmentID] + ,[Name] + ,[Budget] + ,[StartDate] + ,[Administrator] + FROM [MySchool].[dbo].[Department] + Where YEAR([StartDate])=@Year + +END +GO + +SET ANSI_NULLS ON +GO +SET QUOTED_IDENTIFIER ON +GO +CREATE TABLE [dbo].[Course]([CourseID] [nvarchar](10) NOT NULL, +[Year] [smallint] NOT NULL, +[Title] [nvarchar](100) NOT NULL, +[Credits] [int] NOT NULL, +[DepartmentID] [int] NOT NULL, + CONSTRAINT [PK_Course] PRIMARY KEY CLUSTERED +( +[CourseID] ASC, +[Year] ASC +)WITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, IGNORE_DUP_KEY = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON) ON [PRIMARY]) ON [PRIMARY] + +GO + +SET ANSI_NULLS ON +GO +SET QUOTED_IDENTIFIER ON +GO +CREATE TABLE [dbo].[Department]([DepartmentID] [int] IDENTITY(1,1) NOT NULL, +[Name] [nvarchar](50) NOT NULL, +[Budget] [money] NOT NULL, +[StartDate] [datetime] NOT NULL, +[Administrator] [int] NULL, + CONSTRAINT [PK_Department] PRIMARY KEY CLUSTERED +( +[DepartmentID] ASC +)WITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, IGNORE_DUP_KEY = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON) ON [PRIMARY]) ON [PRIMARY] + +GO + +SET ANSI_NULLS ON +GO +SET QUOTED_IDENTIFIER ON +GO +CREATE TABLE [dbo].[Person]([PersonID] [int] IDENTITY(1,1) NOT NULL, +[LastName] [nvarchar](50) NOT NULL, +[FirstName] [nvarchar](50) NOT NULL, +[HireDate] [datetime] NULL, +[EnrollmentDate] [datetime] NULL, + CONSTRAINT [PK_School.Student] PRIMARY KEY CLUSTERED +( +[PersonID] ASC +)WITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, IGNORE_DUP_KEY = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON) ON [PRIMARY]) ON [PRIMARY] + +GO + +SET ANSI_NULLS ON +GO +SET QUOTED_IDENTIFIER ON +GO +CREATE TABLE [dbo].[StudentGrade]([EnrollmentID] [int] IDENTITY(1,1) NOT NULL, +[CourseID] [nvarchar](10) NOT NULL, +[StudentID] [int] NOT NULL, +[Grade] [decimal](3, 2) NOT NULL, + CONSTRAINT [PK_StudentGrade] PRIMARY KEY CLUSTERED +( +[EnrollmentID] ASC +)WITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, IGNORE_DUP_KEY = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON) ON [PRIMARY]) ON [PRIMARY] + +GO + +SET ANSI_NULLS ON +GO +SET QUOTED_IDENTIFIER ON +GO +create view [dbo].[EnglishCourse] +as +select c.CourseID,c.Title,c.Credits,c.DepartmentID +from Course as c join Department as d on c.DepartmentID=d.DepartmentID +where d.Name=N'English' + +GO +INSERT [dbo].[Course] ([CourseID], [Year], [Title], [Credits], [DepartmentID]) VALUES (N'C1045', 2012, N'Calculus', 4, 7) +INSERT [dbo].[Course] ([CourseID], [Year], [Title], [Credits], [DepartmentID]) VALUES (N'C1061', 2012, N'Physics', 4, 1) +INSERT [dbo].[Course] ([CourseID], [Year], [Title], [Credits], [DepartmentID]) VALUES (N'C2021', 2012, N'Composition', 3, 2) +INSERT [dbo].[Course] ([CourseID], [Year], [Title], [Credits], [DepartmentID]) VALUES (N'C2042', 2012, N'Literature', 4, 2) +SET IDENTITY_INSERT [dbo].[Department] ON + +INSERT [dbo].[Department] ([DepartmentID], [Name], [Budget], [StartDate], [Administrator]) VALUES (1, N'Engineering', 350000.0000, CAST(0x0000999C00000000 AS DateTime), 2) +INSERT [dbo].[Department] ([DepartmentID], [Name], [Budget], [StartDate], [Administrator]) VALUES (2, N'English', 120000.0000, CAST(0x0000999C00000000 AS DateTime), 6) +INSERT [dbo].[Department] ([DepartmentID], [Name], [Budget], [StartDate], [Administrator]) VALUES (4, N'Economics', 200000.0000, CAST(0x0000999C00000000 AS DateTime), 4) +INSERT [dbo].[Department] ([DepartmentID], [Name], [Budget], [StartDate], [Administrator]) VALUES (7, N'Mathematics', 250024.0000, CAST(0x0000999C00000000 AS DateTime), 3) +SET IDENTITY_INSERT [dbo].[Department] OFF +SET IDENTITY_INSERT [dbo].[Person] ON + +INSERT [dbo].[Person] ([PersonID], [LastName], [FirstName], [HireDate], [EnrollmentDate]) VALUES (1, N'Hu', N'Nan', NULL, CAST(0x0000A0BF00000000 AS DateTime)) +INSERT [dbo].[Person] ([PersonID], [LastName], [FirstName], [HireDate], [EnrollmentDate]) VALUES (2, N'Norman', N'Laura', NULL, CAST(0x0000A0BF00000000 AS DateTime)) +INSERT [dbo].[Person] ([PersonID], [LastName], [FirstName], [HireDate], [EnrollmentDate]) VALUES (3, N'Olivotto', N'Nino', NULL, CAST(0x0000A0BF00000000 AS DateTime)) +INSERT [dbo].[Person] ([PersonID], [LastName], [FirstName], [HireDate], [EnrollmentDate]) VALUES (4, N'Anand', N'Arturo', NULL, CAST(0x0000A0BF00000000 AS DateTime)) +INSERT [dbo].[Person] ([PersonID], [LastName], [FirstName], [HireDate], [EnrollmentDate]) VALUES (5, N'Jai', N'Damien', NULL, CAST(0x0000A0BF00000000 AS DateTime)) +INSERT [dbo].[Person] ([PersonID], [LastName], [FirstName], [HireDate], [EnrollmentDate]) VALUES (6, N'Holt', N'Roger', CAST(0x000097F100000000 AS DateTime), NULL) +INSERT [dbo].[Person] ([PersonID], [LastName], [FirstName], [HireDate], [EnrollmentDate]) VALUES (7, N'Martin', N'Randall', CAST(0x00008B1A00000000 AS DateTime), NULL) +SET IDENTITY_INSERT [dbo].[Person] OFF +SET IDENTITY_INSERT [dbo].[StudentGrade] ON + +INSERT [dbo].[StudentGrade] ([EnrollmentID], [CourseID], [StudentID], [Grade]) VALUES (1, N'C1045', 1, CAST(3.50 AS Decimal(3, 2))) +INSERT [dbo].[StudentGrade] ([EnrollmentID], [CourseID], [StudentID], [Grade]) VALUES (2, N'C1045', 2, CAST(3.00 AS Decimal(3, 2))) +INSERT [dbo].[StudentGrade] ([EnrollmentID], [CourseID], [StudentID], [Grade]) VALUES (3, N'C1045', 3, CAST(2.50 AS Decimal(3, 2))) +INSERT [dbo].[StudentGrade] ([EnrollmentID], [CourseID], [StudentID], [Grade]) VALUES (4, N'C1045', 4, CAST(4.00 AS Decimal(3, 2))) +INSERT [dbo].[StudentGrade] ([EnrollmentID], [CourseID], [StudentID], [Grade]) VALUES (5, N'C1045', 5, CAST(3.50 AS Decimal(3, 2))) +INSERT [dbo].[StudentGrade] ([EnrollmentID], [CourseID], [StudentID], [Grade]) VALUES (6, N'C1061', 1, CAST(4.00 AS Decimal(3, 2))) +INSERT [dbo].[StudentGrade] ([EnrollmentID], [CourseID], [StudentID], [Grade]) VALUES (7, N'C1061', 3, CAST(3.50 AS Decimal(3, 2))) +INSERT [dbo].[StudentGrade] ([EnrollmentID], [CourseID], [StudentID], [Grade]) VALUES (8, N'C1061', 4, CAST(2.50 AS Decimal(3, 2))) +INSERT [dbo].[StudentGrade] ([EnrollmentID], [CourseID], [StudentID], [Grade]) VALUES (9, N'C1061', 5, CAST(1.50 AS Decimal(3, 2))) +INSERT [dbo].[StudentGrade] ([EnrollmentID], [CourseID], [StudentID], [Grade]) VALUES (10, N'C2021', 1, CAST(2.50 AS Decimal(3, 2))) +INSERT [dbo].[StudentGrade] ([EnrollmentID], [CourseID], [StudentID], [Grade]) VALUES (11, N'C2021', 2, CAST(3.50 AS Decimal(3, 2))) +INSERT [dbo].[StudentGrade] ([EnrollmentID], [CourseID], [StudentID], [Grade]) VALUES (12, N'C2021', 4, CAST(3.00 AS Decimal(3, 2))) +INSERT [dbo].[StudentGrade] ([EnrollmentID], [CourseID], [StudentID], [Grade]) VALUES (13, N'C2021', 5, CAST(3.00 AS Decimal(3, 2))) +INSERT [dbo].[StudentGrade] ([EnrollmentID], [CourseID], [StudentID], [Grade]) VALUES (14, N'C2042', 1, CAST(2.00 AS Decimal(3, 2))) +INSERT [dbo].[StudentGrade] ([EnrollmentID], [CourseID], [StudentID], [Grade]) VALUES (15, N'C2042', 2, CAST(3.50 AS Decimal(3, 2))) +INSERT [dbo].[StudentGrade] ([EnrollmentID], [CourseID], [StudentID], [Grade]) VALUES (16, N'C2042', 3, CAST(4.00 AS Decimal(3, 2))) +INSERT [dbo].[StudentGrade] ([EnrollmentID], [CourseID], [StudentID], [Grade]) VALUES (17, N'C2042', 5, CAST(3.00 AS Decimal(3, 2))) +SET IDENTITY_INSERT [dbo].[StudentGrade] OFF +ALTER TABLE [dbo].[Course] WITH CHECK ADD CONSTRAINT [FK_Course_Department] FOREIGN KEY([DepartmentID]) +REFERENCES [dbo].[Department] ([DepartmentID]) +GO +ALTER TABLE [dbo].[Course] CHECK CONSTRAINT [FK_Course_Department] +GO +ALTER TABLE [dbo].[StudentGrade] WITH CHECK ADD CONSTRAINT [FK_StudentGrade_Student] FOREIGN KEY([StudentID]) +REFERENCES [dbo].[Person] ([PersonID]) +GO +ALTER TABLE [dbo].[StudentGrade] CHECK CONSTRAINT [FK_StudentGrade_Student] +GO +``` + + Next, compile and execute the following: + ```csharp -using System; -using System.Data; -using System.Data.SqlClient; -using System.Threading.Tasks; - -class Program { - - static class SqlHelper { - // Set the connection, command, and then execute the command with non query. - public static Int32 ExecuteNonQuery(String connectionString, String commandText, - CommandType commandType, params SqlParameter[] parameters) { - using (SqlConnection conn = new SqlConnection(connectionString)) { - using (SqlCommand cmd = new SqlCommand(commandText, conn)) { - // There're three command types: StoredProcedure, Text, TableDirect. The TableDirect - // type is only for OLE DB. - cmd.CommandType = commandType; - cmd.Parameters.AddRange(parameters); - - conn.Open(); - return cmd.ExecuteNonQuery(); - } - } - } - - // Set the connection, command, and then execute the command and only return one value. - public static Object ExecuteScalar(String connectionString, String commandText, - CommandType commandType, params SqlParameter[] parameters) { - using (SqlConnection conn = new SqlConnection(connectionString)) { - using (SqlCommand cmd = new SqlCommand(commandText, conn)) { - cmd.CommandType = commandType; - cmd.Parameters.AddRange(parameters); - - conn.Open(); - return cmd.ExecuteScalar(); - } - } - } - - // Set the connection, command, and then execute the command with query and return the reader. - public static SqlDataReader ExecuteReader(String connectionString, String commandText, - CommandType commandType, params SqlParameter[] parameters) { - SqlConnection conn = new SqlConnection(connectionString); - - using (SqlCommand cmd = new SqlCommand(commandText, conn)) { - cmd.CommandType = commandType; - cmd.Parameters.AddRange(parameters); - - conn.Open(); - // When using CommandBehavior.CloseConnection, the connection will be closed when the - // IDataReader is closed. - SqlDataReader reader = cmd.ExecuteReader(CommandBehavior.CloseConnection); - - return reader; - } - } - } - - static void Main(string[] args) { - String connectionString = "Data Source=(local);Initial Catalog=MySchool;Integrated Security=True;Asynchronous Processing=true;"; - - CountCourses(connectionString, 2012); - Console.WriteLine(); - - Console.WriteLine("Following result is the departments that started from 2007:"); - GetDepartments(connectionString, 2007); - Console.WriteLine(); - - Console.WriteLine("Add the credits when the credits of course is lower than 4."); - AddCredits(connectionString, 4); - Console.WriteLine(); - - Console.WriteLine("Please press any key to exit..."); - Console.ReadKey(); - } - - static void CountCourses(String connectionString, Int32 year) { - String commandText = "Select Count([CourseID]) FROM [MySchool].[dbo].[Course] Where Year=@Year"; - SqlParameter parameterYear = new SqlParameter("@Year", SqlDbType.Int); - parameterYear.Value = year; - - Object oValue = SqlHelper.ExecuteScalar(connectionString, commandText, CommandType.Text, parameterYear); - Int32 count; - if (Int32.TryParse(oValue.ToString(), out count)) - Console.WriteLine("There {0} {1} course{2} in {3}.", count > 1 ? "are" : "is", count, count > 1 ? "s" : null, year); - } - - // Display the Departments that start from the specified year. - static void GetDepartments(String connectionString, Int32 year) { - String commandText = "dbo.GetDepartmentsOfSpecifiedYear"; - - // Specify the year of StartDate - SqlParameter parameterYear = new SqlParameter("@Year", SqlDbType.Int); - parameterYear.Value = year; - - // When the direction of parameter is set as Output, you can get the value after - // executing the command. - SqlParameter parameterBudget = new SqlParameter("@BudgetSum", SqlDbType.Money); - parameterBudget.Direction = ParameterDirection.Output; - - using (SqlDataReader reader = SqlHelper.ExecuteReader(connectionString, commandText, - CommandType.StoredProcedure, parameterYear, parameterBudget)) { - Console.WriteLine("{0,-20}{1,-20}{2,-20}{3,-20}", "Name", "Budget", "StartDate", - "Administrator"); - while (reader.Read()) { - Console.WriteLine("{0,-20}{1,-20:C}{2,-20:d}{3,-20}", reader["Name"], - reader["Budget"], reader["StartDate"], reader["Administrator"]); - } - } - Console.WriteLine("{0,-20}{1,-20:C}", "Sum:", parameterBudget.Value); - } - - // If credits of course is lower than the certain value, the method will add the credits. - static void AddCredits(String connectionString, Int32 creditsLow) { - String commandText = "Update [MySchool].[dbo].[Course] Set Credits=Credits+1 Where Credits<@Credits"; - - SqlParameter parameterCredits = new SqlParameter("@Credits", creditsLow); - - Int32 rows = SqlHelper.ExecuteNonQuery(connectionString, commandText, CommandType.Text, parameterCredits); - - Console.WriteLine("{0} row{1} {2} updated.", rows, rows > 1 ? "s" : null, rows > 1 ? "are" : "is"); - } -} -``` - +using System; +using System.Data; +using System.Data.SqlClient; +using System.Threading.Tasks; + +class Program { + + static class SqlHelper { + // Set the connection, command, and then execute the command with non query. + public static Int32 ExecuteNonQuery(String connectionString, String commandText, + CommandType commandType, params SqlParameter[] parameters) { + using (SqlConnection conn = new SqlConnection(connectionString)) { + using (SqlCommand cmd = new SqlCommand(commandText, conn)) { + // There're three command types: StoredProcedure, Text, TableDirect. The TableDirect + // type is only for OLE DB. + cmd.CommandType = commandType; + cmd.Parameters.AddRange(parameters); + + conn.Open(); + return cmd.ExecuteNonQuery(); + } + } + } + + // Set the connection, command, and then execute the command and only return one value. + public static Object ExecuteScalar(String connectionString, String commandText, + CommandType commandType, params SqlParameter[] parameters) { + using (SqlConnection conn = new SqlConnection(connectionString)) { + using (SqlCommand cmd = new SqlCommand(commandText, conn)) { + cmd.CommandType = commandType; + cmd.Parameters.AddRange(parameters); + + conn.Open(); + return cmd.ExecuteScalar(); + } + } + } + + // Set the connection, command, and then execute the command with query and return the reader. + public static SqlDataReader ExecuteReader(String connectionString, String commandText, + CommandType commandType, params SqlParameter[] parameters) { + SqlConnection conn = new SqlConnection(connectionString); + + using (SqlCommand cmd = new SqlCommand(commandText, conn)) { + cmd.CommandType = commandType; + cmd.Parameters.AddRange(parameters); + + conn.Open(); + // When using CommandBehavior.CloseConnection, the connection will be closed when the + // IDataReader is closed. + SqlDataReader reader = cmd.ExecuteReader(CommandBehavior.CloseConnection); + + return reader; + } + } + } + + static void Main(string[] args) { + String connectionString = "Data Source=(local);Initial Catalog=MySchool;Integrated Security=True;Asynchronous Processing=true;"; + + CountCourses(connectionString, 2012); + Console.WriteLine(); + + Console.WriteLine("Following result is the departments that started from 2007:"); + GetDepartments(connectionString, 2007); + Console.WriteLine(); + + Console.WriteLine("Add the credits when the credits of course is lower than 4."); + AddCredits(connectionString, 4); + Console.WriteLine(); + + Console.WriteLine("Please press any key to exit..."); + Console.ReadKey(); + } + + static void CountCourses(String connectionString, Int32 year) { + String commandText = "Select Count([CourseID]) FROM [MySchool].[dbo].[Course] Where Year=@Year"; + SqlParameter parameterYear = new SqlParameter("@Year", SqlDbType.Int); + parameterYear.Value = year; + + Object oValue = SqlHelper.ExecuteScalar(connectionString, commandText, CommandType.Text, parameterYear); + Int32 count; + if (Int32.TryParse(oValue.ToString(), out count)) + Console.WriteLine("There {0} {1} course{2} in {3}.", count > 1 ? "are" : "is", count, count > 1 ? "s" : null, year); + } + + // Display the Departments that start from the specified year. + static void GetDepartments(String connectionString, Int32 year) { + String commandText = "dbo.GetDepartmentsOfSpecifiedYear"; + + // Specify the year of StartDate + SqlParameter parameterYear = new SqlParameter("@Year", SqlDbType.Int); + parameterYear.Value = year; + + // When the direction of parameter is set as Output, you can get the value after + // executing the command. + SqlParameter parameterBudget = new SqlParameter("@BudgetSum", SqlDbType.Money); + parameterBudget.Direction = ParameterDirection.Output; + + using (SqlDataReader reader = SqlHelper.ExecuteReader(connectionString, commandText, + CommandType.StoredProcedure, parameterYear, parameterBudget)) { + Console.WriteLine("{0,-20}{1,-20}{2,-20}{3,-20}", "Name", "Budget", "StartDate", + "Administrator"); + while (reader.Read()) { + Console.WriteLine("{0,-20}{1,-20:C}{2,-20:d}{3,-20}", reader["Name"], + reader["Budget"], reader["StartDate"], reader["Administrator"]); + } + } + Console.WriteLine("{0,-20}{1,-20:C}", "Sum:", parameterBudget.Value); + } + + // If credits of course is lower than the certain value, the method will add the credits. + static void AddCredits(String connectionString, Int32 creditsLow) { + String commandText = "Update [MySchool].[dbo].[Course] Set Credits=Credits+1 Where Credits<@Credits"; + + SqlParameter parameterCredits = new SqlParameter("@Credits", creditsLow); + + Int32 rows = SqlHelper.ExecuteNonQuery(connectionString, commandText, CommandType.Text, parameterCredits); + + Console.WriteLine("{0} row{1} {2} updated.", rows, rows > 1 ? "s" : null, rows > 1 ? "are" : "is"); + } +} +``` + ]]> Retrieving and Modifying Data in ADO.NET @@ -478,28 +478,28 @@ class Program { Initializes a new instance of the class. - . - -|Properties|Initial value| -|----------------|-------------------| -||empty string ("")| -||30| -||`CommandType.Text`| -||Null| - - You can change the value for any of these properties through a separate call to the property. - - - -## Examples - The following example creates a and sets the `CommandTimeout` property. - + . + +|Properties|Initial value| +|----------------|-------------------| +||empty string ("")| +||30| +||`CommandType.Text`| +||Null| + + You can change the value for any of these properties through a separate call to the property. + + + +## Examples + The following example creates a and sets the `CommandTimeout` property. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData IDbCommand.CommandTimeout Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData IDbCommand.CommandTimeout Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData IDbCommand.CommandTimeout Example/VB/source.vb" id="Snippet1"::: + ]]> Retrieving and Modifying Data in ADO.NET @@ -543,28 +543,28 @@ class Program { The text of the query. Initializes a new instance of the class with the text of the query. - is created, the following read/write properties are set to initial values. - -|Properties|Initial value| -|----------------|-------------------| -||`cmdText`| -||30| -||`CommandType.Text`| -||null| - - You can change the value for any of these properties through a separate call to the property. - - - -## Examples - The following example creates a , passing in the connection string and command text. - + is created, the following read/write properties are set to initial values. + +|Properties|Initial value| +|----------------|-------------------| +||`cmdText`| +||30| +||`CommandType.Text`| +||null| + + You can change the value for any of these properties through a separate call to the property. + + + +## Examples + The following example creates a , passing in the connection string and command text. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData SqlCommand.SqlCommand1 Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData SqlCommand.SqlCommand1 Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData SqlCommand.SqlCommand1 Example/VB/source.vb" id="Snippet1"::: + ]]> Connecting and Retrieving Data in ADO.NET @@ -610,28 +610,28 @@ class Program { A that represents the connection to an instance of SQL Server. Initializes a new instance of the class with the text of the query and a . - . - -|Properties|Initial value| -|----------------|-------------------| -||`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. - - - -## Examples - The following example creates a and sets some of its properties. - + . + +|Properties|Initial value| +|----------------|-------------------| +||`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. + + + +## Examples + The following example creates a and sets some of its properties. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData SqlCommand.SqlCommand2 Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData SqlCommand.SqlCommand2 Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData SqlCommand.SqlCommand2 Example/VB/source.vb" id="Snippet1"::: + ]]> Connecting and Retrieving Data in ADO.NET @@ -679,20 +679,20 @@ class Program { The in which the executes. Initializes a new instance of the class with the text of the query, a , and the . - . - -|Properties|Initial value| -|----------------|-------------------| -||`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. - + . + +|Properties|Initial value| +|----------------|-------------------| +||`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. + ]]> Connecting and Retrieving Data in ADO.NET @@ -772,42 +772,42 @@ class Program { Initiates the asynchronous execution of the Transact-SQL statement or stored procedure that is described by this . An that can be used to poll or wait for results, or both; this value is also needed when invoking , which returns the number of affected rows. - 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 . + 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 . This method ignores the property. - - - -## Examples - The following console application creates updates data within the **AdventureWorks** sample database, doing its work asynchronously. In order to emulate a long-running process, this example inserts a WAITFOR statement in the command text. Normally, you would not take efforts to make your commands run slower, but doing this in this case makes it easier to demonstrate the asynchronous behavior. - + + + +## Examples + The following console application creates updates data within the **AdventureWorks** sample database, doing its work asynchronously. In order to emulate a long-running process, this example inserts a WAITFOR statement in the command text. Normally, you would not take efforts to make your commands run slower, but doing this in this case makes it easier to demonstrate the asynchronous behavior. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks SqlCommand.BeginExecuteNonQuery/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/DataWorks SqlCommand.BeginExecuteNonQuery/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/DataWorks SqlCommand.BeginExecuteNonQuery/VB/source.vb" id="Snippet1"::: + ]]> - A other than **Binary** or **VarBinary** was used when was set to . For more information about streaming, see [SqlClient Streaming Support](/dotnet/framework/data/adonet/sqlclient-streaming-support). + A other than **Binary** or **VarBinary** was used when was set to . For more information about streaming, see [SqlClient Streaming Support](/dotnet/framework/data/adonet/sqlclient-streaming-support). -or- - A other than **Char**, **NChar**, **NVarChar**, **VarChar**, or **Xml** was used when was set to . + A other than **Char**, **NChar**, **NVarChar**, **VarChar**, or **Xml** was used when was set to . -or- A other than **Xml** was used when was set to . - Any error that occurred while executing the command text. + Any error that occurred while executing the command text. -or- A timeout occurred during a streaming operation. For more information about streaming, see [SqlClient Streaming Support](/dotnet/framework/data/adonet/sqlclient-streaming-support). - The name/value pair "Asynchronous Processing=true" was not included within the connection string defining the connection for this . + The name/value pair "Asynchronous Processing=true" was not included within the connection string defining the connection for this . -or- @@ -855,50 +855,50 @@ The closed or dropped durin Initiates the asynchronous execution of the Transact-SQL statement or stored procedure that is described by this , given a callback procedure and state information. An that can be used to poll or wait for results, or both; this value is also needed when invoking , which returns the number of affected rows. - 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. - - 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 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. + 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. + + 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 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. 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 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. - - To set up this example, create a new Windows application. Put a control and a control on the form (accepting the default name for each control). Add the following code to the form's class, modifying the connection string as needed for your environment. - + + + +## 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). + + 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. + + To set up this example, create a new Windows application. Put a control and a control on the form (accepting the default name for each control). Add the following code to the form's class, modifying the connection string as needed for your environment. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks SqlCommand.BeginExecuteNonQueryForm/CS/Form1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/DataWorks SqlCommand.BeginExecuteNonQueryForm/VB/Form1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/DataWorks SqlCommand.BeginExecuteNonQueryForm/VB/Form1.vb" id="Snippet1"::: + ]]> - A other than **Binary** or **VarBinary** was used when was set to . For more information about streaming, see [SqlClient Streaming Support](/dotnet/framework/data/adonet/sqlclient-streaming-support). + A other than **Binary** or **VarBinary** was used when was set to . For more information about streaming, see [SqlClient Streaming Support](/dotnet/framework/data/adonet/sqlclient-streaming-support). -or- -A other than **Char**, **NChar**, **NVarChar**, **VarChar**, or **Xml** was used when was set to . +A other than **Char**, **NChar**, **NVarChar**, **VarChar**, or **Xml** was used when was set to . -or- A other than **Xml** was used when was set to . - Any error that occurred while executing the command text. + Any error that occurred while executing the command text. -or- A timeout occurred during a streaming operation. For more information about streaming, see [SqlClient Streaming Support](/dotnet/framework/data/adonet/sqlclient-streaming-support). - The name/value pair "Asynchronous Processing=true" was not included within the connection string defining the connection for this . + The name/value pair "Asynchronous Processing=true" was not included within the connection string defining the connection for this . -or- @@ -950,44 +950,44 @@ A other than **Xml Initiates the asynchronous execution of the Transact-SQL statement or stored procedure that is described by this , and retrieves one or more result sets from the server. An that can be used to poll or wait for results, or both; this value is also needed when invoking , which returns a instance that can be used to retrieve the returned rows. - 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. - - 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 . - + 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. + + 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. This method ignores the property. - - - -## Examples - The following console application starts the process of retrieving a data reader asynchronously. While waiting for the results, this simple application sits in a loop, investigating the property value. As soon as the process has completed, the code retrieves the and displays its contents. - + + + +## Examples + The following console application starts the process of retrieving a data reader asynchronously. While waiting for the results, this simple application sits in a loop, investigating the property value. As soon as the process has completed, the code retrieves the and displays its contents. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks SqlCommand.BeginExecuteReader/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/DataWorks SqlCommand.BeginExecuteReader/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/DataWorks SqlCommand.BeginExecuteReader/VB/source.vb" id="Snippet1"::: + ]]> - A other than **Binary** or **VarBinary** was used when was set to . For more information about streaming, see [SqlClient Streaming Support](/dotnet/framework/data/adonet/sqlclient-streaming-support). + A other than **Binary** or **VarBinary** was used when was set to . For more information about streaming, see [SqlClient Streaming Support](/dotnet/framework/data/adonet/sqlclient-streaming-support). -or- - A other than **Char**, **NChar**, **NVarChar**, **VarChar**, or **Xml** was used when was set to . + A other than **Char**, **NChar**, **NVarChar**, **VarChar**, or **Xml** was used when was set to . -or- A other than **Xml** was used when was set to . - Any error that occurred while executing the command text. + Any error that occurred while executing the command text. -or- A timeout occurred during a streaming operation. For more information about streaming, see [SqlClient Streaming Support](/dotnet/framework/data/adonet/sqlclient-streaming-support). - The name/value pair "Asynchronous Processing=true" was not included within the connection string defining the connection for this . + The name/value pair "Asynchronous Processing=true" was not included within the connection string defining the connection for this . -or- @@ -1024,54 +1024,54 @@ A timeout occurred during a streaming operation. For more information about stre System.IAsyncResult - + One of the values, indicating options for statement execution and data retrieval. Initiates the asynchronous execution of the Transact-SQL statement or stored procedure that is described by this using one of the values. An that can be used to poll, wait for results, or both; this value is also needed when invoking , which returns a instance that can be used to retrieve the returned rows. - 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. - - 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 . - + 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. + + 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. This method ignores the property. - - -## Examples - The following console application starts the process of retrieving a data reader asynchronously. While waiting for the results, this simple application sits in a loop, investigating the property value. Once the process has completed, the code retrieves the and displays its contents. - - This example also passes the `CommandBehavior.CloseConnection` and `CommandBehavior.SingleRow` values in the behavior parameter, causing the connection to be closed with the returned is closed, and to optimize for a single row result. - + + +## Examples + The following console application starts the process of retrieving a data reader asynchronously. While waiting for the results, this simple application sits in a loop, investigating the property value. Once the process has completed, the code retrieves the and displays its contents. + + This example also passes the `CommandBehavior.CloseConnection` and `CommandBehavior.SingleRow` values in the behavior parameter, causing the connection to be closed with the returned is closed, and to optimize for a single row result. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks SqlCommand.BeginExecuteReaderAsyncSimple/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/DataWorks SqlCommand.BeginExecuteReaderAsyncSimple/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/DataWorks SqlCommand.BeginExecuteReaderAsyncSimple/VB/source.vb" id="Snippet1"::: + ]]> - A other than **Binary** or **VarBinary** was used when was set to . For more information about streaming, see [SqlClient Streaming Support](/dotnet/framework/data/adonet/sqlclient-streaming-support). + A other than **Binary** or **VarBinary** was used when was set to . For more information about streaming, see [SqlClient Streaming Support](/dotnet/framework/data/adonet/sqlclient-streaming-support). -or- - A other than **Char**, **NChar**, **NVarChar**, **VarChar**, or **Xml** was used when was set to . + A other than **Char**, **NChar**, **NVarChar**, **VarChar**, or **Xml** was used when was set to . -or- A other than **Xml** was used when was set to . - Any error that occurred while executing the command text. + Any error that occurred while executing the command text. -or- A timeout occurred during a streaming operation. For more information about streaming, see [SqlClient Streaming Support](/dotnet/framework/data/adonet/sqlclient-streaming-support). - The name/value pair "Asynchronous Processing=true" was not included within the connection string defining the connection for this . + The name/value pair "Asynchronous Processing=true" was not included within the connection string defining the connection for this . -or- @@ -1108,8 +1108,8 @@ A timeout occurred during a streaming operation. For more information about stre System.IAsyncResult - - + + An delegate that is invoked when the command's execution has completed. Pass ( in Microsoft Visual Basic) to indicate that no callback is required. @@ -1117,52 +1117,52 @@ A timeout occurred during a streaming operation. For more information about stre Initiates the asynchronous execution of the Transact-SQL statement or stored procedure that is described by this and retrieves one or more result sets from the server, given a callback procedure and state information. An that can be used to poll, wait for results, or both; this value is also needed when invoking , which returns a instance which can be used to retrieve the returned rows. - 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. - - 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. - + 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. + + 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. 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 . - - 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. - - To set up this example, create a new Windows application. Put a control, a control, and a control on the form (accepting the default name for each control). Add the following code to the form's class, modifying the connection string as needed for your environment. - + + + +## 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 . + + 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. + + To set up this example, create a new Windows application. Put a control, a control, and a control on the form (accepting the default name for each control). Add the following code to the form's class, modifying the connection string as needed for your environment. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks SqlCommand.BeginExecuteReaderAsync/CS/Form1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/DataWorks SqlCommand.BeginExecuteReaderAsync/VB/Form1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/DataWorks SqlCommand.BeginExecuteReaderAsync/VB/Form1.vb" id="Snippet1"::: + ]]> - A other than **Binary** or **VarBinary** was used when was set to . For more information about streaming, see [SqlClient Streaming Support](/dotnet/framework/data/adonet/sqlclient-streaming-support). + A other than **Binary** or **VarBinary** was used when was set to . For more information about streaming, see [SqlClient Streaming Support](/dotnet/framework/data/adonet/sqlclient-streaming-support). -or- -A other than **Char**, **NChar**, **NVarChar**, **VarChar**, or **Xml** was used when was set to . +A other than **Char**, **NChar**, **NVarChar**, **VarChar**, or **Xml** was used when was set to . -or- A other than **Xml** was used when was set to . - Any error that occurred while executing the command text. + Any error that occurred while executing the command text. -or- A timeout occurred during a streaming operation. For more information about streaming, see [SqlClient Streaming Support](/dotnet/framework/data/adonet/sqlclient-streaming-support). - The name/value pair "Asynchronous Processing=true" was not included within the connection string defining the connection for this . + The name/value pair "Asynchronous Processing=true" was not included within the connection string defining the connection for this . -or- @@ -1199,9 +1199,9 @@ A other than **Xml System.IAsyncResult - - - + + + An delegate that is invoked when the command's execution has completed. Pass ( in Microsoft Visual Basic) to indicate that no callback is required. @@ -1210,56 +1210,56 @@ A other than **Xml Initiates the asynchronous execution of the Transact-SQL statement or stored procedure that is described by this , using one of the values, and retrieving one or more result sets from the server, given a callback procedure and state information. An that can be used to poll or wait for results, or both; this value is also needed when invoking , which returns a instance which can be used to retrieve the returned rows. - 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 `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. - - 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. - + 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 `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. + + 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. 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 . - - 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. - - To set up this example, create a new Windows application. Put a control, a control, and a control on the form (accepting the default name for each control). Add the following code to the form's class, modifying the connection string as needed for your environment. - - This example passes the `CommandBehavior.CloseConnection` value in the `behavior` parameter, causing the returned to automatically close its connection when it is closed. - + + + +## 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 . + + 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. + + To set up this example, create a new Windows application. Put a control, a control, and a control on the form (accepting the default name for each control). Add the following code to the form's class, modifying the connection string as needed for your environment. + + This example passes the `CommandBehavior.CloseConnection` value in the `behavior` parameter, causing the returned to automatically close its connection when it is closed. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks SqlCommand.BeginExecuteReaderAsyncBehavior/CS/Form1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/DataWorks SqlCommand.BeginExecuteReaderAsyncBehavior/VB/Form1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/DataWorks SqlCommand.BeginExecuteReaderAsyncBehavior/VB/Form1.vb" id="Snippet1"::: + ]]> - A other than **Binary** or **VarBinary** was used when was set to . For more information about streaming, see [SqlClient Streaming Support](/dotnet/framework/data/adonet/sqlclient-streaming-support). + A other than **Binary** or **VarBinary** was used when was set to . For more information about streaming, see [SqlClient Streaming Support](/dotnet/framework/data/adonet/sqlclient-streaming-support). -or- - A other than **Char**, **NChar**, **NVarChar**, **VarChar**, or **Xml** was used when was set to . + A other than **Char**, **NChar**, **NVarChar**, **VarChar**, or **Xml** was used when was set to . -or- A other than **Xml** was used when was set to . - Any error that occurred while executing the command text. + Any error that occurred while executing the command text. -or- A timeout occurred during a streaming operation. For more information about streaming, see [SqlClient Streaming Support](/dotnet/framework/data/adonet/sqlclient-streaming-support). - The name/value pair "Asynchronous Processing=true" was not included within the connection string defining the connection for this . + The name/value pair "Asynchronous Processing=true" was not included within the connection string defining the connection for this . -or- @@ -1313,56 +1313,56 @@ A other than **Xml Initiates the asynchronous execution of the Transact-SQL statement or stored procedure that is described by this and returns results as an object. An that can be used to poll or wait for results, or both; this value is also needed when invoking , which returns a single XML value. - 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: - + 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: + ```csharp -SqlCommand command = new SqlCommand("SELECT ContactID, FirstName, LastName FROM dbo.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 `EndExecuteXmlReader` 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. - - 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 . - +SqlCommand command = new SqlCommand("SELECT ContactID, FirstName, LastName FROM dbo.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 `EndExecuteXmlReader` 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. + + 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 . + 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 console application starts the process of retrieving XML data asynchronously. While waiting for the results, this simple application sits in a loop, investigating the property value. Once the process has completed, the code retrieves the XML and displays its contents. - + + + +## Examples + The following console application starts the process of retrieving XML data asynchronously. While waiting for the results, this simple application sits in a loop, investigating the property value. Once the process has completed, the code retrieves the XML and displays its contents. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks SqlCommand.BeginExecuteXmlReader/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/DataWorks SqlCommand.BeginExecuteXmlReader/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/DataWorks SqlCommand.BeginExecuteXmlReader/VB/source.vb" id="Snippet1"::: + ]]> - A other than **Binary** or **VarBinary** was used when was set to . For more information about streaming, see [SqlClient Streaming Support](/dotnet/framework/data/adonet/sqlclient-streaming-support). + A other than **Binary** or **VarBinary** was used when was set to . For more information about streaming, see [SqlClient Streaming Support](/dotnet/framework/data/adonet/sqlclient-streaming-support). -or- -A other than **Char**, **NChar**, **NVarChar**, **VarChar**, or **Xml** was used when was set to . +A other than **Char**, **NChar**, **NVarChar**, **VarChar**, or **Xml** was used when was set to . -or- A other than **Xml** was used when was set to . - Any error that occurred while executing the command text. + Any error that occurred while executing the command text. -or- A timeout occurred during a streaming operation. For more information about streaming, see [SqlClient Streaming Support](/dotnet/framework/data/adonet/sqlclient-streaming-support). - The name/value pair "Asynchronous Processing=true" was not included within the connection string defining the connection for this . + The name/value pair "Asynchronous Processing=true" was not included within the connection string defining the connection for this . -or- @@ -1410,62 +1410,62 @@ The closed or dropped durin Initiates the asynchronous execution of the Transact-SQL statement or stored procedure that is described by this and returns results as an object, using a callback procedure. An that can be used to poll, wait for results, or both; this value is also needed when the is called, which returns the results of the command as XML. - 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. - - A typical query can be formatted as in the following C# example: - + 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. + + 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. - - 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. - - 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. - +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. + + 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. + + 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. 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 . - - 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. - - To set up this example, create a new Windows application. Put a control, a control, and a control on the form (accepting the default name for each control). Add the following code to the form's class, modifying the connection string as needed for your environment. - + + + +## 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 . + + 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. + + To set up this example, create a new Windows application. Put a control, a control, and a control on the form (accepting the default name for each control). Add the following code to the form's class, modifying the connection string as needed for your environment. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks SqlCommand.BeginExecuteXmlReaderAsync/CS/Form1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/DataWorks SqlCommand.BeginExecuteXmlReaderAsync/VB/Form1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/DataWorks SqlCommand.BeginExecuteXmlReaderAsync/VB/Form1.vb" id="Snippet1"::: + ]]> - A other than **Binary** or **VarBinary** was used when was set to . For more information about streaming, see [SqlClient Streaming Support](/dotnet/framework/data/adonet/sqlclient-streaming-support). + A other than **Binary** or **VarBinary** was used when was set to . For more information about streaming, see [SqlClient Streaming Support](/dotnet/framework/data/adonet/sqlclient-streaming-support). -or- -A other than **Char**, **NChar**, **NVarChar**, **VarChar**, or **Xml** was used when was set to . +A other than **Char**, **NChar**, **NVarChar**, **VarChar**, or **Xml** was used when was set to . -or- A other than **Xml** was used when was set to . - Any error that occurred while executing the command text. + Any error that occurred while executing the command text. -or- A timeout occurred during a streaming operation. For more information about streaming, see [SqlClient Streaming Support](/dotnet/framework/data/adonet/sqlclient-streaming-support). - The name/value pair "Asynchronous Processing=true" was not included within the connection string defining the connection for this . + The name/value pair "Asynchronous Processing=true" was not included within the connection string defining the connection for this . -or- @@ -1521,21 +1521,21 @@ The closed or dropped durin Tries to cancel the execution of a . - , 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. - + , 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. + :::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/VS_Snippets_ADO.NET/Classic WebData SqlCommand.Cancel/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData SqlCommand.Cancel/VB/source.vb" id="Snippet1"::: + ]]> Connecting and Retrieving Data in ADO.NET @@ -1681,27 +1681,27 @@ The closed or dropped durin Gets or sets the Transact-SQL statement, table name or stored procedure to execute at the data source. The Transact-SQL statement or stored procedure to execute. The default is an empty string. - 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. - - The Microsoft .NET Framework Data Provider for SQL Server does not support the question mark (?) placeholder for passing parameters to a Transact-SQL statement or a stored procedure called by a command of `CommandType.Text`. In this case, named parameters must be used. For example: - + 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. + + The Microsoft .NET Framework Data Provider for SQL Server does not support the question mark (?) placeholder for passing parameters to a Transact-SQL statement or a stored procedure called by a command of `CommandType.Text`. In this case, named parameters must be used. For example: + ```sql -SELECT * FROM dbo.Customers WHERE CustomerID = @CustomerID -``` - - For more information, see [Configuring Parameters and Parameter Data Types](/dotnet/framework/data/adonet/configuring-parameters-and-parameter-data-types). - - - -## Examples - The following example creates a and sets some of its properties. - +SELECT * FROM dbo.Customers WHERE CustomerID = @CustomerID +``` + + For more information, see [Configuring Parameters and Parameter Data Types](/dotnet/framework/data/adonet/configuring-parameters-and-parameter-data-types). + + + +## Examples + The following example creates a and sets some of its properties. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData SqlCommand.CommandText Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData SqlCommand.CommandText Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData SqlCommand.CommandText Example/VB/source.vb" id="Snippet1"::: + ]]> Retrieving and Modifying Data in ADO.NET @@ -1761,48 +1761,48 @@ SELECT * FROM dbo.Customers WHERE CustomerID = @CustomerID Gets or sets the wait time (in seconds) before terminating the attempt to execute a command and generating an error. The time in seconds to wait for the command to execute. The default is 30 seconds. - [!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 . - - 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. - +> 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. + ```csharp -using System; -using System.Data.SqlClient; -/// -public class A { - /// - public static void Main() { - string connectionString = ""; - // Wait for 5 second delay in the command - string queryString = "waitfor delay '00:00:05'"; - using (SqlConnection connection = new SqlConnection(connectionString)) { - connection.Open(); - SqlCommand command = new SqlCommand(queryString, connection); - // Setting command timeout to 1 second - command.CommandTimeout = 1; - try { - command.ExecuteNonQuery(); - } - catch (SqlException e) { - Console.WriteLine("Got expected SqlException due to command timeout "); - Console.WriteLine(e); - } - } - } -} -``` - +using System; +using System.Data.SqlClient; +/// +public class A { + /// + public static void Main() { + string connectionString = ""; + // Wait for 5 second delay in the command + string queryString = "waitfor delay '00:00:05'"; + using (SqlConnection connection = new SqlConnection(connectionString)) { + connection.Open(); + SqlCommand command = new SqlCommand(queryString, connection); + // Setting command timeout to 1 second + command.CommandTimeout = 1; + try { + command.ExecuteNonQuery(); + } + catch (SqlException e) { + Console.WriteLine("Got expected SqlException due to command timeout "); + Console.WriteLine(e); + } + } + } +} +``` + ]]> Connecting and Retrieving Data in ADO.NET @@ -1866,25 +1866,25 @@ public class A { Gets or sets a value indicating how the property is to be interpreted. One of the values. The default is . - 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: - - SELECT * FROM Customers WHERE CustomerID = @CustomerID - - For more information, see [Configuring Parameters and Parameter Data Types](/dotnet/framework/data/adonet/configuring-parameters-and-parameter-data-types). - - - -## Examples - The following example creates a and sets some of its properties. - + 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: + + SELECT * FROM Customers WHERE CustomerID = @CustomerID + + For more information, see [Configuring Parameters and Parameter Data Types](/dotnet/framework/data/adonet/configuring-parameters-and-parameter-data-types). + + + +## Examples + The following example creates a and sets some of its properties. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData IDbCommand.CommandTimeout Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData IDbCommand.CommandTimeout Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData IDbCommand.CommandTimeout Example/VB/source.vb" id="Snippet1"::: + ]]> The value was not a valid . @@ -1951,21 +1951,21 @@ public class A { Gets or sets the used by this instance of the . The connection to a data source. The default value is . - . - - If the property is not null and the transaction has already been committed or rolled back, is set to null. - - - -## Examples - The following example creates a and sets some of its properties. - + . + + If the property is not null and the transaction has already been committed or rolled back, is set to null. + + + +## Examples + The following example creates a and sets some of its properties. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData SqlCommand.Connection Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData SqlCommand.Connection Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData SqlCommand.Connection Example/VB/source.vb" id="Snippet1"::: + ]]> The property was changed while the command was enlisted in a transaction. @@ -2051,11 +2051,11 @@ public class A { Creates a new instance of a object. A object. - method is a strongly-typed version of . - + method is a strongly-typed version of . + ]]> Connecting and Retrieving Data in ADO.NET @@ -2308,24 +2308,24 @@ public class A { Finishes asynchronous execution of a Transact-SQL statement. The number of rows affected (the same behavior as ). - 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 . - + 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 . + ]]> parameter is null ( in Microsoft Visual Basic) was called more than once for a single command execution, or the method was mismatched against its execution method (for example, the code called to complete execution of a call to . - The amount of time specified in elapsed and the asynchronous operation specified with is not complete. - + The amount of time specified in elapsed and the asynchronous operation specified with is not complete. + -or- In some situations, can be set to incorrectly. If this occurs and is called, EndExecuteNonQuery could raise a SqlException error if the amount of time specified in elapsed and the asynchronous operation specified with is not complete. To correct this situation, you should either increase the value of CommandTimeout or reduce the work being done by the asynchronous operation. @@ -2359,23 +2359,23 @@ In some situations, can be set to System.Data.SqlClient.SqlDataReader - + The returned by the call to . Finishes asynchronous execution of a Transact-SQL statement, returning the requested . A object that can be used to retrieve the requested rows. - 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 . - + 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 . + ]]> @@ -2421,16 +2421,16 @@ In some situations, can be set to Finishes asynchronous execution of a Transact-SQL statement, returning the requested data as XML. An object that can be used to fetch the resulting XML data. - 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 . - + 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 . + ]]> @@ -2570,13 +2570,13 @@ In some situations, can be set to Executes a Transact-SQL statement against the connection and returns the number of rows affected. The number of rows affected. - 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. - + 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. + 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. When a trigger exists on a table being inserted or updated, the return value includes the number of rows affected by both the insert or update operation and the number of rows affected by the trigger or triggers. @@ -2587,24 +2587,24 @@ 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. - +## 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. + :::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/VS_Snippets_ADO.NET/Classic WebData SqlCommand.ExecuteNonQuery Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData SqlCommand.ExecuteNonQuery Example/VB/source.vb" id="Snippet1"::: + ]]> - A other than **Binary** or **VarBinary** was used when was set to . For more information about streaming, see [SqlClient Streaming Support](/dotnet/framework/data/adonet/sqlclient-streaming-support). + A other than **Binary** or **VarBinary** was used when was set to . For more information about streaming, see [SqlClient Streaming Support](/dotnet/framework/data/adonet/sqlclient-streaming-support). -or- - A other than **Char**, **NChar**, **NVarChar**, **VarChar**, or **Xml** was used when was set to . + A other than **Char**, **NChar**, **NVarChar**, **VarChar**, or **Xml** was used when was set to . -or- A other than **Xml** was used when was set to . - An exception occurred while executing the command against a locked row. This exception is not generated when you are using Microsoft .NET Framework version 1.0. + An exception occurred while executing the command against a locked row. This exception is not generated when you are using Microsoft .NET Framework version 1.0. -or- @@ -2654,37 +2654,37 @@ If no statements are detected that contribute to the count, the return value is An asynchronous version of , which executes a Transact-SQL statement against the connection and returns the number of rows affected. The cancellation token can be used to request that the operation be abandoned before the command timeout elapses. Exceptions will be reported via the returned Task object. A task representing the asynchronous operation. - , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . ]]> - A other than **Binary** or **VarBinary** was used when was set to . For more information about streaming, see [SqlClient Streaming Support](/dotnet/framework/data/adonet/sqlclient-streaming-support). + A other than **Binary** or **VarBinary** was used when was set to . For more information about streaming, see [SqlClient Streaming Support](/dotnet/framework/data/adonet/sqlclient-streaming-support). -or- -A other than **Char**, **NChar**, **NVarChar**, **VarChar**, or **Xml** was used when was set to . +A other than **Char**, **NChar**, **NVarChar**, **VarChar**, or **Xml** was used when was set to . -or- A other than **Xml** was used when was set to . - Calling more than once for the same instance before task completion. + Calling more than once for the same instance before task completion. -or- -The closed or dropped during a streaming operation. For more information about streaming, see [SqlClient Streaming Support](/dotnet/framework/data/adonet/sqlclient-streaming-support). +The closed or dropped during a streaming operation. For more information about streaming, see [SqlClient Streaming Support](/dotnet/framework/data/adonet/sqlclient-streaming-support). -or- - + is specified in the connection string. - SQL Server returned an error while executing the command text. + SQL Server returned an error while executing the command text. -or- - + A timeout occurred during a streaming operation. For more information about streaming, see [SqlClient Streaming Support](/dotnet/framework/data/adonet/sqlclient-streaming-support). An error occurred in a , or object during a streaming operation. For more information about streaming, see [SqlClient Streaming Support](/dotnet/framework/data/adonet/sqlclient-streaming-support). The , or object was closed during a streaming operation. For more information about streaming, see [SqlClient Streaming Support](/dotnet/framework/data/adonet/sqlclient-streaming-support). @@ -2740,43 +2740,43 @@ The closed or dropped durin Sends the to the and builds a . A object. - 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 . - + 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. - - The multiple active result set (MARS) feature allows for multiple actions using the same connection. - +> 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. - - - -## Examples - The following example creates a , and then executes it by passing a string that is a Transact-SQL SELECT statement, and a string to use to connect to the data source. - + + + +## Examples + The following example creates a , and then executes it by passing a string that is a Transact-SQL 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.ExecuteReader Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData SqlCommand.ExecuteReader Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData SqlCommand.ExecuteReader Example/VB/source.vb" id="Snippet1"::: + ]]> - A other than **Binary** or **VarBinary** was used when was set to . For more information about streaming, see [SqlClient Streaming Support](/dotnet/framework/data/adonet/sqlclient-streaming-support). + A other than **Binary** or **VarBinary** was used when was set to . For more information about streaming, see [SqlClient Streaming Support](/dotnet/framework/data/adonet/sqlclient-streaming-support). -or- - A other than **Char**, **NChar**, **NVarChar**, **VarChar**, or **Xml** was used when was set to . + A other than **Char**, **NChar**, **NVarChar**, **VarChar**, or **Xml** was used when was set to . -or- A other than **Xml** was used when was set to . - An exception occurred while executing the command against a locked row. This exception is not generated when you are using Microsoft .NET Framework version 1.0. + An exception occurred while executing the command against a locked row. This exception is not generated when you are using Microsoft .NET Framework version 1.0. -or- A timeout occurred during a streaming operation. For more information about streaming, see [SqlClient Streaming Support](/dotnet/framework/data/adonet/sqlclient-streaming-support). - The current state of the connection is closed. requires an open . + The current state of the connection is closed. requires an open . -or- @@ -2829,33 +2829,33 @@ The closed or dropped durin Sends the to the , and builds a using one of the values. A object. - 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 . - + 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. - +> 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. - - - -## Examples - The following example creates a , and then executes it by passing a string that is a Transact-SQL SELECT statement, and a string to use to connect to the data source. is set to . - + + + +## Examples + The following example creates a , and then executes it by passing a string that is a Transact-SQL SELECT statement, and a string to use to connect to the data source. is set to . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData SqlCommand.ExecuteReader2/CS/mysample.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData SqlCommand.ExecuteReader2/VB/mysample.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData SqlCommand.ExecuteReader2/VB/mysample.vb" id="Snippet1"::: + ]]> - A other than **Binary** or **VarBinary** was used when was set to . For more information about streaming, see [SqlClient Streaming Support](/dotnet/framework/data/adonet/sqlclient-streaming-support). + A other than **Binary** or **VarBinary** was used when was set to . For more information about streaming, see [SqlClient Streaming Support](/dotnet/framework/data/adonet/sqlclient-streaming-support). -or- - A other than **Char**, **NChar**, **NVarChar**, **VarChar**, or **Xml** was used when was set to . + A other than **Char**, **NChar**, **NVarChar**, **VarChar**, or **Xml** was used when was set to . -or- @@ -2877,11 +2877,11 @@ The closed or dropped durin Initiates the asynchronous execution of the Transact-SQL statement or stored procedure that is described by this . - ADO.NET Overview @@ -2922,35 +2922,35 @@ The closed or dropped durin An asynchronous version of , which sends the to the and builds a . Exceptions will be reported via the returned Task object. A task representing the asynchronous operation. - , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . ]]> - A other than **Binary** or **VarBinary** was used when was set to . For more information about streaming, see [SqlClient Streaming Support](/dotnet/framework/data/adonet/sqlclient-streaming-support). + A other than **Binary** or **VarBinary** was used when was set to . For more information about streaming, see [SqlClient Streaming Support](/dotnet/framework/data/adonet/sqlclient-streaming-support). -or- - A other than **Char**, **NChar**, **NVarChar**, **VarChar**, or **Xml** was used when was set to . + A other than **Char**, **NChar**, **NVarChar**, **VarChar**, or **Xml** was used when was set to . -or- A other than **Xml** was used when was set to . An invalid value. - Calling more than once for the same instance before task completion. + Calling more than once for the same instance before task completion. -or- - The closed or dropped during a streaming operation. For more information about streaming, see [SqlClient Streaming Support](/dotnet/framework/data/adonet/sqlclient-streaming-support). + The closed or dropped during a streaming operation. For more information about streaming, see [SqlClient Streaming Support](/dotnet/framework/data/adonet/sqlclient-streaming-support). -or- is specified in the connection string. - SQL Server returned an error while executing the command text. + SQL Server returned an error while executing the command text. -or- @@ -2998,35 +2998,35 @@ The closed or dropped durin An asynchronous version of , which sends the to the , and builds a . Exceptions will be reported via the returned Task object. A task representing the asynchronous operation. - , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . ]]> - A other than **Binary** or **VarBinary** was used when was set to . For more information about streaming, see [SqlClient Streaming Support](/dotnet/framework/data/adonet/sqlclient-streaming-support). + A other than **Binary** or **VarBinary** was used when was set to . For more information about streaming, see [SqlClient Streaming Support](/dotnet/framework/data/adonet/sqlclient-streaming-support). -or- - A other than **Char**, **NChar**, **NVarChar**, **VarChar**, or **Xml** was used when was set to . + A other than **Char**, **NChar**, **NVarChar**, **VarChar**, or **Xml** was used when was set to . -or- A other than **Xml** was used when was set to . An invalid value. - Calling more than once for the same instance before task completion. + Calling more than once for the same instance before task completion. -or- - The closed or dropped during a streaming operation. For more information about streaming, see [SqlClient Streaming Support](/dotnet/framework/data/adonet/sqlclient-streaming-support). + The closed or dropped during a streaming operation. For more information about streaming, see [SqlClient Streaming Support](/dotnet/framework/data/adonet/sqlclient-streaming-support). -or- is specified in the connection string. - SQL Server returned an error while executing the command text. + SQL Server returned an error while executing the command text. -or- @@ -3071,40 +3071,40 @@ The closed or dropped durin The cancellation instruction. - An asynchronous version of , which sends the to the and builds a . - + An asynchronous version of , which sends the to the and builds a . + The cancellation token can be used to request that the operation be abandoned before the command timeout elapses. Exceptions will be reported via the returned Task object. A task representing the asynchronous operation. - , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . ]]> - A other than **Binary** or **VarBinary** was used when was set to . For more information about streaming, see [SqlClient Streaming Support](/dotnet/framework/data/adonet/sqlclient-streaming-support). + A other than **Binary** or **VarBinary** was used when was set to . For more information about streaming, see [SqlClient Streaming Support](/dotnet/framework/data/adonet/sqlclient-streaming-support). -or- -A other than **Char**, **NChar**, **NVarChar**, **VarChar**, or **Xml** was used when was set to . +A other than **Char**, **NChar**, **NVarChar**, **VarChar**, or **Xml** was used when was set to . -or- - + A other than **Xml** was used when was set to . An invalid value. - Calling more than once for the same instance before task completion. + Calling more than once for the same instance before task completion. -or- -The closed or dropped during a streaming operation. For more information about streaming, see [SqlClient Streaming Support](/dotnet/framework/data/adonet/sqlclient-streaming-support). +The closed or dropped during a streaming operation. For more information about streaming, see [SqlClient Streaming Support](/dotnet/framework/data/adonet/sqlclient-streaming-support). -or- is specified in the connection string. - SQL Server returned an error while executing the command text. + SQL Server returned an error while executing the command text. -or- @@ -3152,40 +3152,40 @@ A timeout occurred during a streaming operation. For more information about stre Options for statement execution and data retrieval. When is set to , reads the entire row before returning a complete Task. The cancellation instruction. - An asynchronous version of , which sends the to the , and builds a - + An asynchronous version of , which sends the to the , and builds a + The cancellation token can be used to request that the operation be abandoned before the command timeout elapses. Exceptions will be reported via the returned Task object. A task representing the asynchronous operation. - , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . ]]> - A other than **Binary** or **VarBinary** was used when was set to . For more information about streaming, see [SqlClient Streaming Support](/dotnet/framework/data/adonet/sqlclient-streaming-support). + A other than **Binary** or **VarBinary** was used when was set to . For more information about streaming, see [SqlClient Streaming Support](/dotnet/framework/data/adonet/sqlclient-streaming-support). -or- -A other than **Char**, **NChar**, **NVarChar**, **VarChar**, or **Xml** was used when was set to . +A other than **Char**, **NChar**, **NVarChar**, **VarChar**, or **Xml** was used when was set to . -or- A other than **Xml** was used when was set to . An invalid value. - Calling more than once for the same instance before task completion. + Calling more than once for the same instance before task completion. -or- -The closed or dropped during a streaming operation. For more information about streaming, see [SqlClient Streaming Support](/dotnet/framework/data/adonet/sqlclient-streaming-support). +The closed or dropped during a streaming operation. For more information about streaming, see [SqlClient Streaming Support](/dotnet/framework/data/adonet/sqlclient-streaming-support). -or- is specified in the connection string. - SQL Server returned an error while executing the command text. + SQL Server returned an error while executing the command text. -or- @@ -3241,36 +3241,36 @@ A timeout occurred during a streaming operation. For more information about stre Executes the query, and returns the first column of the first row in the result set returned by the query. Additional columns or rows are ignored. The first column of the first row in the result set, or a null reference ( in Visual Basic) if the result set is empty. Returns a maximum of 2033 characters. - 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: - + 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: + ```csharp -cmd.CommandText = "SELECT COUNT(*) FROM dbo.region"; -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. - +cmd.CommandText = "SELECT COUNT(*) FROM dbo.region"; +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. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks SqlCommand.ExecuteScalar/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/DataWorks SqlCommand.ExecuteScalar/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/DataWorks SqlCommand.ExecuteScalar/VB/source.vb" id="Snippet1"::: + ]]> - A other than **Binary** or **VarBinary** was used when was set to . For more information about streaming, see [SqlClient Streaming Support](/dotnet/framework/data/adonet/sqlclient-streaming-support). + A other than **Binary** or **VarBinary** was used when was set to . For more information about streaming, see [SqlClient Streaming Support](/dotnet/framework/data/adonet/sqlclient-streaming-support). -or- -A other than **Char**, **NChar**, **NVarChar**, **VarChar**, or **Xml** was used when was set to . +A other than **Char**, **NChar**, **NVarChar**, **VarChar**, or **Xml** was used when was set to . -or- A other than **Xml** was used when was set to . - An exception occurred while executing the command against a locked row. This exception is not generated when you are using Microsoft .NET Framework version 1.0. + An exception occurred while executing the command against a locked row. This exception is not generated when you are using Microsoft .NET Framework version 1.0. -or- @@ -3317,39 +3317,39 @@ A timeout occurred during a streaming operation. For more information about stre The cancellation instruction. - An asynchronous version of , which executes the query asynchronously and returns the first column of the first row in the result set returned by the query. Additional columns or rows are ignored. - + An asynchronous version of , which executes the query asynchronously and returns the first column of the first row in the result set returned by the query. Additional columns or rows are ignored. + The cancellation token can be used to request that the operation be abandoned before the command timeout elapses. Exceptions will be reported via the returned Task object. A task representing the asynchronous operation. - , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . ]]> - A other than **Binary** or **VarBinary** was used when was set to . For more information about streaming, see [SqlClient Streaming Support](/dotnet/framework/data/adonet/sqlclient-streaming-support). + A other than **Binary** or **VarBinary** was used when was set to . For more information about streaming, see [SqlClient Streaming Support](/dotnet/framework/data/adonet/sqlclient-streaming-support). -or- -A other than **Char**, **NChar**, **NVarChar**, **VarChar**, or **Xml** was used when was set to . +A other than **Char**, **NChar**, **NVarChar**, **VarChar**, or **Xml** was used when was set to . -or- A other than **Xml** was used when was set to . - Calling more than once for the same instance before task completion. + Calling more than once for the same instance before task completion. -or- -The closed or dropped during a streaming operation. For more information about streaming, see [SqlClient Streaming Support](/dotnet/framework/data/adonet/sqlclient-streaming-support). +The closed or dropped during a streaming operation. For more information about streaming, see [SqlClient Streaming Support](/dotnet/framework/data/adonet/sqlclient-streaming-support). -or- is specified in the connection string. - SQL Server returned an error while executing the command text. + SQL Server returned an error while executing the command text. -or- @@ -3397,44 +3397,44 @@ A timeout occurred during a streaming operation. For more information about stre Sends the to the and builds an object. An object. - 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: - + 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: + ```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. - - The multiple active result set (MARS) feature allows for multiple actions using the same connection. - +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. + + 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. -## 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. - +## 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. + :::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/VS_Snippets_ADO.NET/Classic WebData SqlCommand.ExecuteXmlReader/VB/mysample.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData SqlCommand.ExecuteXmlReader/VB/mysample.vb" id="Snippet1"::: + ]]> - A other than **Binary** or **VarBinary** was used when was set to . For more information about streaming, see [SqlClient Streaming Support](/dotnet/framework/data/adonet/sqlclient-streaming-support). + A other than **Binary** or **VarBinary** was used when was set to . For more information about streaming, see [SqlClient Streaming Support](/dotnet/framework/data/adonet/sqlclient-streaming-support). -or- -A other than **Char**, **NChar**, **NVarChar**, **VarChar**, or **Xml** was used when was set to . +A other than **Char**, **NChar**, **NVarChar**, **VarChar**, or **Xml** was used when was set to . -or- A other than **Xml** was used when was set to . - An exception occurred while executing the command against a locked row. This exception is not generated when you are using Microsoft .NET Framework version 1.0. + An exception occurred while executing the command against a locked row. This exception is not generated when you are using Microsoft .NET Framework version 1.0. -or- @@ -3489,42 +3489,42 @@ A timeout occurred during a streaming operation. For more information about stre - An asynchronous version of , which sends the to the and builds an object. - + An asynchronous version of , which sends the to the and builds an object. + Exceptions will be reported via the returned Task object. A task representing the asynchronous operation. - , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . ]]> - A other than **Binary** or **VarBinary** was used when was set to . For more information about streaming, see [SqlClient Streaming Support](/dotnet/framework/data/adonet/sqlclient-streaming-support). + A other than **Binary** or **VarBinary** was used when was set to . For more information about streaming, see [SqlClient Streaming Support](/dotnet/framework/data/adonet/sqlclient-streaming-support). -or- -A other than **Char**, **NChar**, **NVarChar**, **VarChar**, or **Xml** was used when was set to . +A other than **Char**, **NChar**, **NVarChar**, **VarChar**, or **Xml** was used when was set to . -or- A other than **Xml** was used when was set to . - Calling more than once for the same instance before task completion. + Calling more than once for the same instance before task completion. -or- -The closed or dropped during a streaming operation. For more information about streaming, see [SqlClient Streaming Support](/dotnet/framework/data/adonet/sqlclient-streaming-support). +The closed or dropped during a streaming operation. For more information about streaming, see [SqlClient Streaming Support](/dotnet/framework/data/adonet/sqlclient-streaming-support). -or- is specified in the connection string. - SQL Server returned an error while executing the command text. + SQL Server returned an error while executing the command text. -or- @@ -3569,42 +3569,42 @@ A timeout occurred during a streaming operation. For more information about stre The cancellation instruction. - An asynchronous version of , which sends the to the and builds an object. - + An asynchronous version of , which sends the to the and builds an object. + The cancellation token can be used to request that the operation be abandoned before the command timeout elapses. Exceptions will be reported via the returned Task object. A task representing the asynchronous operation. - , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . ]]> - A other than **Binary** or **VarBinary** was used when was set to . For more information about streaming, see [SqlClient Streaming Support](/dotnet/framework/data/adonet/sqlclient-streaming-support). + A other than **Binary** or **VarBinary** was used when was set to . For more information about streaming, see [SqlClient Streaming Support](/dotnet/framework/data/adonet/sqlclient-streaming-support). -or- -A other than **Char**, **NChar**, **NVarChar**, **VarChar**, or **Xml** was used when was set to . +A other than **Char**, **NChar**, **NVarChar**, **VarChar**, or **Xml** was used when was set to . -or- A other than **Xml** was used when was set to . - Calling more than once for the same instance before task completion. + Calling more than once for the same instance before task completion. -or- -The closed or dropped during a streaming operation. For more information about streaming, see [SqlClient Streaming Support](/dotnet/framework/data/adonet/sqlclient-streaming-support). +The closed or dropped during a streaming operation. For more information about streaming, see [SqlClient Streaming Support](/dotnet/framework/data/adonet/sqlclient-streaming-support). -or- is specified in the connection string. - SQL Server returned an error while executing the command text. + SQL Server returned an error while executing the command text. -or- @@ -3655,11 +3655,11 @@ A timeout occurred during a streaming operation. For more information about stre Gets or sets a value that specifies the object bound to this command. When set to null (default), no notification should be requested. - Using Query Notifications @@ -3698,13 +3698,13 @@ A timeout occurred during a streaming operation. For more information about stre if the application should automatically receive query notifications; otherwise . The default value is . - Using Query Notifications @@ -3759,24 +3759,24 @@ A timeout occurred during a streaming operation. For more information about stre Gets the . The parameters of the Transact-SQL statement or stored procedure. The default is an empty collection. - [!NOTE] -> If the parameters in the collection do not match the requirements of the query to be executed, an error may result. - - For more information, see [Configuring Parameters and Parameter Data Types](/dotnet/framework/data/adonet/configuring-parameters-and-parameter-data-types). - -## Examples - The following example demonstrates how to create a and add parameters to the . - +> If the parameters in the collection do not match the requirements of the query to be executed, an error may result. + + For more information, see [Configuring Parameters and Parameter Data Types](/dotnet/framework/data/adonet/configuring-parameters-and-parameter-data-types). + +## Examples + The following example demonstrates how to create a and add parameters to the . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks SqlParameterCollection.AddWithValue/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/DataWorks SqlParameterCollection.AddWithValue/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/DataWorks SqlParameterCollection.AddWithValue/VB/source.vb" id="Snippet1"::: + ]]> Connecting and Retrieving Data in ADO.NET @@ -3828,28 +3828,28 @@ A timeout occurred during a streaming operation. For more information about stre Creates a prepared version of the command on an instance of SQL Server. - 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. - + 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. + > [!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 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 . - - 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. - +> 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. + + 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. + +## Examples + 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/VS_Snippets_ADO.NET/Classic WebData SqlCommand.Prepare/VB/Source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData SqlCommand.Prepare/VB/Source.vb" id="Snippet1"::: + ]]> Connecting and Retrieving Data in ADO.NET @@ -3888,11 +3888,11 @@ A timeout occurred during a streaming operation. For more information about stre Resets the property to its default value. - is 30 seconds. - + is 30 seconds. + ]]> Connecting and Retrieving Data in ADO.NET @@ -4128,11 +4128,11 @@ This member is an explicit interface member implementation. It can be used only Gets or sets the within which the executes. The . The default value is . - property if it is already set to a specific value, and the command is in the process of executing. If you set the transaction property to a object that is not connected to the same as the object, an exception is thrown the next time that you attempt to execute a statement. - + property if it is already set to a specific value, and the command is in the process of executing. If you set the transaction property to a object that is not connected to the same as the object, an exception is thrown the next time that you attempt to execute a statement. + ]]> Performing a Transaction @@ -4193,13 +4193,13 @@ This member is an explicit interface member implementation. It can be used only Gets or sets how command results are applied to the when used by the **Update** method of the . One of the values. - value is **Both** unless the command is automatically generated (as in the case of the ), in which case the default is **None**. - - For more information about using the **UpdatedRowSource** property, see [DataAdapter Parameters](/dotnet/framework/data/adonet/dataadapter-parameters). - + value is **Both** unless the command is automatically generated (as in the case of the ), in which case the default is **None**. + + For more information about using the **UpdatedRowSource** property, see [DataAdapter Parameters](/dotnet/framework/data/adonet/dataadapter-parameters). + ]]> Connecting and Retrieving Data in ADO.NET diff --git a/xml/System.Data.SqlClient/SqlConnection.xml b/xml/System.Data.SqlClient/SqlConnection.xml index 74de933145b..aca3161d505 100644 --- a/xml/System.Data.SqlClient/SqlConnection.xml +++ b/xml/System.Data.SqlClient/SqlConnection.xml @@ -1891,7 +1891,7 @@ The is similar to System.Void - + A reference to an existing in which to enlist. diff --git a/xml/System.Data.SqlClient/SqlConnectionStringBuilder.xml b/xml/System.Data.SqlClient/SqlConnectionStringBuilder.xml index bdfc00b1c41..4400725d733 100644 --- a/xml/System.Data.SqlClient/SqlConnectionStringBuilder.xml +++ b/xml/System.Data.SqlClient/SqlConnectionStringBuilder.xml @@ -1243,7 +1243,7 @@ False System.Void - + To be added. diff --git a/xml/System.Data.SqlClient/SqlDataAdapter.xml b/xml/System.Data.SqlClient/SqlDataAdapter.xml index 4f976837f44..db9fcd1043a 100644 --- a/xml/System.Data.SqlClient/SqlDataAdapter.xml +++ b/xml/System.Data.SqlClient/SqlDataAdapter.xml @@ -76,35 +76,35 @@ Represents a set of data commands and a database connection that are used to fill the and update a SQL Server database. This class cannot be inherited. - , 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. - + , 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. - - 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. - - 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. - +> 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. + + 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. + + 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). - - - -## Examples - The following example uses the , , and to select records from a database and populate a with the selected rows. The filled is then returned. To accomplish this, the method is passed an initialized , a connection string, and a query string that is a Transact-SQL SELECT statement. - + + + +## Examples + The following example uses the , , and to select records from a database and populate a with the selected rows. The filled is then returned. To accomplish this, the method is passed an initialized , a connection string, and a query string that is a Transact-SQL SELECT statement. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData SqlDataAdapter Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData SqlDataAdapter Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData SqlDataAdapter Example/VB/source.vb" id="Snippet1"::: + ]]> DataAdapters and DataReaders @@ -150,26 +150,26 @@ Initializes a new instance of the class. - is created, the following read/write properties are set to the following initial values. - -|Properties|Initial value| -|----------------|-------------------| -||`MissingMappingAction.Passthrough`| -||`MissingSchemaAction.Add`| - - You can change the value of any of these properties through a separate call to the property. - - - -## Examples - The following example creates a and sets some of its properties. - + is created, the following read/write properties are set to the following initial values. + +|Properties|Initial value| +|----------------|-------------------| +||`MissingMappingAction.Passthrough`| +||`MissingSchemaAction.Add`| + + You can change the value of any of these properties through a separate call to the property. + + + +## Examples + The following example creates a and sets some of its properties. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData SqlDataAdapter.SqlDataAdapter Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData SqlDataAdapter.SqlDataAdapter Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData SqlDataAdapter.SqlDataAdapter Example/VB/source.vb" id="Snippet1"::: + ]]> Manipulating Data (ADO.NET) @@ -208,30 +208,30 @@ A that is a Transact-SQL SELECT statement or stored procedure and is set as the property of the . Initializes a new instance of the class with the specified as the property. - constructor sets the property to the value specified in the `selectCommand` parameter. - - 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`| - - 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. - - - -## Examples - The following example creates a and sets some of its properties. - + constructor sets the property to the value specified in the `selectCommand` parameter. + + 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`| + + 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. + + + +## Examples + The following example creates a and sets some of its properties. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData SqlDataAdapter.SqlDataAdapter1 Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData SqlDataAdapter.SqlDataAdapter1 Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData SqlDataAdapter.SqlDataAdapter1 Example/VB/source.vb" id="Snippet1"::: + ]]> Manipulating Data (ADO.NET) @@ -272,28 +272,28 @@ A that represents the connection. If your connection string does not use , you can use to pass the user ID and password more securely than by specifying the user ID and password as text in the connection string. Initializes a new instance of the class with a and a object. - 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`| - - You can change the value of either of these properties through a separate call to the property. - - - -## Examples - The following example creates a and sets some of its properties. - + 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`| + + You can change the value of either of these properties through a separate call to the property. + + + +## Examples + The following example creates a and sets some of its properties. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData SqlDataAdapter.SqlDataAdapter3 Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData SqlDataAdapter.SqlDataAdapter3 Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData SqlDataAdapter.SqlDataAdapter3 Example/VB/source.vb" id="Snippet1"::: + ]]> Manipulating Data (ADO.NET) @@ -334,28 +334,28 @@ The connection string. If your connection string does not use , you can use and to pass the user ID and password more securely than by specifying the user ID and password as text in the connection string. Initializes a new instance of the class with a and a connection string. - constructor uses the `selectCommandText` parameter to set the property. The will create and maintain the connection created with the `selectConnectionString` parameter. - - 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`| - - You can change the value of any of these properties through a separate call to the property. - - - -## Examples - The following example creates a and sets some of its properties. - + constructor uses the `selectCommandText` parameter to set the property. The will create and maintain the connection created with the `selectConnectionString` parameter. + + 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`| + + You can change the value of any of these properties through a separate call to the property. + + + +## Examples + The following example creates a and sets some of its properties. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData SqlDataAdapter.SqlDataAdapter2 Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData SqlDataAdapter.SqlDataAdapter2 Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData SqlDataAdapter.SqlDataAdapter2 Example/VB/source.vb" id="Snippet1"::: + ]]> Manipulating Data (ADO.NET) @@ -384,7 +384,7 @@ System.Int32 - + To be added. @@ -441,10 +441,10 @@ System.Data.Common.RowUpdatedEventArgs - - - - + + + + To be added. @@ -478,10 +478,10 @@ System.Data.Common.RowUpdatingEventArgs - - - - + + + + To be added. @@ -546,23 +546,23 @@ Gets or sets a Transact-SQL statement or stored procedure to delete records from the data set. A used during to delete records in the database that correspond to deleted rows in the . - , 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. - - 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. - + , 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. + + 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. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks SqlDataAdapter.Command/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/DataWorks SqlDataAdapter.Command/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/DataWorks SqlDataAdapter.Command/VB/source.vb" id="Snippet1"::: + ]]> Manipulating Data (ADO.NET) @@ -645,8 +645,8 @@ System.Data.IDataParameter - - + + To be added. @@ -769,25 +769,25 @@ Gets or sets a Transact-SQL statement or stored procedure to insert new records into the data source. A used during to insert records into the database that correspond to new rows in the . - , 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. - - 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. - - - -## Examples - The following example creates a and sets the , , , and properties. It assumes you have already created a object. - + , 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. + + 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. + + + +## Examples + 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/VS_Snippets_ADO.NET/DataWorks SqlDataAdapter.Command/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/DataWorks SqlDataAdapter.Command/VB/source.vb" id="Snippet1"::: + ]]> Manipulating Data (ADO.NET) @@ -903,41 +903,41 @@ Occurs during after a command is executed against the data source. The attempt to update is made, so the event fires. - , 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. - -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 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) - + , 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. + +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 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 SqlDataAdapter.RowUpdated Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData SqlDataAdapter.RowUpdated Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData SqlDataAdapter.RowUpdated Example/VB/source.vb" id="Snippet1"::: + ]]> Manipulating Data (ADO.NET) @@ -981,41 +981,41 @@ Occurs during before a command is executed against the data source. The attempt to update is made, so the event fires. - , 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. - -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 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) - + , 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. + +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 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 SqlDataAdapter.RowUpdated Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData SqlDataAdapter.RowUpdated Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData SqlDataAdapter.RowUpdated Example/VB/source.vb" id="Snippet1"::: + ]]> Manipulating Data (ADO.NET) @@ -1076,21 +1076,21 @@ Gets or sets a Transact-SQL statement or stored procedure used to select records in the data source. A used during to select records from the database for placement in the . - 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. - - - -## Examples - The following example creates a and sets the , , , and properties. It assumes you have already created a object. - + 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. + + + +## Examples + 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/VS_Snippets_ADO.NET/DataWorks SqlDataAdapter.Command/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/DataWorks SqlDataAdapter.Command/VB/source.vb" id="Snippet1"::: + ]]> Manipulating Data (ADO.NET) @@ -1131,11 +1131,11 @@ For a description of this member, see . An that is used during to delete records in the data source for deleted rows in the data set. - instance is cast to an interface. - + instance is cast to an interface. + ]]> ADO.NET Overview @@ -1174,11 +1174,11 @@ For a description of this member, see . An that is used during to insert records in the data source for new rows in the data set. - instance is cast to an interface. - + instance is cast to an interface. + ]]> ADO.NET Overview @@ -1217,11 +1217,11 @@ For a description of this member, see . An that is used during to select records from data source for placement in the data set. - instance is cast to an interface. - + instance is cast to an interface. + ]]> ADO.NET Overview @@ -1260,11 +1260,11 @@ For a description of this member, see . An that is used during to update records in the data source for modified rows in the data set. - instance is cast to an interface. - + instance is cast to an interface. + ]]> ADO.NET Overview @@ -1305,11 +1305,11 @@ For a description of this member, see . A new object that is a copy of the current instance. - instance is cast to an interface. - + instance is cast to an interface. + ]]> ADO.NET Overview @@ -1369,39 +1369,39 @@ Gets or sets the number of rows that are processed in each round-trip to the server. - The number of rows to process per-batch. - - Value is - - Effect - - 0 - - There is no limit on the batch size. - - 1 - - Disables batch updating. - - >1 - - Changes are sent using batches of operations at a time. - - + The number of rows to process per-batch. + + Value is + + Effect + + 0 + + There is no limit on the batch size. + + 1 + + Disables batch updating. + + >1 + + Changes are sent using batches of operations at a time. + + When setting this to a value other than 1, all the commands associated with the have to have their **UpdatedRowSource** property set to or . An exception is thrown otherwise. - property to update a data source with changes from a . This can increase application performance by reducing the number of round-trips to the server. - - Executing an extremely large batch could decrease performance. Therefore, you should test for the optimum batch size setting before implementing your application. - - An is thrown if the value is set to a number less than zero. - + property to update a data source with changes from a . This can increase application performance by reducing the number of round-trips to the server. + + Executing an extremely large batch could decrease performance. Therefore, you should test for the optimum batch size setting before implementing your application. + + An is thrown if the value is set to a number less than zero. + ]]> Manipulating Data (ADO.NET) @@ -1462,28 +1462,28 @@ Gets or sets a Transact-SQL statement or stored procedure used to update records in the data source. A used during to update records in the database that correspond to modified rows in the . - , 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. - + , 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. + > [!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`. - - 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. - +> 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`. + + 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. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks SqlDataAdapter.Command/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/DataWorks SqlDataAdapter.Command/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/DataWorks SqlDataAdapter.Command/VB/source.vb" id="Snippet1"::: + ]]> Manipulating Data (ADO.NET) diff --git a/xml/System.Data.SqlClient/SqlParameterCollection.xml b/xml/System.Data.SqlClient/SqlParameterCollection.xml index 25fb469cdaa..7a9975034c9 100644 --- a/xml/System.Data.SqlClient/SqlParameterCollection.xml +++ b/xml/System.Data.SqlClient/SqlParameterCollection.xml @@ -71,21 +71,21 @@ Represents a collection of parameters associated with a and their respective mappings to columns in a . This class cannot be inherited. - through the collection. The parameters are used to select data within the data source and populate the . This code assumes that a and a have already been created with the appropriate schema, commands, and connection. - + through the collection. The parameters are used to select data within the data source and populate the . This code assumes that a and a have already been created with the appropriate schema, commands, and connection. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData SqlParameter Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData SqlParameter Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData SqlParameter Example/VB/source.vb" id="Snippet1"::: + ]]> Commands and Parameters (ADO.NET) @@ -145,12 +145,12 @@ Adds the specified object to the . A new object. - The specified in the parameter is already added to this or another . @@ -221,14 +221,14 @@ ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - - + + ## Examples - - The following example demonstrates the implementation of the interface to create a simple, fixed-size list. This code is part of a larger example for the interface. - + + The following example demonstrates the implementation of the interface to create a simple, fixed-size list. This code is part of a larger example for the interface. + :::code language="csharp" source="~/snippets/csharp/System.Collections/IList/Overview/Program.cs" id="Snippet02"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.IList_Implementation/vb/Program.vb" id="Snippet02"::: ]]> @@ -282,12 +282,12 @@ This member is an explicit interface member implementation. It can be used only Adds a to the given the parameter name and the data type. A new object. - Commands and Parameters (ADO.NET) @@ -328,29 +328,29 @@ This member is an explicit interface member implementation. It can be used only System.Data.SqlClient.SqlParameter - - + + The name of the to add to the collection. A . Adds the specified object to the . - A new object. - - Use caution when you are using this overload of the method to specify integer parameter values. Because this overload takes a of type , you must convert the integral value to an type when the value is zero, as the following C# example demonstrates. - -``` -parameters.Add("@pname", Convert.ToInt32(0)); -``` - + A new object. + + Use caution when you are using this overload of the method to specify integer parameter values. Because this overload takes a of type , you must convert the integral value to an type when the value is zero, as the following C# example demonstrates. + +``` +parameters.Add("@pname", Convert.ToInt32(0)); +``` + If you do not perform this conversion, the compiler assumes that you are trying to call the (, ) overload. - The specified in the parameter is already added to this or another . @@ -403,17 +403,17 @@ parameters.Add("@pname", Convert.ToInt32(0)); Adds a to the , given the specified parameter name, and size. A new object. - Commands and Parameters (ADO.NET) @@ -464,12 +464,12 @@ parameters.Add("@pname", Convert.ToInt32(0)); Adds a to the with the parameter name, the data type, and the column length. A new object. - Commands and Parameters (ADO.NET) @@ -617,21 +617,21 @@ parameters.Add("@pname", Convert.ToInt32(0)); Adds a value to the end of the . A object. - 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. - - - -## Examples - The following example demonstrates how to use the `AddWithValue` method. - + 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. + + + +## Examples + The following example demonstrates how to use the `AddWithValue` method. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks SqlParameterCollection.AddWithValue/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/DataWorks SqlParameterCollection.AddWithValue/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/DataWorks SqlParameterCollection.AddWithValue/VB/source.vb" id="Snippet1"::: + ]]> Commands and Parameters (ADO.NET) @@ -689,16 +689,16 @@ parameters.Add("@pname", Convert.ToInt32(0)); ## Remarks 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 - + The following example demonstrates the implementation of the interface to create a simple, fixed-size list. This code is part of a larger example for the interface. - + :::code language="csharp" source="~/snippets/csharp/System.Collections/IList/Overview/Program.cs" id="Snippet02"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.IList_Implementation/vb/Program.vb" id="Snippet02"::: ]]> @@ -823,13 +823,13 @@ 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. - Starting with the .NET Framework 2.0, this method uses the collection's objects' and methods on `item` to determine whether item exists. In the earlier versions of the .NET Framework, this determination was made by using the and methods of the `item` parameter on the objects in the collection. - - + Starting with the .NET Framework 2.0, this method uses the collection's objects' and methods on `item` to determine whether item exists. In the earlier versions of the .NET Framework, this determination was made by using the and methods of the `item` parameter on the objects in the collection. + + ## Examples - + The following example demonstrates the implementation of the interface to create a simple, fixed-size list. This code is part of a larger example for the interface. - + :::code language="csharp" source="~/snippets/csharp/System.Collections/IList/Overview/Program.cs" id="Snippet02"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.IList_Implementation/vb/Program.vb" id="Snippet02"::: @@ -1112,24 +1112,24 @@ 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. - + 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. - + 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 . - + 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 changes are made to the collection, such as adding, modifying, or deleting elements, the behavior of the enumerator is undefined. - - The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - + + The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. + ## 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/VS_Snippets_CLR_System/system.Collections_EnumeratorInterfaces/vb/ienumerator.vb" id="Snippet1"::: @@ -1332,14 +1332,14 @@ 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. - - Starting with the .NET Framework 2.0, this method uses the collection's objects' and methods on `item` to determine whether item exists. In the earlier versions of the .NET Framework, this determination was made by using the and methods of the `item` parameter on the objects in the collection. - - + + Starting with the .NET Framework 2.0, this method uses the collection's objects' and methods on `item` to determine whether item exists. In the earlier versions of the .NET Framework, this determination was made by using the and methods of the `item` parameter on the objects in the collection. + + ## Examples - + The following example demonstrates the implementation of the interface to create a simple, fixed-size list. This code is part of a larger example for the interface. - + :::code language="csharp" source="~/snippets/csharp/System.Collections/IList/Overview/Program.cs" id="Snippet02"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.IList_Implementation/vb/Program.vb" id="Snippet02"::: @@ -1515,17 +1515,17 @@ 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. - - - - If `index` equals the number of items in the , then `value` is appended to the end. - In collections of contiguous elements, such as lists, the elements that follow the insertion point move down to accommodate the new element. If the collection is indexed, the indexes of the elements that are moved are also updated. This behavior does not apply to collections where elements are conceptually grouped into buckets, such as a hash table. - - + + + + If `index` equals the number of items in the , then `value` is appended to the end. + In collections of contiguous elements, such as lists, the elements that follow the insertion point move down to accommodate the new element. If the collection is indexed, the indexes of the elements that are moved are also updated. This behavior does not apply to collections where elements are conceptually grouped into buckets, such as a hash table. + + ## Examples - + The following example demonstrates the implementation of the interface to create a simple, fixed-size list. This code is part of a larger example for the interface. - + :::code language="csharp" source="~/snippets/csharp/System.Collections/IList/Overview/Program.cs" id="Snippet02"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.IList_Implementation/vb/Program.vb" id="Snippet02"::: @@ -1573,16 +1573,16 @@ 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. - - - - A collection with a fixed size does not allow the addition or removal of elements after the collection is created, but it allows the modification of existing elements. - - + + + + A collection with a fixed size does not allow the addition or removal of elements after the collection is created, but it allows the modification of existing elements. + + ## Examples - + The following example demonstrates the implementation of the interface to create a simple, fixed-size list. This code is part of a larger example for the interface. - + :::code language="csharp" source="~/snippets/csharp/System.Collections/IList/Overview/Program.cs" id="Snippet02"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.IList_Implementation/vb/Program.vb" id="Snippet02"::: @@ -1630,14 +1630,14 @@ 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. - - A collection that is read-only does not allow the addition, removal, or modification of elements after the collection is created. - - + + A collection that is read-only does not allow the addition, removal, or modification of elements after the collection is created. + + ## Examples - + The following example demonstrates the implementation of the interface to create a simple, fixed-size list. This code is part of a larger example for the interface. - + :::code language="csharp" source="~/snippets/csharp/System.Collections/IList/Overview/Program.cs" id="Snippet02"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.IList_Implementation/vb/Program.vb" id="Snippet02"::: @@ -1679,13 +1679,13 @@ 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. - + The following code example shows how to lock the collection using the property during the entire enumeration. - + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.collections.icollection/cpp/remarks.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections/ICollection/IsSynchronized/remarks.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.icollection/vb/remarks.vb" id="Snippet1"::: @@ -1758,13 +1758,13 @@ This member is an explicit interface member implementation. It can be used only Gets the at the specified index. The at the specified index. - objects to supply an input parameter to a stored procedure that returns results in an output parameter. The code iterates through the items in the and displays some parameter properties in the console window. This example assumes a valid connection string to the **AdventureWorks** sample database on an instance of SQL Server. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData SqlParameterCollection.Parent Example/CS/source.cs" id="Snippet1"::: - + objects to supply an input parameter to a stored procedure that returns results in an output parameter. The code iterates through the items in the and displays some parameter properties in the console window. This example assumes a valid connection string to the **AdventureWorks** sample database on an instance of SQL Server. + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData SqlParameterCollection.Parent Example/CS/source.cs" id="Snippet1"::: + ]]> The specified index does not exist. @@ -1824,11 +1824,11 @@ This member is an explicit interface member implementation. It can be used only Gets the with the specified name. The with the specified name. - . If the `parameterName` is not valid, an will be thrown. - + . If the `parameterName` is not valid, an will be thrown. + ]]> The specified is not valid. @@ -1886,14 +1886,14 @@ This member is an explicit interface member implementation. It can be used only A object to remove from the collection. Removes the specified from the collection. - object in a collection. If the parameter exists, the example removes it. This example assumes that a collection has already been created by a . - + object in a collection. If the parameter exists, the example removes it. This example assumes that a collection has already been created by a . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData SqlParameterCollection.Remove Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData SqlParameterCollection.Remove Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData SqlParameterCollection.Remove Example/VB/source.vb" id="Snippet1"::: + ]]> The parameter is not a . @@ -1956,13 +1956,13 @@ 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. - - In collections of contiguous elements, such as lists, the elements that follow the removed element move up to occupy the vacated spot. If the collection is indexed, the indexes of the elements that are moved are also updated. This behavior does not apply to collections where elements are conceptually grouped into buckets, such as a hash table. If `value` is not found in the , the remains unchanged and no exception is thrown. - + + In collections of contiguous elements, such as lists, the elements that follow the removed element move up to occupy the vacated spot. If the collection is indexed, the indexes of the elements that are moved are also updated. This behavior does not apply to collections where elements are conceptually grouped into buckets, such as a hash table. If `value` is not found in the , the remains unchanged and no exception is thrown. + ## Examples - + The following example demonstrates the implementation of the interface to create a simple, fixed-size list. This code is part of a larger example for the interface. - + :::code language="csharp" source="~/snippets/csharp/System.Collections/IList/Overview/Program.cs" id="Snippet02"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.IList_Implementation/vb/Program.vb" id="Snippet02"::: @@ -2037,12 +2037,12 @@ 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. - In collections of contiguous elements, such as lists, the elements that follow the removed element move up to occupy the vacated spot. If the collection is indexed, the indexes of the elements that are moved are also updated. This behavior does not apply to collections where elements are conceptually grouped into buckets, such as a hash table. + In collections of contiguous elements, such as lists, the elements that follow the removed element move up to occupy the vacated spot. If the collection is indexed, the indexes of the elements that are moved are also updated. This behavior does not apply to collections where elements are conceptually grouped into buckets, such as a hash table. ## Examples - + The following example demonstrates the implementation of the interface to create a simple, fixed-size list. This code is part of a larger example for the interface. - + :::code language="csharp" source="~/snippets/csharp/System.Collections/IList/Overview/Program.cs" id="Snippet02"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Collections.IList_Implementation/vb/Program.vb" id="Snippet02"::: @@ -2231,24 +2231,24 @@ 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 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. - + + 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: - + :::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"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.icollection/vb/remarks.vb" id="Snippet2"::: - - 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. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.icollection/vb/remarks.vb" id="Snippet2"::: + + 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. + ## Examples - + The following code example shows how to lock the collection using the property during the entire enumeration. - + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.collections.icollection/cpp/remarks.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Collections/ICollection/IsSynchronized/remarks.cs" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Collections/ICollection/IsSynchronized/remarks.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.icollection/vb/remarks.vb" id="Snippet1"::: ]]> diff --git a/xml/System.Data/Constraint.xml b/xml/System.Data/Constraint.xml index f0be4ec9ace..ddf99319f1c 100644 --- a/xml/System.Data/Constraint.xml +++ b/xml/System.Data/Constraint.xml @@ -65,21 +65,21 @@ Represents a constraint that can be enforced on one or more objects. - . For example, when you delete a value that is used in one or more related tables, a determines whether the values in the related tables are also deleted, set to null values, set to default values, or whether no action occurs. A , on the other hand, just makes sure that all values within a particular table are unique. For more information, see [DataTable Constraints](/dotnet/framework/data/adonet/dataset-datatable-dataview/datatable-constraints). - - A base constructor is not used. Primary or unique key constraints are created by using the constructor, and foreign key constraints are created by using the constructor. - - - -## Examples - The following example examines the collection of constraints for a and determines whether each constraint is a or a . The properties of the constraint are then displayed. - + . For example, when you delete a value that is used in one or more related tables, a determines whether the values in the related tables are also deleted, set to null values, set to default values, or whether no action occurs. A , on the other hand, just makes sure that all values within a particular table are unique. For more information, see [DataTable Constraints](/dotnet/framework/data/adonet/dataset-datatable-dataview/datatable-constraints). + + A base constructor is not used. Primary or unique key constraints are created by using the constructor, and foreign key constraints are created by using the constructor. + + + +## Examples + The following example examines the collection of constraints for a and determines whether each constraint is a or a . The properties of the constraint are then displayed. + :::code language="csharp" source="~/snippets/csharp/System.Data/Constraint/Overview/constraint.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData Constraint Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData Constraint Example/VB/source.vb" id="Snippet1"::: + ]]> This type is safe for multithreaded read operations. You must synchronize any write operations. @@ -90,11 +90,11 @@ - - - - - + + + + + Constructor System.Data @@ -117,11 +117,11 @@ Initializes a new instance of the class. - @@ -272,19 +272,19 @@ The name of a constraint in the . The name of the . - is returned by the property of the class. - - - -## Examples - The following example iterates through the of a and prints each . - + is returned by the property of the class. + + + +## Examples + 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/VS_Snippets_ADO.NET/Classic WebData Constraint.ConstraintName Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData Constraint.ConstraintName Example/VB/source.vb" id="Snippet1"::: + ]]> The name is a null value or empty string. @@ -339,11 +339,11 @@ Gets the collection of user-defined constraint properties. A of custom information. - . Properties that are not of type are not persisted when the is written as XML. - + . Properties that are not of type are not persisted when the is written as XML. + ]]> @@ -389,14 +389,14 @@ The to which this constraint will belong. Sets the constraint's . - method to set the for a constraint. - + 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/VS_Snippets_ADO.NET/Classic WebData Constraint.SetDataSet Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData Constraint.SetDataSet Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -454,14 +454,14 @@ Gets the to which the constraint applies. A to which the constraint applies. - of a . - + of a . + :::code language="csharp" source="~/snippets/csharp/System.Data/Constraint/Table/table.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData Constraint.Table Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData Constraint.Table Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -505,14 +505,14 @@ Gets the , if there is one, as a string. The string value of the . - using the method. - + using the method. + :::code language="csharp" source="~/snippets/csharp/System.Data/Constraint/ToString/tostring.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData Constraint.ToString Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData Constraint.ToString Example/VB/source.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.Data/TypedDataSetGeneratorException.xml b/xml/System.Data/TypedDataSetGeneratorException.xml index 80ddf88ab42..4fd6b3d8126 100644 --- a/xml/System.Data/TypedDataSetGeneratorException.xml +++ b/xml/System.Data/TypedDataSetGeneratorException.xml @@ -25,11 +25,11 @@ The exception that is thrown when a name conflict occurs while generating a strongly typed . - class is not intended for use as a stand-alone component, but as a class from which other classes derive standard functionality. - + class is not intended for use as a stand-alone component, but as a class from which other classes derive standard functionality. + ]]> @@ -61,11 +61,11 @@ Initializes a new instance of the class. - class is not intended for use as a stand-alone component, but as a class from which other classes derive standard functionality. - + class is not intended for use as a stand-alone component, but as a class from which other classes derive standard functionality. + ]]> @@ -92,11 +92,11 @@ object containing a dynamic list of exceptions. Initializes a new instance of the class. - class is not intended for use as a stand-alone component, but as a class from which other classes derive standard functionality. - + class is not intended for use as a stand-alone component, but as a class from which other classes derive standard functionality. + ]]> @@ -115,17 +115,17 @@ 4.0.0.0 - + The string to display when the exception is thrown. Initializes a new instance of the class with the specified string. - class is not intended for use as a stand-alone component, but as a class from which other classes derive standard functionality. - + class is not intended for use as a stand-alone component, but as a class from which other classes derive standard functionality. + ]]> @@ -153,11 +153,11 @@ A structure. Initializes a new instance of the class using the specified serialization information and streaming context. - class is not intended for use as a stand-alone component, but as a class from which other classes derive standard functionality. - + class is not intended for use as a stand-alone component, but as a class from which other classes derive standard functionality. + ]]> @@ -176,19 +176,19 @@ 4.0.0.0 - - + + The string to display when the exception is thrown. A reference to an inner exception. Initializes a new instance of the class with the specified string and inner exception. - class is not intended for use as a stand-alone component, but as a class from which other classes derive standard functionality. - + class is not intended for use as a stand-alone component, but as a class from which other classes derive standard functionality. + ]]> @@ -215,11 +215,11 @@ object. - class is not intended for use as a stand-alone component, but as a class from which other classes derive standard functionality. - + class is not intended for use as a stand-alone component, but as a class from which other classes derive standard functionality. + ]]> @@ -250,11 +250,11 @@ A structure. Implements the interface and returns the data needed to serialize the object. - class is not intended for use as a stand-alone component, but as a class from which other classes derive standard functionality. - + class is not intended for use as a stand-alone component, but as a class from which other classes derive standard functionality. + ]]> diff --git a/xml/System.Diagnostics.Tracing/EventSourceException.xml b/xml/System.Diagnostics.Tracing/EventSourceException.xml index ecf056d52ac..5fad8e60198 100644 --- a/xml/System.Diagnostics.Tracing/EventSourceException.xml +++ b/xml/System.Diagnostics.Tracing/EventSourceException.xml @@ -202,8 +202,8 @@ - - + + The object that holds the serialized object data. @@ -255,11 +255,11 @@ The exception that is the cause of the current exception, or if no inner exception is specified. Initializes a new instance of the class with a specified error message and a reference to the inner exception that is the cause of this exception. - property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. - + property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. + ]]> diff --git a/xml/System.Diagnostics/Debug.xml b/xml/System.Diagnostics/Debug.xml index f3816148d11..a949287858b 100644 --- a/xml/System.Diagnostics/Debug.xml +++ b/xml/System.Diagnostics/Debug.xml @@ -108,12 +108,12 @@ 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="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Debug Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Debug/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Debug Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Debug Example/VB/source.vb" id="Snippet1"::: + ]]> This type is thread safe. @@ -226,12 +226,12 @@ 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="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Debug.Assert Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Debug/Assert/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Debug.Assert Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Debug.Assert Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -422,12 +422,12 @@ 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="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Debug.Assert1 Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Debug/Assert/source1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Debug.Assert1 Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Debug.Assert1 Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -628,12 +628,12 @@ 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="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Debug.Assert2 Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Debug/Assert/source2.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Debug.Assert2 Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Debug.Assert2 Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -893,12 +893,12 @@ For .NET Framework apps, you can also set the named `myTextListener`. `myTextListener` uses a called `myOutputWriter` to write to a file named `TestFile.txt`. The example creates the file, stream, and text writer, writes one line of text to the file, and then flushes and closes the output. - +The following example creates a named `myTextListener`. `myTextListener` uses a called `myOutputWriter` to write to a file named `TestFile.txt`. The example creates the file, stream, and text writer, writes one line of text to the file, and then flushes and closes the output. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Debug.Close Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Debug/Close/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Debug.Close Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Debug.Close Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -991,18 +991,18 @@ The following example creates a method to print a message during exception handling. - +The following example uses the method to print a message during exception handling. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Debug.Fail Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Debug/Fail/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Debug.Fail Example/VB/source.vb" id="Snippet1"::: - - You can also use the method in a switch statement. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Debug.Fail Example/VB/source.vb" id="Snippet1"::: + + You can also use the method in a switch statement. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Debug.Fail Example/CPP/source.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Debug/Fail/source.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Debug.Fail Example/VB/source.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Debug.Fail Example/VB/source.vb" id="Snippet2"::: + ]]> @@ -1087,18 +1087,18 @@ The following example uses the method to ## 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="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Debug.Fail1 Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Debug/Fail/source1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Debug.Fail1 Example/VB/source.vb" id="Snippet1"::: - -You can also use the method in a switch statement. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Debug.Fail1 Example/VB/source.vb" id="Snippet1"::: + +You can also use the method in a switch statement. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Debug.Fail1 Example/CPP/source.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Debug/Fail/source1.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Debug.Fail1 Example/VB/source.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Debug.Fail1 Example/VB/source.vb" id="Snippet2"::: + ]]> @@ -1167,12 +1167,12 @@ You can also use the method in a switch ## Examples -The following example creates a named `myTextListener`. `myTextListener` uses a called `myFileStream` to write to a file named `TestFile.txt`. The example creates the stream, opens the file if it exists or creates a new one, writes one line of text to the file, and then flushes and closes the output. - +The following example creates a named `myTextListener`. `myTextListener` uses a called `myFileStream` to write to a file named `TestFile.txt`. The example creates the stream, opens the file if it exists or creates a new one, writes one line of text to the file, and then flushes and closes the output. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Debug.Close Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Debug/Close/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Debug.Close Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Debug.Close Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -1236,23 +1236,23 @@ The following example creates a @@ -1309,23 +1309,23 @@ The property represents the numbe ## Examples -The following example sets the indent level and emits debugging messages. - +The following example sets the indent level and emits debugging messages. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Debug.IndentLevel Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Debug/Indent/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Debug.IndentLevel Example/VB/source.vb" id="Snippet1"::: - - This example produces the following output: - -``` - -List of errors: - Error 1: File not found - Error 2: Directory not found -End of list of errors - -``` - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Debug.IndentLevel Example/VB/source.vb" id="Snippet1"::: + + This example produces the following output: + +``` + +List of errors: + Error 1: File not found + Error 2: Directory not found +End of list of errors + +``` + ]]> @@ -1448,12 +1448,12 @@ For .NET Framework apps, you can also set the 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="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Debug.Listeners Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Debug/Listeners/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Debug.Listeners Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Debug.Listeners Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -1520,7 +1520,7 @@ The following example creates a System.Void - + The message to write. @@ -1583,7 +1583,7 @@ The following example creates a System.Void - + [System.Diagnostics.CodeAnalysis.StringSyntax("CompositeFormat")] @@ -1591,7 +1591,7 @@ The following example creates a - + [System.ParamArray] @@ -1684,23 +1684,23 @@ The following example creates a @@ -1779,16 +1779,16 @@ End of list of errors ## 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. - - 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. - +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. + + 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. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Debug.Write Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Debug/Write/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Debug.Write Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Debug.Write Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -1862,16 +1862,16 @@ The following example creates a named `gen ## 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. - - 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. - +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. + + 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. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Debug.Write Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Debug/Write/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Debug.Write Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Debug.Write Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -1949,16 +1949,16 @@ The following example creates a named `gen ## 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. - - 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. - +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. + + 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. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Debug.Write Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Debug/Write/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Debug.Write Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Debug.Write Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -2036,16 +2036,16 @@ The following example creates a named `gen ## 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. - - 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. - +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. + + 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. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Debug.Write Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Debug/Write/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Debug.Write Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Debug.Write Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -2205,16 +2205,16 @@ This overload was introduced in .NET 6 to improve performance. In comparison to ## 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. - - 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. - +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. + + 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. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Debug.WriteIf1 Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Debug/WriteIf/source1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Debug.WriteIf1 Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Debug.WriteIf1 Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -2306,16 +2306,16 @@ Debug.WriteIf(mySwitch.TraceError, "aNumber = " + aNumber + " out of range"); ## 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. - - 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. - +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. + + 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. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Debug.WriteIf Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Debug/WriteIf/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Debug.WriteIf Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Debug.WriteIf Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -2486,16 +2486,16 @@ This overload was introduced in .NET 6 to improve performance. In comparison to ## 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. - - 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. - +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. + + 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. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Debug.WriteIf3 Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Debug/WriteIf/source3.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Debug.WriteIf3 Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Debug.WriteIf3 Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -2591,16 +2591,16 @@ Debug.WriteIf(mySwitch.TraceError, "aNumber = " + aNumber + " out of range"); ## 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. - - 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. - +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. + + 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. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Debug.WriteIf2 Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Debug/WriteIf/source2.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Debug.WriteIf2 Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Debug.WriteIf2 Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -2702,16 +2702,16 @@ Debug.WriteIf(mySwitch.TraceError, "aNumber = " + aNumber + " out of range"); ## 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. - - 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. - +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. + + 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. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Debug.WriteLine1 Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Debug/WriteLine/source1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Debug.WriteLine1 Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Debug.WriteLine1 Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -2786,16 +2786,16 @@ The following example creates a named `gen ## 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. - - 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. - +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. + + 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. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Debug.WriteLine Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Debug/WriteLine/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Debug.WriteLine Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Debug.WriteLine Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -2873,16 +2873,16 @@ The following example creates a named `gen ## 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. - - 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. - +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. + + 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. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Debug.WriteLine3 Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Debug/WriteLine/source3.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Debug.WriteLine3 Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Debug.WriteLine3 Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -3050,16 +3050,16 @@ The following example creates a named `gen ## 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. - - 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. - +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. + + 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. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Debug.WriteLine2 Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Debug/WriteLine/source2.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Debug.WriteLine2 Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Debug.WriteLine2 Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -3216,16 +3216,16 @@ This overload was introduced in .NET 6 to improve performance. In comparison to ## 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. - - 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. - +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. + + 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. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Debug.WriteLineIf1 Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Debug/WriteLineIf/source1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Debug.WriteLineIf1 Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Debug.WriteLineIf1 Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -3318,16 +3318,16 @@ Debug.WriteLineIf(mySwitch.TraceError, "aNumber = " + aNumber + " out of range") ## 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. - - 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. - +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. + + 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. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Debug.WriteLineIf Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Debug/WriteLineIf/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Debug.WriteLineIf Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Debug.WriteLineIf Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -3497,16 +3497,16 @@ This overload was introduced in .NET 6 to improve performance. In comparison to ## 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. - - 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. - +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. + + 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. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Debug.WriteLineIf3 Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Debug/WriteLineIf/source3.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Debug.WriteLineIf3 Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Debug.WriteLineIf3 Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -3602,16 +3602,16 @@ Debug.WriteLineIf(mySwitch.TraceError, "aNumber = " + aNumber + " out of range") ## 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. - - 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. - +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. + + 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. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Debug.WriteLineIf2 Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Debug/WriteLineIf/source2.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Debug.WriteLineIf2 Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Debug.WriteLineIf2 Example/VB/source.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.Diagnostics/DebuggableAttribute.xml b/xml/System.Diagnostics/DebuggableAttribute.xml index 59455bfaa55..5a6f972048f 100644 --- a/xml/System.Diagnostics/DebuggableAttribute.xml +++ b/xml/System.Diagnostics/DebuggableAttribute.xml @@ -57,17 +57,17 @@ Modifies code generation for runtime just-in-time (JIT) debugging. This class cannot be inherited. - controls how the runtime treats code within the module. The runtime might track extra information about generated code, and it might disable certain optimizations based on the values contained within this attribute. - - 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. - - For more information about using attributes, see [Attributes](/dotnet/standard/attributes/). - + controls how the runtime treats code within the module. The runtime might track extra information about generated code, and it might disable certain optimizations based on the values contained within this attribute. + + 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. + + For more information about using attributes, see [Attributes](/dotnet/standard/attributes/). + ]]> @@ -126,11 +126,11 @@ A bitwise combination of the values specifying the debugging mode for the JIT compiler. Initializes a new instance of the class, using the specified debugging modes for the just-in-time (JIT) compiler. - constructor with a `modes` parameter value of is equivalent to calling the constructor with an `isJITTrackingEnabled` parameter value of `true`. - + constructor with a `modes` parameter value of is equivalent to calling the constructor with an `isJITTrackingEnabled` parameter value of `true`. + ]]> @@ -167,8 +167,8 @@ 9.0.0.0 - - + + @@ -177,15 +177,15 @@ to disable the optimizer for execution; otherwise, . Initializes a new instance of the class, using the specified tracking and optimization options for the just-in-time (JIT) compiler. - 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. - - An `isJITOptimizerDisabled` parameter value of `true` optimizes for debugging; a value of `false` optimizes for execution. - + 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. + + An `isJITOptimizerDisabled` parameter value of `true` optimizes for debugging; a value of `false` optimizes for execution. + ]]> @@ -227,11 +227,11 @@ Gets the debugging modes for the attribute. A bitwise combination of the values describing the debugging mode for the just-in-time (JIT) compiler. The default is . - property controls how the runtime tracks information important to the debugger during code generation. This information helps the debugger provide a rich debugging experience. - + property controls how the runtime tracks information important to the debugger during code generation. This information helps the debugger provide a rich debugging experience. + ]]> @@ -275,11 +275,11 @@ if the runtime optimizer is disabled; otherwise, . - 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. - + 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. + ]]> @@ -323,16 +323,16 @@ if the runtime will track information during code generation for the debugger; otherwise, . - controls whether the runtime tracks information important to the debugger during code generation. This information helps the debugger provide a rich debugging experience. - - Starting with the .NET Framework 2.0, JIT tracking information is always enabled during debugging, and this property value is ignored. - + controls whether the runtime tracks information important to the debugger during code generation. This information helps the debugger provide a rich debugging experience. + + Starting with the .NET Framework 2.0, JIT tracking information is always enabled during debugging, and this property value is ignored. + > [!NOTE] -> This property does not control the ability to debug, but tells the just-in-time (JIT) compiler to generate tracking information. Specifically, the compiler tracks the Microsoft Intermediate Language (MSIL)-offset to the native-code offset within a method. - +> This property does not control the ability to debug, but tells the just-in-time (JIT) compiler to generate tracking information. Specifically, the compiler tracks the Microsoft Intermediate Language (MSIL)-offset to the native-code offset within a method. + ]]> diff --git a/xml/System.Diagnostics/Debugger.xml b/xml/System.Diagnostics/Debugger.xml index b936ffc68bf..b77b4f3804a 100644 --- a/xml/System.Diagnostics/Debugger.xml +++ b/xml/System.Diagnostics/Debugger.xml @@ -156,29 +156,29 @@ Signals a breakpoint to an attached debugger. - [!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. - - - -## Examples - The following code example demonstrates how to stop the debugger at the call to . - -```vb -Debugger.Break() -Console.WriteLine("Hello, world.") -``` - -```csharp -Debugger.Break(); -Console.WriteLine("Hello, world."); -``` - +> 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 . + +```vb +Debugger.Break() +Console.WriteLine("Hello, world.") +``` + +```csharp +Debugger.Break(); +Console.WriteLine("Hello, world."); +``` + ]]> The is not set to break into the debugger. @@ -225,11 +225,11 @@ Console.WriteLine("Hello, world."); Represents the default category of message with a constant. - is used by . - + is used by . + ]]> @@ -388,13 +388,13 @@ Console.WriteLine("Hello, world."); if the startup is successful or if the debugger is already attached; otherwise, . - The is not set to start the debugger. @@ -446,9 +446,9 @@ Debugger launch is only supported on Windows. On Unix operating systems, the met System.Void - - - + + + A description of the importance of the message. @@ -456,14 +456,14 @@ Debugger launch is only supported on Windows. On Unix operating systems, the met The message to show. Posts a message for the attached debugger. - [!NOTE] -> The category parameter is limited to 256 characters. Strings longer than 256 characters are truncated. - +> The category parameter is limited to 256 characters. Strings longer than 256 characters are truncated. + ]]> @@ -517,13 +517,13 @@ Debugger launch is only supported on Windows. On Unix operating systems, the met Notifies a debugger that execution is about to enter a path that involves a cross-thread dependency. - 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. - + 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/ProcessModuleCollection.xml b/xml/System.Diagnostics/ProcessModuleCollection.xml index abef3739cf3..7214f66ad52 100644 --- a/xml/System.Diagnostics/ProcessModuleCollection.xml +++ b/xml/System.Diagnostics/ProcessModuleCollection.xml @@ -66,11 +66,11 @@ Provides a strongly typed collection of objects. - @@ -171,45 +171,6 @@ To be added. - - - - - - - - Method - - System - 2.0.5.0 - - - System.Diagnostics.Process - - - netstandard - - - - System.Obsolete("This API is no longer available", true) - - - [System.Obsolete("This API is no longer available", true)] - [<System.Obsolete("This API is no longer available", true)>] - - - - System.Void - - - - - - To be added. - To be added. - To be added. - - @@ -254,11 +215,11 @@ if the module exists in the collection; otherwise, . - @@ -415,47 +376,6 @@ To be added. - - - - - - - - Method - - System - 2.0.5.0 - - - System.Diagnostics.Process - - - netstandard - - - - System.Obsolete("This API is no longer available", true) - - - [System.Obsolete("This API is no longer available", true)] - [<System.Obsolete("This API is no longer available", true)>] - - - - System.Void - - - - - - - To be added. - To be added. - To be added. - To be added. - - @@ -501,46 +421,6 @@ To be added. - - - - - - - - Method - - System - 2.0.5.0 - - - System.Diagnostics.Process - - - netstandard - - - - System.Obsolete("This API is no longer available", true) - - - [System.Obsolete("This API is no longer available", true)] - [<System.Obsolete("This API is no longer available", true)>] - - - - System.Boolean - - - - - - To be added. - To be added. - To be added. - To be added. - - diff --git a/xml/System.Diagnostics/StackFrame.xml b/xml/System.Diagnostics/StackFrame.xml index 1aee349fc10..e2aac5979ed 100644 --- a/xml/System.Diagnostics/StackFrame.xml +++ b/xml/System.Diagnostics/StackFrame.xml @@ -67,27 +67,27 @@ Provides information about a , which represents a function call on the call stack for the current thread. - is created and pushed on the call stack for every function call made during the execution of a thread. The stack frame always includes information, and optionally includes file name, line number, and column number information. - - information will be most informative with Debug build configurations. By default, Debug builds include debug symbols, while Release builds do not. The debug symbols contain most of the file, method name, line number, and column information used in constructing objects. - - - -## Examples - The following example demonstrates the use of the class to provide the stack frame information for a stack trace. - + is created and pushed on the call stack for every function call made during the execution of a thread. The stack frame always includes information, and optionally includes file name, line number, and column number information. + + information will be most informative with Debug build configurations. By default, Debug builds include debug symbols, while Release builds do not. The debug symbols contain most of the file, method name, line number, and column information used in constructing objects. + + + +## Examples + The following example demonstrates the use of the class to provide the stack frame information for a stack trace. + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/StackFrame/Overview/program.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stackframesample2/vb/program.vb" id="Snippet1"::: - - The following example demonstrates the use of the members of the class. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stackframesample2/vb/program.vb" id="Snippet1"::: + + The following example demonstrates the use of the members of the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/StackFrameSample1/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/StackFrame/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/StackFrameSample1/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/StackFrameSample1/VB/source.vb" id="Snippet1"::: + ]]> @@ -104,11 +104,11 @@ - - - - - + + + + + Constructor mscorlib @@ -177,21 +177,21 @@ - + The number of frames up the stack to skip. Initializes a new instance of the class that corresponds to a frame above the current stack frame. - constructor. This code example is part of a larger example provided for the class. - + constructor. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/StackFrameSample1/CPP/source.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/StackFrame/Overview/source.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/StackFrameSample1/VB/source.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/StackFrameSample1/VB/source.vb" id="Snippet3"::: + ]]> @@ -233,7 +233,7 @@ 9.0.0.0 - + @@ -242,15 +242,15 @@ To be added. Initializes a new instance of the class, optionally capturing source information. - constructor. This code example is part of a larger example provided for the class. - + constructor. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/StackFrameSample1/CPP/source.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/StackFrame/Overview/source.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/StackFrameSample1/VB/source.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/StackFrameSample1/VB/source.vb" id="Snippet2"::: + ]]> @@ -294,28 +294,28 @@ - - + + The file name. The line number in the specified file. Initializes a new instance of the class that contains only the given file name and line number. - constructor. This code example is part of a larger example provided for the class. - + constructor. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/StackFrameSample1/CPP/source.cpp" id="Snippet5"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/StackFrame/Overview/source.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/StackFrameSample1/VB/source.vb" id="Snippet5"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/StackFrameSample1/VB/source.vb" id="Snippet5"::: + ]]> @@ -357,8 +357,8 @@ 9.0.0.0 - - + + @@ -368,15 +368,15 @@ To be added. Initializes a new instance of the class that corresponds to a frame above the current stack frame, optionally capturing source information. - constructor. This code example is part of a larger example provided for the class. - + constructor. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/StackFrameSample1/CPP/source.cpp" id="Snippet4"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/StackFrame/Overview/source.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/StackFrameSample1/VB/source.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/StackFrameSample1/VB/source.vb" id="Snippet4"::: + ]]> @@ -420,9 +420,9 @@ - - - + + + The file name. @@ -430,20 +430,20 @@ The column number in the specified file. Initializes a new instance of the class that contains only the given file name, line number, and column number. - constructor. This code example is part of a larger example provided for the class. - + constructor. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/StackFrameSample1/CPP/source.cpp" id="Snippet6"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/StackFrame/Overview/source.cs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/StackFrameSample1/VB/source.vb" id="Snippet6"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/StackFrameSample1/VB/source.vb" id="Snippet6"::: + ]]> @@ -494,15 +494,15 @@ Gets the column number in the file that contains the code that is executing. This information is typically extracted from the debugging symbols for the executable. The file column number, or 0 (zero) if the file column number cannot be determined. - method. This code example is part of a larger example provided for the class. - + method. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/StackFrameSample1/CPP/source.cpp" id="Snippet7"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/StackFrame/Overview/source.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/StackFrameSample1/VB/source.vb" id="Snippet7"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/StackFrameSample1/VB/source.vb" id="Snippet7"::: + ]]> @@ -553,15 +553,15 @@ Gets the line number in the file that contains the code that is executing. This information is typically extracted from the debugging symbols for the executable. The file line number, or 0 (zero) if the file line number cannot be determined. - method. This code example is part of a larger example provided for the class. - + method. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/StackFrameSample1/CPP/source.cpp" id="Snippet7"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/StackFrame/Overview/source.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/StackFrameSample1/VB/source.vb" id="Snippet7"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/StackFrameSample1/VB/source.vb" id="Snippet7"::: + ]]> @@ -619,15 +619,15 @@ Gets the file name that contains the code that is executing. This information is typically extracted from the debugging symbols for the executable. The file name, or if the file name cannot be determined. - method. This code example is part of a larger example provided for the class. - + method. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/StackFrameSample1/CPP/source.cpp" id="Snippet7"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/StackFrame/Overview/source.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/StackFrameSample1/VB/source.vb" id="Snippet7"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/StackFrameSample1/VB/source.vb" id="Snippet7"::: + ]]> @@ -678,15 +678,15 @@ Gets the offset from the start of the Microsoft intermediate language (MSIL) code for the method that is executing. This offset might be an approximation depending on whether or not the just-in-time (JIT) compiler is generating debugging code. The generation of this debugging information is controlled by the . The offset from the start of the MSIL code for the method that is executing. - method. This code example is part of a larger example provided for the class. - + method. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/StackFrameSample1/CPP/source.cpp" id="Snippet7"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/StackFrame/Overview/source.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/StackFrameSample1/VB/source.vb" id="Snippet7"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/StackFrameSample1/VB/source.vb" id="Snippet7"::: + ]]> @@ -745,20 +745,20 @@ Gets the method in which the frame is executing. The method in which the frame is executing. - 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. - + 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. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/StackTraceSample3/CPP/stacktracesample3.cpp" id="Snippet6"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/StackFrame/GetMethod/stacktracesample3.cs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/StackTraceSample3/VB/stacktracesample3.vb" id="Snippet6"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/StackTraceSample3/VB/stacktracesample3.vb" id="Snippet6"::: + ]]> @@ -802,15 +802,15 @@ Gets the offset from the start of the native just-in-time (JIT)-compiled code for the method that is being executed. The generation of this debugging information is controlled by the class. The offset from the start of the JIT-compiled code for the method that is being executed. - method. This code example is part of a larger example provided for the class. - + method. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/StackFrameSample1/CPP/source.cpp" id="Snippet7"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/StackFrame/Overview/source.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/StackFrameSample1/VB/source.vb" id="Snippet7"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/StackFrameSample1/VB/source.vb" id="Snippet7"::: + ]]> @@ -856,11 +856,11 @@ Defines the value that is returned from the or method when the native or Microsoft intermediate language (MSIL) offset is unknown. This field is constant. - @@ -916,15 +916,15 @@ Builds a readable representation of the stack trace. A readable representation of the stack trace. - method. This code example is part of a larger example provided for the class. - + method. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/StackFrameSample1/CPP/source.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/StackFrame/Overview/source.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/StackFrameSample1/VB/source.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/StackFrameSample1/VB/source.vb" id="Snippet3"::: + ]]> diff --git a/xml/System.Diagnostics/StackTrace.xml b/xml/System.Diagnostics/StackTrace.xml index aeabdfdb21f..b76e236e8ab 100644 --- a/xml/System.Diagnostics/StackTrace.xml +++ b/xml/System.Diagnostics/StackTrace.xml @@ -67,22 +67,22 @@ Represents a stack trace, which is an ordered collection of one or more stack frames. - information will be most informative with Debug build configurations. By default, Debug builds include debug symbols, while Release builds do not. The debug symbols contain most of the file, method name, line number, and column information used in constructing and objects. - - might not report as many method calls as expected, due to code transformations that occur during optimization. - - - -## Examples - The following console application demonstrates how to create a simple and iterate through its frames to obtain debugging and diagnostic information. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/StackTraceSample1/CPP/stacktracesample1.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/StackTrace/Overview/stacktracesample1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/StackTraceSample1/VB/stacktracesample1.vb" id="Snippet1"::: - + information will be most informative with Debug build configurations. By default, Debug builds include debug symbols, while Release builds do not. The debug symbols contain most of the file, method name, line number, and column information used in constructing and objects. + + might not report as many method calls as expected, due to code transformations that occur during optimization. + + + +## Examples + The following console application demonstrates how to create a simple and iterate through its frames to obtain debugging and diagnostic information. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/StackTraceSample1/CPP/stacktracesample1.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/StackTrace/Overview/stacktracesample1.cs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/StackTraceSample1/VB/stacktracesample1.vb" id="Snippet1"::: + ]]> @@ -134,22 +134,22 @@ Initializes a new instance of the class from the caller's frame. - is created with the caller's current thread, and does not contain file name, line number, or column information. - - Use this parameterless constructor when you want a complete trace with only summary method information about the call stack. - - - -## Examples - The following code example displays the first and last function calls in a stack trace. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/StackFrameSample1/CPP/source.cpp" id="Snippet8"::: - :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/StackFrame/Overview/source.cs" id="Snippet8"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/StackFrameSample1/VB/source.vb" id="Snippet8"::: - + is created with the caller's current thread, and does not contain file name, line number, or column information. + + Use this parameterless constructor when you want a complete trace with only summary method information about the call stack. + + + +## Examples + The following code example displays the first and last function calls in a stack trace. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/StackFrameSample1/CPP/source.cpp" id="Snippet8"::: + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/StackFrame/Overview/source.cs" id="Snippet8"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/StackFrameSample1/VB/source.vb" id="Snippet8"::: + ]]> @@ -186,27 +186,27 @@ 9.0.0.0 - + to capture the file name, line number, and column number; otherwise, . Initializes a new instance of the class from the caller's frame, optionally capturing source information. - is created with the caller's current thread. - - - -## Examples - The following code example demonstrates various constructor methods. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/StackFrameSample1/CPP/source.cpp" id="Snippet4"::: - :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/StackFrame/Overview/source.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/StackFrameSample1/VB/source.vb" id="Snippet4"::: - + is created with the caller's current thread. + + + +## Examples + The following code example demonstrates various constructor methods. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/StackFrameSample1/CPP/source.cpp" id="Snippet4"::: + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/StackFrame/Overview/source.cs" id="Snippet4"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/StackFrameSample1/VB/source.vb" id="Snippet4"::: + ]]> @@ -271,26 +271,26 @@ 9.0.0.0 - + The frame that the object should contain. Initializes a new instance of the class that contains a single frame. - @@ -328,19 +328,19 @@ 9.0.0.0 - + The exception object from which to construct the stack trace. Initializes a new instance of the class using the provided exception object. - is created with the caller's current thread, and does not contain file name, line number, or column information. - - The resulting stack trace describes the stack at the time of the exception. - + is created with the caller's current thread, and does not contain file name, line number, or column information. + + The resulting stack trace describes the stack at the time of the exception. + ]]> The parameter is . @@ -379,19 +379,19 @@ 9.0.0.0 - + The number of frames up the stack from which to start the trace. Initializes a new instance of the class from the caller's frame, skipping the specified number of frames. - is created with the caller's current thread, and does not contain file name, line number, or column information. - - If the number of frames to skip is greater than or equal to the total number of frames on the call stack at the time the instance is created, the will contain no frames. - + is created with the caller's current thread, and does not contain file name, line number, or column information. + + If the number of frames to skip is greater than or equal to the total number of frames on the call stack at the time the instance is created, the will contain no frames. + ]]> The parameter is negative. @@ -429,23 +429,23 @@ 9.0.0.0 - - + + The exception object from which to construct the stack trace. The number of frames up the stack from which to start the trace. Initializes a new instance of the class using the provided exception object and skipping the specified number of frames. - does not contain file name, line number, or column information. - - The resulting stack trace describes the stack at the time of the exception. - - If the number of frames to skip is greater than or equal to the total number of frames on the call stack at the time the instance is created, the will contain no frames. - + does not contain file name, line number, or column information. + + The resulting stack trace describes the stack at the time of the exception. + + If the number of frames to skip is greater than or equal to the total number of frames on the call stack at the time the instance is created, the will contain no frames. + ]]> The parameter is . @@ -485,8 +485,8 @@ 9.0.0.0 - - + + The number of frames up the stack from which to start the trace. @@ -494,20 +494,20 @@ to capture the file name, line number, and column number; otherwise, . Initializes a new instance of the class from the caller's frame, skipping the specified number of frames and optionally capturing source information. - will contain no frames. - - - -## Examples - The following code example demonstrates various constructor methods. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/StackFrameSample1/CPP/source.cpp" id="Snippet4"::: - :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/StackFrame/Overview/source.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/StackFrameSample1/VB/source.vb" id="Snippet4"::: - + will contain no frames. + + + +## Examples + The following code example demonstrates various constructor methods. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/StackFrameSample1/CPP/source.cpp" id="Snippet4"::: + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/StackFrame/Overview/source.cs" id="Snippet4"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/StackFrameSample1/VB/source.vb" id="Snippet4"::: + ]]> The parameter is negative. @@ -540,24 +540,24 @@ - - + + The thread whose stack trace is requested. to capture the file name, line number, and column number; otherwise, . - Initializes a new instance of the class for a specific thread, optionally capturing source information. - + Initializes a new instance of the class for a specific thread, optionally capturing source information. + Do not use this constructor overload. - [!IMPORTANT] -> Do not use this constructor. It is obsolete, and there is no recommended alternative. When you suspend a thread, you have no way of knowing what code it is executing, and deadlocks can occur very easily. For example, if you suspend a thread while it holds locks during a security permission evaluation, other threads in the might be blocked. If you suspend a thread while it is executing a class constructor, other threads in the that attempt to use that class are blocked. - + [!IMPORTANT] +> Do not use this constructor. It is obsolete, and there is no recommended alternative. When you suspend a thread, you have no way of knowing what code it is executing, and deadlocks can occur very easily. For example, if you suspend a thread while it holds locks during a security permission evaluation, other threads in the might be blocked. If you suspend a thread while it is executing a class constructor, other threads in the that attempt to use that class are blocked. + ]]> The thread is not suspended. @@ -596,9 +596,9 @@ 9.0.0.0 - - - + + + The exception object from which to construct the stack trace. @@ -607,13 +607,13 @@ to capture the file name, line number, and column number; otherwise, . Initializes a new instance of the class using the provided exception object, skipping the specified number of frames and optionally capturing source information. - will contain no frames. - + will contain no frames. + ]]> The parameter is . @@ -674,11 +674,11 @@ to capture the file name, line number, and column number; otherwise, . Initializes a new instance of the class, using the provided exception object and optionally capturing source information. - The parameter is . @@ -723,15 +723,15 @@ Gets the number of frames in the stack trace. The number of frames in the stack trace. - @@ -778,27 +778,27 @@ System.Diagnostics.StackFrame - + The index of the stack frame requested. Gets the specified stack frame. The specified stack frame. - @@ -857,24 +857,24 @@ Returns a copy of all stack frames in the current stack trace. An array of type representing the function calls in the stack trace. - 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. - - 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. - - - -## Examples - The following code example demonstrates enumerating the frames in a . - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/StackTraceSample2/CPP/stacktracesample2.cpp" id="Snippet3"::: - :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/StackTrace/GetFrames/stacktracesample2.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/StackTraceSample2/VB/stacktracesample2.vb" id="Snippet3"::: - + 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. + + 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. + + + +## Examples + The following code example demonstrates enumerating the frames in a . + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/StackTraceSample2/CPP/stacktracesample2.cpp" id="Snippet3"::: + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/StackTrace/GetFrames/stacktracesample2.cs" id="Snippet3"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/StackTraceSample2/VB/stacktracesample2.vb" id="Snippet3"::: + ]]> @@ -919,11 +919,11 @@ Defines the default for the number of methods to omit from the stack trace. This field is constant. - @@ -975,15 +975,15 @@ Builds a readable representation of the stack trace. A readable representation of the stack trace. - diff --git a/xml/System.Globalization/Calendar.xml b/xml/System.Globalization/Calendar.xml index 8df61546ee5..227fdf8e00c 100644 --- a/xml/System.Globalization/Calendar.xml +++ b/xml/System.Globalization/Calendar.xml @@ -85,61 +85,61 @@ Represents time in divisions, such as weeks, months, and years. - [!NOTE] -> For information about using the calendar classes in .NET, see [Working with Calendars](/dotnet/standard/datetime/working-with-calendars). - - Any moment in time can be represented as a set of numeric values using a particular calendar. For example, a vernal equinox occurred at (1999, 3, 20, 8, 46, 0, 0.0) in the Gregorian calendar, that is, March 20, 1999 C.E. at 8:46:00:0.0. An implementation of can map any date in the range of a specific calendar to a similar set of numeric values, and can map such sets of numeric values to a textual representation using information from and . The textual representation can be culture-sensitive, for example, "8:46 AM March 20th 1999 AD" for the en-US culture, or culture-insensitive, for example, "1999-03-20T08:46:00" in ISO 8601 format. - - A implementation can define one or more eras. The class identifies the eras as enumerated integers, where the current era () has the value 0. +> For information about using the calendar classes in .NET, see [Working with Calendars](/dotnet/standard/datetime/working-with-calendars). + + Any moment in time can be represented as a set of numeric values using a particular calendar. For example, a vernal equinox occurred at (1999, 3, 20, 8, 46, 0, 0.0) in the Gregorian calendar, that is, March 20, 1999 C.E. at 8:46:00:0.0. An implementation of can map any date in the range of a specific calendar to a similar set of numeric values, and can map such sets of numeric values to a textual representation using information from and . The textual representation can be culture-sensitive, for example, "8:46 AM March 20th 1999 AD" for the en-US culture, or culture-insensitive, for example, "1999-03-20T08:46:00" in ISO 8601 format. + + A implementation can define one or more eras. The class identifies the eras as enumerated integers, where the current era () has the value 0. [!INCLUDE[japanese-era-note](~/includes/calendar-era.md)] - To make up for the difference between the calendar year and the actual time that the earth rotates around the sun or the actual time that the moon rotates around the earth, a leap year has a different number of days from a standard calendar year. Each implementation defines leap years differently. - - For consistency, the first unit in each interval (the first month, for example) is assigned the value 1. - - The namespace includes the following implementations: - -- - -- - -- - -- - -- - -- - -- - -- - -- - -- - -- - -- - -- - -- - -- - - - -## Examples - The following code example demonstrates the members of the class. - + To make up for the difference between the calendar year and the actual time that the earth rotates around the sun or the actual time that the moon rotates around the earth, a leap year has a different number of days from a standard calendar year. Each implementation defines leap years differently. + + For consistency, the first unit in each interval (the first month, for example) is assigned the value 1. + + The namespace includes the following implementations: + +- + +- + +- + +- + +- + +- + +- + +- + +- + +- + +- + +- + +- + +- + +- + + + +## Examples + The following code example demonstrates the members of the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Globalization.Calendar/CPP/calendar.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/Overview/calendar.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.Calendar/VB/calendar.vb" id="Snippet1"::: @@ -205,15 +205,15 @@ Initializes a new instance of the class. - class. - + class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Globalization.Calendar/CPP/calendar.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/Overview/calendar.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.Calendar/VB/calendar.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.Calendar/VB/calendar.vb" id="Snippet1"::: + ]]> @@ -270,27 +270,27 @@ Returns a that is the specified number of days away from the specified . The that results from adding the specified number of days to the specified . - . If `days` is negative, the resulting is earlier than the specified . - - The month part of the resulting is affected if the resulting day is outside the month of the specified . The year part of the resulting is affected if the resulting month is outside the year of the specified . The era part of the resulting is affected if the resulting year is outside the era of the specified . The time-of-day part of the resulting remains the same as the specified . - - The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. - + . If `days` is negative, the resulting is earlier than the specified . + + The month part of the resulting is affected if the resulting day is outside the month of the specified . The year part of the resulting is affected if the resulting month is outside the year of the specified . The era part of the resulting is affected if the resulting year is outside the era of the specified . The time-of-day part of the resulting remains the same as the specified . + + The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. + :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/AddDays/add1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.calendar.addmethods/vb/add1.vb" id="Snippet1"::: - - - -## Examples - The following code example demonstrates the members of the class. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.calendar.addmethods/vb/add1.vb" id="Snippet1"::: + + + +## Examples + The following code example demonstrates the members of the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Globalization.Calendar/CPP/calendar.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/Overview/calendar.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.Calendar/VB/calendar.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.Calendar/VB/calendar.vb" id="Snippet1"::: + ]]> The resulting is outside the supported range of this calendar. @@ -355,27 +355,27 @@ Returns a that is the specified number of hours away from the specified . The that results from adding the specified number of hours to the specified . - . If `hours` is negative, the resulting is earlier than the specified . - - The day part of the resulting is affected if the resulting time is outside the day of the specified . The month part of the resulting is affected if the resulting day is outside the month of the specified . The year part of the resulting is affected if the resulting month is outside the year of the specified . The era part of the resulting is affected if the resulting year is outside the era of the specified . - - The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. - + . If `hours` is negative, the resulting is earlier than the specified . + + The day part of the resulting is affected if the resulting time is outside the day of the specified . The month part of the resulting is affected if the resulting day is outside the month of the specified . The year part of the resulting is affected if the resulting month is outside the year of the specified . The era part of the resulting is affected if the resulting year is outside the era of the specified . + + The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. + :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/AddDays/add1.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.calendar.addmethods/vb/add1.vb" id="Snippet2"::: - - - -## Examples - The following code example demonstrates the members of the class. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.calendar.addmethods/vb/add1.vb" id="Snippet2"::: + + + +## Examples + The following code example demonstrates the members of the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Globalization.Calendar/CPP/calendar.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/Overview/calendar.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.Calendar/VB/calendar.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.Calendar/VB/calendar.vb" id="Snippet1"::: + ]]> The resulting is outside the supported range of this calendar. @@ -440,27 +440,27 @@ Returns a that is the specified number of milliseconds away from the specified . The that results from adding the specified number of milliseconds to the specified . - . If `milliseconds` is negative, the resulting is earlier than the specified . - - The day part of the resulting is affected if the resulting time is outside the day of the specified . The month part of the resulting is affected if the resulting day is outside the month of the specified . The year part of the resulting is affected if the resulting month is outside the year of the specified . The era part of the resulting is affected if the resulting year is outside the era of the specified . - - The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. - + . If `milliseconds` is negative, the resulting is earlier than the specified . + + The day part of the resulting is affected if the resulting time is outside the day of the specified . The month part of the resulting is affected if the resulting day is outside the month of the specified . The year part of the resulting is affected if the resulting month is outside the year of the specified . The era part of the resulting is affected if the resulting year is outside the era of the specified . + + The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. + :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/AddDays/add1.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.calendar.addmethods/vb/add1.vb" id="Snippet3"::: - - - -## Examples - The following code example demonstrates the members of the class. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.calendar.addmethods/vb/add1.vb" id="Snippet3"::: + + + +## Examples + The following code example demonstrates the members of the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Globalization.Calendar/CPP/calendar.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/Overview/calendar.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.Calendar/VB/calendar.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.Calendar/VB/calendar.vb" id="Snippet1"::: + ]]> The resulting is outside the supported range of this calendar. @@ -525,27 +525,27 @@ Returns a that is the specified number of minutes away from the specified . The that results from adding the specified number of minutes to the specified . - . If `minutes` is negative, the resulting is earlier than the specified . - - The day part of the resulting is affected if the resulting time is outside the day of the specified . The month part of the resulting is affected if the resulting day is outside the month of the specified . The year part of the resulting is affected if the resulting month is outside the year of the specified . The era part of the resulting is affected if the resulting year is outside the era of the specified . - - The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. - + . If `minutes` is negative, the resulting is earlier than the specified . + + The day part of the resulting is affected if the resulting time is outside the day of the specified . The month part of the resulting is affected if the resulting day is outside the month of the specified . The year part of the resulting is affected if the resulting month is outside the year of the specified . The era part of the resulting is affected if the resulting year is outside the era of the specified . + + The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. + :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/AddDays/add1.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.calendar.addmethods/vb/add1.vb" id="Snippet4"::: - - - -## Examples - The following code example demonstrates the members of the class. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.calendar.addmethods/vb/add1.vb" id="Snippet4"::: + + + +## Examples + The following code example demonstrates the members of the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Globalization.Calendar/CPP/calendar.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/Overview/calendar.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.Calendar/VB/calendar.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.Calendar/VB/calendar.vb" id="Snippet1"::: + ]]> The resulting is outside the supported range of this calendar. @@ -610,31 +610,31 @@ When overridden in a derived class, returns a that is the specified number of months away from the specified . The that results from adding the specified number of months to the specified . - . If `months` is negative, the resulting is earlier than the specified . - - The day part of the resulting is affected if the resulting day is not a valid day in the resulting month of the resulting year. It is changed to the last valid day in the resulting month of the resulting year. The year part of the resulting is affected if the resulting month is outside the year of the specified . The era part of the resulting is affected if the resulting year is outside the era of the specified . The time-of-day part of the resulting remains the same as the specified . - - For example, suppose that the current calendar has 12 months, where the fourth month has 30 days and the tenth month has 31 days. If the specified month is the tenth month, the specified day is the 31st day of that month, and the value of the `months` parameter is 6, the resulting year is one more than the specified year, the resulting month is the fourth month, and the resulting day is the 30th day, which is the last day of the resulting month. - - If the value of the `months` parameter is negative, the resulting is earlier than the specified . - - The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. - + . If `months` is negative, the resulting is earlier than the specified . + + The day part of the resulting is affected if the resulting day is not a valid day in the resulting month of the resulting year. It is changed to the last valid day in the resulting month of the resulting year. The year part of the resulting is affected if the resulting month is outside the year of the specified . The era part of the resulting is affected if the resulting year is outside the era of the specified . The time-of-day part of the resulting remains the same as the specified . + + For example, suppose that the current calendar has 12 months, where the fourth month has 30 days and the tenth month has 31 days. If the specified month is the tenth month, the specified day is the 31st day of that month, and the value of the `months` parameter is 6, the resulting year is one more than the specified year, the resulting month is the fourth month, and the resulting day is the 30th day, which is the last day of the resulting month. + + If the value of the `months` parameter is negative, the resulting is earlier than the specified . + + The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. + :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/AddDays/add1.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.calendar.addmethods/vb/add1.vb" id="Snippet5"::: - - - -## Examples - The following code example demonstrates the members of the class. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.calendar.addmethods/vb/add1.vb" id="Snippet5"::: + + + +## Examples + The following code example demonstrates the members of the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Globalization.Calendar/CPP/calendar.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/Overview/calendar.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.Calendar/VB/calendar.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.Calendar/VB/calendar.vb" id="Snippet1"::: + ]]> The resulting is outside the supported range of this calendar. @@ -699,27 +699,27 @@ Returns a that is the specified number of seconds away from the specified . The that results from adding the specified number of seconds to the specified . - . If `seconds` is negative, the resulting is earlier than the specified . - - The day part of the resulting is affected if the resulting time is outside the day of the specified . The month part of the resulting is affected if the resulting day is outside the month of the specified . The year part of the resulting is affected if the resulting month is outside the year of the specified . The era part of the resulting is affected if the resulting year is outside the era of the specified . - - The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. - + . If `seconds` is negative, the resulting is earlier than the specified . + + The day part of the resulting is affected if the resulting time is outside the day of the specified . The month part of the resulting is affected if the resulting day is outside the month of the specified . The year part of the resulting is affected if the resulting month is outside the year of the specified . The era part of the resulting is affected if the resulting year is outside the era of the specified . + + The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. + :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/AddDays/add1.cs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.calendar.addmethods/vb/add1.vb" id="Snippet6"::: - - - -## Examples - The following code example demonstrates the members of the class. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.calendar.addmethods/vb/add1.vb" id="Snippet6"::: + + + +## Examples + The following code example demonstrates the members of the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Globalization.Calendar/CPP/calendar.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/Overview/calendar.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.Calendar/VB/calendar.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.Calendar/VB/calendar.vb" id="Snippet1"::: + ]]> The resulting is outside the supported range of this calendar. @@ -784,29 +784,29 @@ Returns a that is the specified number of weeks away from the specified . The that results from adding the specified number of weeks to the specified . - . If `weeks` is negative, the resulting is earlier than the specified . - - The month part of the resulting is affected if the resulting day is outside the month of the specified . The year part of the resulting is affected if the resulting month is outside the year of the specified . The era part of the resulting is affected if the resulting year is outside the era of the specified . The time-of-day part of the resulting remains the same as the specified . - - In all .NET classes derived from the class, a week is defined as seven days. - - The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. - + . If `weeks` is negative, the resulting is earlier than the specified . + + The month part of the resulting is affected if the resulting day is outside the month of the specified . The year part of the resulting is affected if the resulting month is outside the year of the specified . The era part of the resulting is affected if the resulting year is outside the era of the specified . The time-of-day part of the resulting remains the same as the specified . + + In all .NET classes derived from the class, a week is defined as seven days. + + The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. + :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/AddDays/add1.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.calendar.addmethods/vb/add1.vb" id="Snippet7"::: - - - -## Examples - The following code example demonstrates the members of the class. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.calendar.addmethods/vb/add1.vb" id="Snippet7"::: + + + +## Examples + The following code example demonstrates the members of the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Globalization.Calendar/CPP/calendar.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/Overview/calendar.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.Calendar/VB/calendar.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.Calendar/VB/calendar.vb" id="Snippet1"::: + ]]> The resulting is outside the supported range of this calendar. @@ -871,31 +871,31 @@ When overridden in a derived class, returns a that is the specified number of years away from the specified . The that results from adding the specified number of years to the specified . - . If `years` is negative, the resulting is earlier than the specified . - - The day part of the resulting is affected if the resulting day is not a valid day in the resulting month of the resulting year. It is changed to the last valid day in the resulting month of the resulting year. The month part of the resulting is affected if the resulting month is not a valid month in the resulting year. It is changed to the last valid month in the resulting year. The era part of the resulting is affected if the resulting year is outside the era of the specified . The time-of-day part of the resulting remains the same as the specified . - - For example, in the Gregorian calendar, February has 28 days, except during a leap year when it has 29 days. If the specified date is the 29th day of February in a leap year and the value of `years` is 1, the resulting date is the 28th day of February in the following year. - - If `years` is negative, the resulting is earlier than the specified . - - The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. - + . If `years` is negative, the resulting is earlier than the specified . + + The day part of the resulting is affected if the resulting day is not a valid day in the resulting month of the resulting year. It is changed to the last valid day in the resulting month of the resulting year. The month part of the resulting is affected if the resulting month is not a valid month in the resulting year. It is changed to the last valid month in the resulting year. The era part of the resulting is affected if the resulting year is outside the era of the specified . The time-of-day part of the resulting remains the same as the specified . + + For example, in the Gregorian calendar, February has 28 days, except during a leap year when it has 29 days. If the specified date is the 29th day of February in a leap year and the value of `years` is 1, the resulting date is the 28th day of February in the following year. + + If `years` is negative, the resulting is earlier than the specified . + + The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. + :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/AddDays/add1.cs" id="Snippet8"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.calendar.addmethods/vb/add1.vb" id="Snippet8"::: - - - -## Examples - The following code example demonstrates the members of the class. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.calendar.addmethods/vb/add1.vb" id="Snippet8"::: + + + +## Examples + The following code example demonstrates the members of the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Globalization.Calendar/CPP/calendar.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/Overview/calendar.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.Calendar/VB/calendar.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.Calendar/VB/calendar.vb" id="Snippet1"::: + ]]> The resulting is outside the supported range of this calendar. @@ -957,14 +957,14 @@ Gets a value indicating whether the current calendar is solar-based, lunar-based, or a combination of both. One of the values. - type found in .NET and displays the value of its property. - + type found in .NET and displays the value of its property. + :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/AlgorithmType/algorithmtype1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.calendar.algorithmtype/vb/algorithmtype1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.calendar.algorithmtype/vb/algorithmtype1.vb" id="Snippet1"::: + ]]> @@ -1023,11 +1023,11 @@ Creates a new object that is a copy of the current object. A new instance of that is the memberwise clone of the current object. - @@ -1076,11 +1076,11 @@ Represents the current era of the current calendar. The value of this field is 0. - field represents the index of the current era in the array. Because eras are arranged in reverse chronological order (from the current era to earlier eras), this field is a constant that has a value of 0. - + field represents the index of the current era in the array. Because eras are arranged in reverse chronological order (from the current era to earlier eras), this field is a constant that has a value of 0. + ]]> @@ -1125,11 +1125,11 @@ Gets the number of days in the year that precedes the year that is specified by the property. The number of days in the year that precedes the year specified by . - class. - + class. + ]]> @@ -1177,22 +1177,22 @@ When overridden in a derived class, gets the list of eras in the current calendar. An array of integers that represents the eras in the current calendar. - is 4, which is the first element of the array. Only the and the classes support multiple eras. - + [!INCLUDE[japanese-era-note](~/includes/calendar-era.md)] The and classes support multiple eras. Most calendar implementations, on the other hand, support a single era. - -## Examples - The following example displays the values contained in when the Heisei era (1989-2019) was the current era. - + +## Examples + The following example displays the values contained in when the Heisei era (1989-2019) was the current era. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Globalization.JapaneseCalendar.Eras/CPP/yslin_japanesecalendar_eras.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/Eras/yslin_japanesecalendar_eras.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.JapaneseCalendar.Eras/VB/yslin_japanesecalendar_eras.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.JapaneseCalendar.Eras/VB/yslin_japanesecalendar_eras.vb" id="Snippet1"::: + ]]> @@ -1245,15 +1245,15 @@ The and When overridden in a derived class, returns the day of the month in the specified . A positive integer that represents the day of the month in the parameter. - class. - + class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Globalization.Calendar/CPP/calendar.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/Overview/calendar.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.Calendar/VB/calendar.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.Calendar/VB/calendar.vb" id="Snippet1"::: + ]]> @@ -1316,20 +1316,20 @@ The and When overridden in a derived class, returns the day of the week in the specified . A value that represents the day of the week in the parameter. - values are Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, and Saturday. - - - -## Examples - The following code example demonstrates the members of the class. - + values are Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, and Saturday. + + + +## Examples + The following code example demonstrates the members of the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Globalization.Calendar/CPP/calendar.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/Overview/calendar.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.Calendar/VB/calendar.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.Calendar/VB/calendar.vb" id="Snippet1"::: + ]]> @@ -1393,20 +1393,20 @@ The and When overridden in a derived class, returns the day of the year in the specified . A positive integer that represents the day of the year in the parameter. - , for January 1 returns 1, and for December 31 returns 365 in a common year or 366 in a leap year. - - - -## Examples - The following code example demonstrates the members of the class. - + , for January 1 returns 1, and for December 31 returns 365 in a common year or 366 in a leap year. + + + +## Examples + The following code example demonstrates the members of the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Globalization.Calendar/CPP/calendar.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/Overview/calendar.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.Calendar/VB/calendar.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.Calendar/VB/calendar.vb" id="Snippet1"::: + ]]> @@ -1481,27 +1481,27 @@ The and Returns the number of days in the specified month and year of the current era. The number of days in the specified month in the specified year in the current era. - , for February returns 28 in a common year or 29 in a leap year. - - - -## Examples - The following code example compares different implementations of the class. - + , for February returns 28 in a common year or 29 in a leap year. + + + +## Examples + The following code example compares different implementations of the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Globalization.Calendar_Compare/CPP/calendar_compare.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/GetDaysInMonth/calendar_compare.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.Calendar_Compare/VB/calendar_compare.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.Calendar_Compare/VB/calendar_compare.vb" id="Snippet1"::: + ]]> - is outside the range supported by the calendar. - - -or- - + is outside the range supported by the calendar. + + -or- + is outside the range supported by the calendar. @@ -1559,22 +1559,22 @@ The and When overridden in a derived class, returns the number of days in the specified month, year, and era. The number of days in the specified month in the specified year in the specified era. - , for February returns 28 in a common year or 29 in a leap year. - + , for February returns 28 in a common year or 29 in a leap year. + ]]> - is outside the range supported by the calendar. - - -or- - - is outside the range supported by the calendar. - - -or- - + is outside the range supported by the calendar. + + -or- + + is outside the range supported by the calendar. + + -or- + is outside the range supported by the calendar. The derived class must support when it is passed as the parameter. One way to support is by replacing it with the value stored in Eras[0], which is the value for the current era of the calendar. @@ -1643,20 +1643,20 @@ The and Returns the number of days in the specified year of the current era. The number of days in the specified year in the current era. - , returns 365 for a common year or 366 for a leap year. - - - -## Examples - The following code example compares different implementations of the class. - + , returns 365 for a common year or 366 for a leap year. + + + +## Examples + The following code example compares different implementations of the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Globalization.Calendar_Compare/CPP/calendar_compare.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/GetDaysInMonth/calendar_compare.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.Calendar_Compare/VB/calendar_compare.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.Calendar_Compare/VB/calendar_compare.vb" id="Snippet1"::: + ]]> @@ -1715,18 +1715,18 @@ The and When overridden in a derived class, returns the number of days in the specified year and era. The number of days in the specified year in the specified era. - , returns 365 for a common year or 366 for a leap year. - + , returns 365 for a common year or 366 for a leap year. + ]]> - is outside the range supported by the calendar. - - -or- - + is outside the range supported by the calendar. + + -or- + is outside the range supported by the calendar. The derived class must support when it is passed as the parameter. One way to support is by replacing it with the value stored in Eras[0], which is the value for the current era of the calendar. @@ -1785,18 +1785,18 @@ The and When overridden in a derived class, returns the era of the specified . An integer that represents the era of . - and the classes support multiple eras. -## Examples - The following code example demonstrates the members of the class. - +## Examples + The following code example demonstrates the members of the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Globalization.Calendar/CPP/calendar.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/Overview/calendar.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.Calendar/VB/calendar.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.Calendar/VB/calendar.vb" id="Snippet1"::: + ]]> @@ -1861,15 +1861,15 @@ Only the and the Returns the hours value in the specified . An integer from 0 to 23 that represents the hour in . - class. - + class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Globalization.Calendar/CPP/calendar.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/Overview/calendar.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.Calendar/VB/calendar.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.Calendar/VB/calendar.vb" id="Snippet1"::: + ]]> @@ -1938,22 +1938,22 @@ Only the and the System.Int32 - + A year. Calculates the leap month for a specified year. - A positive integer that indicates the leap month in the specified year. - - -or- - + A positive integer that indicates the leap month in the specified year. + + -or- + Zero if this calendar does not support a leap month or if the parameter does not represent a leap year. - method returns a number between 1 and 13 that indicates the month associated with a specified date. If there is a leap month between the eighth and ninth months of the year, the method returns 8 for the eighth month, 9 for the leap eighth month, and 10 for the ninth month. - + method returns a number between 1 and 13 that indicates the month associated with a specified date. If there is a leap month between the eighth and ninth months of the year, the method returns 8 for the eighth month, 9 for the leap eighth month, and 10 for the ninth month. + ]]> @@ -2010,17 +2010,17 @@ Only the and the A year. An era. Calculates the leap month for a specified year and era. - A positive integer that indicates the leap month in the specified year and era. - - -or- - + A positive integer that indicates the leap month in the specified year and era. + + -or- + Zero if this calendar does not support a leap month or if the and parameters do not specify a leap year. - method returns a number between 1 and 13 that indicates the month associated with a specified date. If there is a leap month between the eighth and ninth months of the year, the method returns 8 for the eighth month, 9 for the leap eighth month, and 10 for the ninth month. - + method returns a number between 1 and 13 that indicates the month associated with a specified date. If there is a leap month between the eighth and ninth months of the year, the method returns 8 for the eighth month, 9 for the leap eighth month, and 10 for the ninth month. + ]]> @@ -2072,15 +2072,15 @@ Only the and the Returns the milliseconds value in the specified . A double-precision floating-point number from 0 to 999 that represents the milliseconds in the parameter. - class. - + class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Globalization.Calendar/CPP/calendar.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/Overview/calendar.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.Calendar/VB/calendar.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.Calendar/VB/calendar.vb" id="Snippet1"::: + ]]> @@ -2143,15 +2143,15 @@ Only the and the Returns the minutes value in the specified . An integer from 0 to 59 that represents the minutes in . - class. - + class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Globalization.Calendar/CPP/calendar.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/Overview/calendar.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.Calendar/VB/calendar.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.Calendar/VB/calendar.vb" id="Snippet1"::: + ]]> @@ -2214,20 +2214,20 @@ Only the and the When overridden in a derived class, returns the month in the specified . A positive integer that represents the month in . - , for Tishrei returns 1, and for Elul returns 12 in a common year or 13 in a leap year. - - - -## Examples - The following code example demonstrates the members of the class. - + , for Tishrei returns 1, and for Elul returns 12 in a common year or 13 in a leap year. + + + +## Examples + The following code example demonstrates the members of the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Globalization.Calendar/CPP/calendar.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/Overview/calendar.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.Calendar/VB/calendar.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.Calendar/VB/calendar.vb" id="Snippet1"::: + ]]> @@ -2300,20 +2300,20 @@ Only the and the Returns the number of months in the specified year in the current era. The number of months in the specified year in the current era. - , returns 12 for a common year or 13 for a leap year. - - - -## Examples - The following code example compares different implementations of the class. - + , returns 12 for a common year or 13 for a leap year. + + + +## Examples + The following code example compares different implementations of the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Globalization.Calendar_Compare/CPP/calendar_compare.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/GetDaysInMonth/calendar_compare.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.Calendar_Compare/VB/calendar_compare.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.Calendar_Compare/VB/calendar_compare.vb" id="Snippet1"::: + ]]> @@ -2371,18 +2371,18 @@ Only the and the When overridden in a derived class, returns the number of months in the specified year in the specified era. The number of months in the specified year in the specified era. - , returns 12 for a common year or 13 for a leap year. - + , returns 12 for a common year or 13 for a leap year. + ]]> - is outside the range supported by the calendar. - - -or- - + is outside the range supported by the calendar. + + -or- + is outside the range supported by the calendar. The derived class must support when it is passed as the parameter. One way to support is by replacing it with the value stored in Eras[0], which is the value for the current era of the calendar. @@ -2440,15 +2440,15 @@ Only the and the Returns the seconds value in the specified . An integer from 0 to 59 that represents the seconds in . - class. - + class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Globalization.Calendar/CPP/calendar.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/Overview/calendar.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.Calendar/VB/calendar.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.Calendar/VB/calendar.vb" id="Snippet1"::: + ]]> @@ -2515,69 +2515,69 @@ Only the and the Returns the week of the year that includes the date in the specified value. A positive integer that represents the week of the year that includes the date in the parameter. - object for a particular culture that uses the calendar indicated by the property includes the following culture-specific values that can be used for the `rule` and `firstDayOfWeek` parameters: - -- The property contains the default first day of the week that can be used for the `firstDayOfWeek` parameter. - -- The property contains the default calendar week rule that can be used for the `rule` parameter. - + object for a particular culture that uses the calendar indicated by the property includes the following culture-specific values that can be used for the `rule` and `firstDayOfWeek` parameters: + +- The property contains the default first day of the week that can be used for the `firstDayOfWeek` parameter. + +- The property contains the default calendar week rule that can be used for the `rule` parameter. + > [!NOTE] -> This does not map exactly to ISO 8601. The differences are discussed in the blog entry [ISO 8601 Week of Year format in Microsoft .NET](https://go.microsoft.com/fwlink/?LinkId=160851). Starting with .NET Core 3.0, and solve this problem. +> This does not map exactly to ISO 8601. The differences are discussed in the blog entry [ISO 8601 Week of Year format in Microsoft .NET](https://go.microsoft.com/fwlink/?LinkId=160851). Starting with .NET Core 3.0, and solve this problem. + + The following example uses the current culture's object to determine that January 1, 2011 is in the first week of the year in the Gregorian calendar. - The following example uses the current culture's object to determine that January 1, 2011 is in the first week of the year in the Gregorian calendar. - :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/GetWeekOfYear/getweekofyearex1.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.Calendar.GetWeekOfYear/VB/getweekofyearex1.vb" id="Snippet2"::: - - For some calendars, a call to the method throws an for particular combinations of `rule` and `firstDayOfWeek` values even if `time` is greater than the date returned by that calendar's property. The following table lists the affected calendars, the specific `rule` values, and the range of the earliest supported `time` values. The specific minimum value depends on the value of the `firstDayOfWeek` parameter. - -|Calendar|CalendarWeekRule value|Gregorian date (M/dd/yyyy)|Date in calendar (M/dd/yyyy)| -|--------------|----------------------------|------------------------------------|--------------------------------------| -|||2/19/1901 to 2/25/1901|1/1/1901 to 1/7/1901| -|||2/19/1901 to 2/22/1901|1/01/1901 to 1/04/1901| -|||9/17/1583|1/01/5344| -|||9/17/1583 to 9/23/1583|1/01/5344 to 1/07/5344| -|||9/17/1583 to 9/20/1583|1/01/5344 to 1/04/5344| -|||7/18/0622 to 7/24/0622|1/01/0001 to 1/07/0001| -|||7/18/0622 to 7/21/0622|1/01/0001 to 1/04/0001| -|||1/28/1960 to 2/03/1960|1/01/35 to 1/07/0035| -|||1/28/1960 to 1/31/1960|1/01/0035 to 1/04/0035| -|||1/01/0001 to 1/05/0001|1/03/0001 to 1/07/0001| -|||1/01/0001 to 1/02/0001|1/03/0001 to 1/04/0001| -|||2/14/0918 to 2/20/0918|1/01/0918 to 1/07/0918| -|||2/14/0918 to 2/17/0918|1/01/0918 to 1/04/0918| -|||3/21/0622 to 3/27/0622|1/01/0001 to 1/07/0001| -|||3/21/0622 to 3/24/0622|1/01/0001 to 1/04/0001| -|||2/18/1912 to 2/24/1912|1/01/0001 to 1/07/0001| -|||2/18/1912 to 2/21/1912|1/01/0001 to 1/04/0001| -|||4/30/1900 to 5/06/1900|1/01/1318 to 1/07/1318| -|||4/30/1900 to 5/03/1900|1/01/1318 to 1/04/1318| - - - -## Examples - The following code example shows how the result of varies depending on the and the used. If the specified date is the last day of the year, returns the total number of weeks in that year. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.Calendar.GetWeekOfYear/VB/getweekofyearex1.vb" id="Snippet2"::: + + For some calendars, a call to the method throws an for particular combinations of `rule` and `firstDayOfWeek` values even if `time` is greater than the date returned by that calendar's property. The following table lists the affected calendars, the specific `rule` values, and the range of the earliest supported `time` values. The specific minimum value depends on the value of the `firstDayOfWeek` parameter. + +|Calendar|CalendarWeekRule value|Gregorian date (M/dd/yyyy)|Date in calendar (M/dd/yyyy)| +|--------------|----------------------------|------------------------------------|--------------------------------------| +|||2/19/1901 to 2/25/1901|1/1/1901 to 1/7/1901| +|||2/19/1901 to 2/22/1901|1/01/1901 to 1/04/1901| +|||9/17/1583|1/01/5344| +|||9/17/1583 to 9/23/1583|1/01/5344 to 1/07/5344| +|||9/17/1583 to 9/20/1583|1/01/5344 to 1/04/5344| +|||7/18/0622 to 7/24/0622|1/01/0001 to 1/07/0001| +|||7/18/0622 to 7/21/0622|1/01/0001 to 1/04/0001| +|||1/28/1960 to 2/03/1960|1/01/35 to 1/07/0035| +|||1/28/1960 to 1/31/1960|1/01/0035 to 1/04/0035| +|||1/01/0001 to 1/05/0001|1/03/0001 to 1/07/0001| +|||1/01/0001 to 1/02/0001|1/03/0001 to 1/04/0001| +|||2/14/0918 to 2/20/0918|1/01/0918 to 1/07/0918| +|||2/14/0918 to 2/17/0918|1/01/0918 to 1/04/0918| +|||3/21/0622 to 3/27/0622|1/01/0001 to 1/07/0001| +|||3/21/0622 to 3/24/0622|1/01/0001 to 1/04/0001| +|||2/18/1912 to 2/24/1912|1/01/0001 to 1/07/0001| +|||2/18/1912 to 2/21/1912|1/01/0001 to 1/04/0001| +|||4/30/1900 to 5/06/1900|1/01/1318 to 1/07/1318| +|||4/30/1900 to 5/03/1900|1/01/1318 to 1/04/1318| + + + +## Examples + The following code example shows how the result of varies depending on the and the used. If the specified date is the last day of the year, returns the total number of weeks in that year. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Globalization.Calendar.GetWeekOfYear/CPP/yslin_calendar_getweekofyear.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/GetWeekOfYear/yslin_calendar_getweekofyear.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.Calendar.GetWeekOfYear/VB/yslin_calendar_getweekofyear.vb" id="Snippet1"::: - + ]]> - is earlier than or later than . - - -or- - - is not a valid value. - - -or- - + is earlier than or later than . + + -or- + + is not a valid value. + + -or- + is not a valid value. @@ -2641,15 +2641,15 @@ Only the and the When overridden in a derived class, returns the year in the specified . An integer that represents the year in . - class. - + class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Globalization.Calendar/CPP/calendar.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/Overview/calendar.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.Calendar/VB/calendar.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.Calendar/VB/calendar.vb" id="Snippet1"::: + ]]> @@ -2727,33 +2727,33 @@ Only the and the if the specified day is a leap day; otherwise, . - implementation defines leap years differently. - - A leap day is a day that occurs only in a leap year. For example, in the Gregorian calendar, the 29th day of February is the only leap day. - - - -## Examples - The following code example compares different implementations of the class. - + implementation defines leap years differently. + + A leap day is a day that occurs only in a leap year. For example, in the Gregorian calendar, the 29th day of February is the only leap day. + + + +## Examples + The following code example compares different implementations of the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Globalization.Calendar_Compare/CPP/calendar_compare.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/GetDaysInMonth/calendar_compare.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.Calendar_Compare/VB/calendar_compare.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.Calendar_Compare/VB/calendar_compare.vb" id="Snippet1"::: + ]]> - is outside the range supported by the calendar. - - -or- - - is outside the range supported by the calendar. - - -or- - + is outside the range supported by the calendar. + + -or- + + is outside the range supported by the calendar. + + -or- + is outside the range supported by the calendar. @@ -2815,28 +2815,28 @@ Only the and the if the specified day is a leap day; otherwise, . - implementation defines leap years differently. - - A leap day is a day that occurs only in a leap year. For example, in the Gregorian calendar, the 29th day of February is the only leap day. - + implementation defines leap years differently. + + A leap day is a day that occurs only in a leap year. For example, in the Gregorian calendar, the 29th day of February is the only leap day. + ]]> - is outside the range supported by the calendar. - - -or- - - is outside the range supported by the calendar. - - -or- - - is outside the range supported by the calendar. - - -or- - + is outside the range supported by the calendar. + + -or- + + is outside the range supported by the calendar. + + -or- + + is outside the range supported by the calendar. + + -or- + is outside the range supported by the calendar. The derived class must support when it is passed as the parameter. One way to support is by replacing it with the value stored in Eras[0], which is the value for the current era of the calendar. @@ -2909,29 +2909,29 @@ Only the and the if the specified month is a leap month; otherwise, . - implementation defines leap years differently. - - A leap month is an entire month that occurs only in a leap year. For example, in the Hebrew calendar, Adar Beit is the only leap month. - - - -## Examples - The following code example compares different implementations of the class. - + implementation defines leap years differently. + + A leap month is an entire month that occurs only in a leap year. For example, in the Hebrew calendar, Adar Beit is the only leap month. + + + +## Examples + The following code example compares different implementations of the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Globalization.Calendar_Compare/CPP/calendar_compare.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/GetDaysInMonth/calendar_compare.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.Calendar_Compare/VB/calendar_compare.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.Calendar_Compare/VB/calendar_compare.vb" id="Snippet1"::: + ]]> - is outside the range supported by the calendar. - - -or- - + is outside the range supported by the calendar. + + -or- + is outside the range supported by the calendar. @@ -2990,24 +2990,24 @@ Only the and the if the specified month is a leap month; otherwise, . - implementation defines leap years differently. - - A leap month is an entire month that occurs only in a leap year. For example, in the Hebrew calendar, Adar Beit is the only leap month. - + implementation defines leap years differently. + + A leap month is an entire month that occurs only in a leap year. For example, in the Hebrew calendar, Adar Beit is the only leap month. + ]]> - is outside the range supported by the calendar. - - -or- - - is outside the range supported by the calendar. - - -or- - + is outside the range supported by the calendar. + + -or- + + is outside the range supported by the calendar. + + -or- + is outside the range supported by the calendar. The derived class must support when it is passed as the parameter. One way to support is by replacing it with the value stored in Eras[0], which is the value for the current era of the calendar. @@ -3077,20 +3077,20 @@ Only the and the if the specified year is a leap year; otherwise, . - implementation defines leap years differently. - - - -## Examples - The following code example compares different implementations of the class. - + implementation defines leap years differently. + + + +## Examples + The following code example compares different implementations of the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Globalization.Calendar_Compare/CPP/calendar_compare.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/GetDaysInMonth/calendar_compare.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.Calendar_Compare/VB/calendar_compare.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.Calendar_Compare/VB/calendar_compare.vb" id="Snippet1"::: + ]]> @@ -3149,18 +3149,18 @@ Only the and the if the specified year is a leap year; otherwise, . - implementation defines leap years differently. - + implementation defines leap years differently. + ]]> - is outside the range supported by the calendar. - - -or- - + is outside the range supported by the calendar. + + -or- + is outside the range supported by the calendar. The derived class must support when it is passed as the parameter. One way to support is by replacing it with the value stored in Eras[0], which is the value for the current era of the calendar. @@ -3371,15 +3371,15 @@ Only the and the System.Globalization.Calendar - + A object. Returns a read-only version of the specified object. - The object specified by the parameter, if is read-only. - - -or- - + The object specified by the parameter, if is read-only. + + -or- + A read-only memberwise clone of the object specified by , if is not read-only. To be added. @@ -3456,37 +3456,37 @@ Only the and the Returns a that is set to the specified date and time in the current era. The that is set to the specified date and time in the current era. - and , which support multiple eras based on the reign of the emperor, calling this method can produce an unintended date when an era changes. When instantiating a date using either of these calendars, we recommend that you call the or [JapaneseLunisolarCalendar.ToDateTime(Int32,Int32,Int32,Int32,Int32,Int32,Int32,Int32)](xref:System.Globalization.EastAsianLunisolarCalendar.ToDateTime(System.Int32,System.Int32,System.Int32,System.Int32,System.Int32,System.Int32,System.Int32,System.Int32)) method and explicitly specify an era. +This method returns a date and time based on the current era of a particular calendar. For the and , which support multiple eras based on the reign of the emperor, calling this method can produce an unintended date when an era changes. When instantiating a date using either of these calendars, we recommend that you call the or [JapaneseLunisolarCalendar.ToDateTime(Int32,Int32,Int32,Int32,Int32,Int32,Int32,Int32)](xref:System.Globalization.EastAsianLunisolarCalendar.ToDateTime(System.Int32,System.Int32,System.Int32,System.Int32,System.Int32,System.Int32,System.Int32,System.Int32)) method and explicitly specify an era. ]]> - is outside the range supported by the calendar. - - -or- - - is outside the range supported by the calendar. - - -or- - - is outside the range supported by the calendar. - - -or- - - is less than zero or greater than 23. - - -or- - - is less than zero or greater than 59. - - -or- - - is less than zero or greater than 59. - - -or- - + is outside the range supported by the calendar. + + -or- + + is outside the range supported by the calendar. + + -or- + + is outside the range supported by the calendar. + + -or- + + is less than zero or greater than 23. + + -or- + + is less than zero or greater than 59. + + -or- + + is less than zero or greater than 59. + + -or- + is less than zero or greater than 999. @@ -3554,42 +3554,42 @@ This method returns a date and time based on the current era of a particular cal When overridden in a derived class, returns a that is set to the specified date and time in the specified era. The that is set to the specified date and time in the current era. - method is useful because it can convert any date in the current calendar to a Gregorian calendar date. The Gregorian date can subsequently be used, for example, to compare dates in different calendars or create an equivalent date in a particular calendar. - + method is useful because it can convert any date in the current calendar to a Gregorian calendar date. The Gregorian date can subsequently be used, for example, to compare dates in different calendars or create an equivalent date in a particular calendar. + ]]> - is outside the range supported by the calendar. - - -or- - - is outside the range supported by the calendar. - - -or- - - is outside the range supported by the calendar. - - -or- - - is less than zero or greater than 23. - - -or- - - is less than zero or greater than 59. - - -or- - - is less than zero or greater than 59. - - -or- - - is less than zero or greater than 999. - - -or- - + is outside the range supported by the calendar. + + -or- + + is outside the range supported by the calendar. + + -or- + + is outside the range supported by the calendar. + + -or- + + is less than zero or greater than 23. + + -or- + + is less than zero or greater than 59. + + -or- + + is less than zero or greater than 59. + + -or- + + is less than zero or greater than 999. + + -or- + is outside the range supported by the calendar. The derived class must support when it is passed as the parameter. One way to support is by replacing it with the value stored in the first element of the property array, which is the value for the current era of the calendar. @@ -3648,15 +3648,15 @@ This method returns a date and time based on the current era of a particular cal Converts the specified year to a four-digit year by using the property to determine the appropriate century. An integer that contains the four-digit representation of . - is the last year in the 100-year range that can be represented by a two-digit year. The century is determined by finding the sole occurrence of the two-digit `year` within that 100-year range. For example, if is set to 2029, the 100-year range is from 1930 to 2029. Therefore, a 2-digit value of 30 is interpreted as 1930, while a 2-digit value of 29 is interpreted as 2029. - - If `year` is greater than or equal to 100, the value of `year` is returned unchanged. - - supports either a two-digit year or a four-digit year. Passing a two-digit year value (less than 100) causes the method to convert the value to a four-digit value according to the value representing the appropriate century. If the application supplies a four-digit year value that is within the supported calendar range to , the method returns the actual input value. If the application supplies a four-digit value that is outside the supported calendar range, or if it supplies a negative value, the method throws an exception. - + is the last year in the 100-year range that can be represented by a two-digit year. The century is determined by finding the sole occurrence of the two-digit `year` within that 100-year range. For example, if is set to 2029, the 100-year range is from 1930 to 2029. Therefore, a 2-digit value of 30 is interpreted as 1930, while a 2-digit value of 29 is interpreted as 2029. + + If `year` is greater than or equal to 100, the value of `year` is returned unchanged. + + supports either a two-digit year or a four-digit year. Passing a two-digit year value (less than 100) causes the method to convert the value to a four-digit value according to the value representing the appropriate century. If the application supplies a four-digit year value that is within the supported calendar range to , the method returns the actual input value. If the application supplies a four-digit value that is outside the supported calendar range, or if it supplies a negative value, the method throws an exception. + ]]> @@ -3707,15 +3707,15 @@ This method returns a date and time based on the current era of a particular cal Gets or sets the last year of a 100-year range that can be represented by a 2-digit year. The last year of a 100-year range that can be represented by a 2-digit year. - . The class does not detect changes in the system settings automatically. If the calendar is not supported in the regional and language options, the initial value of this property is the default value defined by the class. - - Your application should set this value to 99 to indicate that 2-digit years are to be taken literally. For example, if this property is set to 99, the 100-year range is from 0 (not a valid value for most calendars) to 99. Therefore, a 2-digit value of 30 is interpreted as 30. - + . The class does not detect changes in the system settings automatically. If the calendar is not supported in the regional and language options, the initial value of this property is the default value defined by the class. + + Your application should set this value to 99 to indicate that 2-digit years are to be taken literally. For example, if this property is set to 99, the 100-year range is from 0 (not a valid value for most calendars) to 99. Therefore, a 2-digit value of 30 is interpreted as 30. + ]]> The current object is read-only. diff --git a/xml/System.Globalization/CharUnicodeInfo.xml b/xml/System.Globalization/CharUnicodeInfo.xml index 9c58ca37b5f..1618c8a9d73 100644 --- a/xml/System.Globalization/CharUnicodeInfo.xml +++ b/xml/System.Globalization/CharUnicodeInfo.xml @@ -70,43 +70,43 @@ Retrieves information about a Unicode character. This class cannot be inherited. - enumeration defines the possible character categories. - - Use the class to obtain the value for a specific character. The class defines methods that return the following Unicode character values: - -- The specific category to which a character or surrogate pair belongs. The value returned is a member of the enumeration. - -- Numeric value. Applies only to numeric characters, including fractions, subscripts, superscripts, Roman numerals, currency numerators, encircled numbers, and script-specific digits. - -- Digit value. Applies to numeric characters that can be combined with other numeric characters to represent a whole number in a numbering system. - -- Decimal digit value. Applies only to characters that represent decimal digits in the decimal (base 10) system. A decimal digit can be one of ten digits, from zero through nine. These characters are members of the category. - -In addition, the class is used internally by a number of other .NET types and methods that rely on character classification. These include: - -- The class, which works with textual elements instead of single characters in a string. - -- The overloads of the method, which determine the category to which a character or surrogate pair belongs. - -- The [character classes](/dotnet/standard/base-types/character-classes-in-regular-expressions) recognized by , .NET's regular expression engine. - -When using this class in your applications, keep in mind the following programming considerations for using the type. The type can be difficult to use, and strings are generally preferable for representing linguistic content. - -- A object does not always correspond to a single character. Although the type represents a single 16-bit value, some characters (such as grapheme clusters and surrogate pairs) consist of two or more UTF-16 code units. For more information, see "Char Objects and Unicode Characters" in the class. - + The [Unicode Standard](https://home.unicode.org/) defines a number of Unicode character categories. For example, a character might be categorized as an uppercase letter, a lowercase letter, a decimal digit number, a letter number, a paragraph separator, a math symbol, or a currency symbol. Your application can use the character category to govern string-based operations, such as parsing or extracting substring with regular expressions. The enumeration defines the possible character categories. + + Use the class to obtain the value for a specific character. The class defines methods that return the following Unicode character values: + +- The specific category to which a character or surrogate pair belongs. The value returned is a member of the enumeration. + +- Numeric value. Applies only to numeric characters, including fractions, subscripts, superscripts, Roman numerals, currency numerators, encircled numbers, and script-specific digits. + +- Digit value. Applies to numeric characters that can be combined with other numeric characters to represent a whole number in a numbering system. + +- Decimal digit value. Applies only to characters that represent decimal digits in the decimal (base 10) system. A decimal digit can be one of ten digits, from zero through nine. These characters are members of the category. + +In addition, the class is used internally by a number of other .NET types and methods that rely on character classification. These include: + +- The class, which works with textual elements instead of single characters in a string. + +- The overloads of the method, which determine the category to which a character or surrogate pair belongs. + +- The [character classes](/dotnet/standard/base-types/character-classes-in-regular-expressions) recognized by , .NET's regular expression engine. + +When using this class in your applications, keep in mind the following programming considerations for using the type. The type can be difficult to use, and strings are generally preferable for representing linguistic content. + +- A object does not always correspond to a single character. Although the type represents a single 16-bit value, some characters (such as grapheme clusters and surrogate pairs) consist of two or more UTF-16 code units. For more information, see "Char Objects and Unicode Characters" in the class. + - The notion of a "character" is also flexible. A character is often thought of as a glyph, but many glyphs require multiple code points. For example, ä can be represented either by two code points ("a" plus U+0308, which is the combining diaeresis), or by a single code point ("ä" or U+00A4). Some languages have many letters, characters, and glyphs that require multiple code points, which can cause confusion in linguistic content representation. For example, there is a ΰ (U+03B0, Greek small letter upsilon with dialytika and tonos), but there is no equivalent capital letter. Uppercasing such a value simply retrieves the original value. - -## Examples - The following code example shows the values returned by each method for different types of characters. - + +## Examples + The following code example shows the values returned by each method for different types of characters. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Globalization.CharUnicodeInfo_Char/CPP/charunicodeinfo_char.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Globalization/CharUnicodeInfo/Overview/charunicodeinfo_char.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.CharUnicodeInfo_Char/VB/charunicodeinfo_char.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.CharUnicodeInfo_Char/VB/charunicodeinfo_char.vb" id="Snippet1"::: + ]]> @@ -175,33 +175,33 @@ Each version of the Unicode standard includes information on changes to the Unic System.Int32 - + The Unicode character for which to get the decimal digit value. Gets the decimal digit value of the specified numeric character. - The decimal digit value of the specified numeric character. - - -or- - + The decimal digit value of the specified numeric character. + + -or- + -1, if the specified character is not a decimal digit. - category that can represent one of ten digits in the decimal (base 10) numbering system, from zero through nine. It includes characters such as U+0030 (DIGIT ZERO) through U+0039 (DIGIT NINE), U+0660 (ARABIC-INDIC DIGIT ZERO) through U+0669 (ARABIC-INDIC DIGIT NINE), U+07C0 (NKO DIGIT ZERO) through U+07C9 (NKO DIGIT NINE), and U+1040 (MYANMAR DIGIT ZERO) through U+1049 (MYANMAR DIGIT NINE). - - For more information about Unicode characters, see the [Unicode Standard](https://go.microsoft.com/fwlink/?linkid=37123). - - - -## Examples - The following code example shows the values returned by each method for different types of characters. - + category that can represent one of ten digits in the decimal (base 10) numbering system, from zero through nine. It includes characters such as U+0030 (DIGIT ZERO) through U+0039 (DIGIT NINE), U+0660 (ARABIC-INDIC DIGIT ZERO) through U+0669 (ARABIC-INDIC DIGIT NINE), U+07C0 (NKO DIGIT ZERO) through U+07C9 (NKO DIGIT NINE), and U+1040 (MYANMAR DIGIT ZERO) through U+1049 (MYANMAR DIGIT NINE). + + For more information about Unicode characters, see the [Unicode Standard](https://go.microsoft.com/fwlink/?linkid=37123). + + + +## Examples + The following code example shows the values returned by each method for different types of characters. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Globalization.CharUnicodeInfo_Char/CPP/charunicodeinfo_char.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Globalization/CharUnicodeInfo/Overview/charunicodeinfo_char.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.CharUnicodeInfo_Char/VB/charunicodeinfo_char.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.CharUnicodeInfo_Char/VB/charunicodeinfo_char.vb" id="Snippet1"::: + ]]> @@ -243,35 +243,35 @@ Each version of the Unicode standard includes information on changes to the Unic System.Int32 - - + + The containing the Unicode character for which to get the decimal digit value. The index of the Unicode character for which to get the decimal digit value. Gets the decimal digit value of the numeric character at the specified index of the specified string. - The decimal digit value of the numeric character at the specified index of the specified string. - - -or- - + The decimal digit value of the numeric character at the specified index of the specified string. + + -or- + -1, if the character at the specified index of the specified string is not a decimal digit. - category that can represent one of ten digits in the decimal (base 10) numbering system, from zero through nine. It includes characters such as U+0030 (DIGIT ZERO) through U+0039 (DIGIT NINE), U+0660 (ARABIC-INDIC DIGIT ZERO) through U+0669 (ARABIC-INDIC DIGIT NINE), U+07C0 (NKO DIGIT ZERO) through U+07C9 (NKO DIGIT NINE), and U+1040 (MYANMAR DIGIT ZERO) through U+1049 (MYANMAR DIGIT NINE). - - For more information about Unicode characters, see the [Unicode Standard](https://go.microsoft.com/fwlink/?linkid=37123). - - - -## Examples - The following code example shows the values returned by each method for different types of characters. - + category that can represent one of ten digits in the decimal (base 10) numbering system, from zero through nine. It includes characters such as U+0030 (DIGIT ZERO) through U+0039 (DIGIT NINE), U+0660 (ARABIC-INDIC DIGIT ZERO) through U+0669 (ARABIC-INDIC DIGIT NINE), U+07C0 (NKO DIGIT ZERO) through U+07C9 (NKO DIGIT NINE), and U+1040 (MYANMAR DIGIT ZERO) through U+1049 (MYANMAR DIGIT NINE). + + For more information about Unicode characters, see the [Unicode Standard](https://go.microsoft.com/fwlink/?linkid=37123). + + + +## Examples + The following code example shows the values returned by each method for different types of characters. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Globalization.CharUnicodeInfo_String/CPP/charunicodeinfo_string.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Globalization/CharUnicodeInfo/GetDecimalDigitValue/charunicodeinfo_string.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.CharUnicodeInfo_String/VB/charunicodeinfo_string.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.CharUnicodeInfo_String/VB/charunicodeinfo_string.vb" id="Snippet1"::: + ]]> @@ -327,33 +327,33 @@ Each version of the Unicode standard includes information on changes to the Unic System.Int32 - + The Unicode character for which to get the digit value. Gets the digit value of the specified numeric character. - The digit value of the specified numeric character. - - -or- - + The digit value of the specified numeric character. + + -or- + -1, if the specified character is not a digit. - @@ -395,35 +395,35 @@ Each version of the Unicode standard includes information on changes to the Unic System.Int32 - - + + The containing the Unicode character for which to get the digit value. The index of the Unicode character for which to get the digit value. Gets the digit value of the numeric character at the specified index of the specified string. - The digit value of the numeric character at the specified index of the specified string. - - -or- - + The digit value of the numeric character at the specified index of the specified string. + + -or- + -1, if the character at the specified index of the specified string is not a digit. - @@ -492,31 +492,31 @@ Each version of the Unicode standard includes information on changes to the Unic The Unicode character for which to get the numeric value. Gets the numeric value associated with the specified character. - The numeric value associated with the specified character. - - -or- - + The numeric value associated with the specified character. + + -or- + -1, if the specified character is not a numeric character. - method assumes that `ch` corresponds to a single linguistic character and checks whether that character can be converted to a decimal digit. However, some numbers in the Unicode standard are represented by two objects that form a surrogate pair. For example, the Aegean numbering system consists of code points U+10107 through U+10133. The following example uses the method to instantiate a string that represents AEGEAN NUMBER ONE. As the output from the example shows, the method returns -1 if it is passed either a high surrogate or a low surrogate of this character. - + method assumes that `ch` corresponds to a single linguistic character and checks whether that character can be converted to a decimal digit. However, some numbers in the Unicode standard are represented by two objects that form a surrogate pair. For example, the Aegean numbering system consists of code points U+10107 through U+10133. The following example uses the method to instantiate a string that represents AEGEAN NUMBER ONE. As the output from the example shows, the method returns -1 if it is passed either a high surrogate or a low surrogate of this character. + :::code language="csharp" source="~/snippets/csharp/System.Globalization/CharUnicodeInfo/GetNumericValue/getnumericvalue1.cs" interactive="try-dotnet-method" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.charunicodeinfo.getnumericvalue/vb/getnumericvalue1.vb" id="Snippet2"::: - - - -## Examples - The following code example shows the values returned by each method for different types of characters. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.charunicodeinfo.getnumericvalue/vb/getnumericvalue1.vb" id="Snippet2"::: + + + +## Examples + The following code example shows the values returned by each method for different types of characters. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Globalization.CharUnicodeInfo_Char/CPP/charunicodeinfo_char.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Globalization/CharUnicodeInfo/Overview/charunicodeinfo_char.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.CharUnicodeInfo_Char/VB/charunicodeinfo_char.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.CharUnicodeInfo_Char/VB/charunicodeinfo_char.vb" id="Snippet1"::: + ]]> @@ -573,31 +573,31 @@ Each version of the Unicode standard includes information on changes to the Unic The containing the Unicode character for which to get the numeric value. The index of the Unicode character for which to get the numeric value. Gets the numeric value associated with the character at the specified index of the specified string. - The numeric value associated with the character at the specified index of the specified string. - - -or- - + The numeric value associated with the character at the specified index of the specified string. + + -or- + -1, if the character at the specified index of the specified string is not a numeric character. - object at position `index` is the first character of a valid surrogate pair, the method determines whether the surrogate pair forms a numeric digit, and, if it does, returns its numeric value. For example, the Aegean numbering system consists of code points U+10107 through U+10133. The following example uses the method to instantiate a string that represents each Aegean number. As the output from the example shows, the method returns the correct numeric value if it is passed the high surrogate of an Aegean number. However, if it is passed the low surrogate, it considers only the low surrogate in isolation and returns -1. - + object at position `index` is the first character of a valid surrogate pair, the method determines whether the surrogate pair forms a numeric digit, and, if it does, returns its numeric value. For example, the Aegean numbering system consists of code points U+10107 through U+10133. The following example uses the method to instantiate a string that represents each Aegean number. As the output from the example shows, the method returns the correct numeric value if it is passed the high surrogate of an Aegean number. However, if it is passed the low surrogate, it considers only the low surrogate in isolation and returns -1. + :::code language="csharp" source="~/snippets/csharp/System.Globalization/CharUnicodeInfo/GetNumericValue/getnumericvalue1.cs" interactive="try-dotnet-method" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.charunicodeinfo.getnumericvalue/vb/getnumericvalue1.vb" id="Snippet3"::: - - - -## Examples - The following code example shows the values returned by each method for different types of characters. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.charunicodeinfo.getnumericvalue/vb/getnumericvalue1.vb" id="Snippet3"::: + + + +## Examples + The following code example shows the values returned by each method for different types of characters. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Globalization.CharUnicodeInfo_String/CPP/charunicodeinfo_string.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Globalization/CharUnicodeInfo/GetDecimalDigitValue/charunicodeinfo_string.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.CharUnicodeInfo_String/VB/charunicodeinfo_string.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.CharUnicodeInfo_String/VB/charunicodeinfo_string.vb" id="Snippet1"::: + ]]> @@ -668,27 +668,27 @@ Each version of the Unicode standard includes information on changes to the Unic Gets the Unicode category of the specified character. A value indicating the category of the specified character. - class returns the category of a Unicode character. For more information on Unicode characters, see the [Unicode Standard](https://go.microsoft.com/fwlink/?linkid=37123). - - The method assumes that `ch` corresponds to a single linguistic character and returns its category. This means that, for surrogate pairs, it returns instead of the category to which the surrogate belongs. For example, the Ugaritic alphabet occupies code points U+10380 to U+1039F. The following example uses the method to instantiate a string that represents UGARITIC LETTER ALPA (U+10380), which is the first letter of the Ugaritic alphabet. As the output from the example shows, the method returns `false` if it is passed either the high surrogate or the low surrogate of this character. - + class returns the category of a Unicode character. For more information on Unicode characters, see the [Unicode Standard](https://go.microsoft.com/fwlink/?linkid=37123). + + The method assumes that `ch` corresponds to a single linguistic character and returns its category. This means that, for surrogate pairs, it returns instead of the category to which the surrogate belongs. For example, the Ugaritic alphabet occupies code points U+10380 to U+1039F. The following example uses the method to instantiate a string that represents UGARITIC LETTER ALPA (U+10380), which is the first letter of the Ugaritic alphabet. As the output from the example shows, the method returns `false` if it is passed either the high surrogate or the low surrogate of this character. + :::code language="csharp" source="~/snippets/csharp/System.Globalization/CharUnicodeInfo/GetUnicodeCategory/getunicodecategory1.cs" interactive="try-dotnet-method" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.charunicodeinfo.getunicodecategory/vb/getunicodecategory1.vb" id="Snippet1"::: - - Note that does not always return the same value as the method when passed a particular character as a parameter. The method is designed to reflect the current version of the Unicode standard. In contrast, although the method usually reflects the current version of the Unicode standard, it might return a character's category based on a previous version of the standard, or it might return a category that differs from the current standard to preserve backward compatibility. - - - -## Examples - The following code example shows the values returned by each method for different types of characters. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.charunicodeinfo.getunicodecategory/vb/getunicodecategory1.vb" id="Snippet1"::: + + Note that does not always return the same value as the method when passed a particular character as a parameter. The method is designed to reflect the current version of the Unicode standard. In contrast, although the method usually reflects the current version of the Unicode standard, it might return a character's category based on a previous version of the standard, or it might return a category that differs from the current standard to preserve backward compatibility. + + + +## Examples + The following code example shows the values returned by each method for different types of characters. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Globalization.CharUnicodeInfo_Char/CPP/charunicodeinfo_char.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Globalization/CharUnicodeInfo/Overview/charunicodeinfo_char.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.CharUnicodeInfo_Char/VB/charunicodeinfo_char.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.CharUnicodeInfo_Char/VB/charunicodeinfo_char.vb" id="Snippet1"::: + ]]> @@ -789,27 +789,27 @@ Each version of the Unicode standard includes information on changes to the Unic Gets the Unicode category of the character at the specified index of the specified string. A value indicating the category of the character at the specified index of the specified string. - class returns the category of a Unicode character. For more information on Unicode characters, see the [Unicode Standard](https://go.microsoft.com/fwlink/?linkid=37123). - - If the object at position `index` is the first character of a valid surrogate pair, the method returns the Unicode category of the surrogate pair instead of returning . For example, the Ugaritic alphabet occupies code points U+10380 to U+1039F. The following example uses the method to instantiate a string that represents UGARITIC LETTER ALPA (U+10380), which is the first letter of the Ugaritic alphabet. As the output from the example shows, the method returns if it is passed the high surrogate of this character, which indicates that it considers the surrogate pair. However, if it is passed the low surrogate, it considers only the low surrogate in isolation and returns . - + class returns the category of a Unicode character. For more information on Unicode characters, see the [Unicode Standard](https://go.microsoft.com/fwlink/?linkid=37123). + + If the object at position `index` is the first character of a valid surrogate pair, the method returns the Unicode category of the surrogate pair instead of returning . For example, the Ugaritic alphabet occupies code points U+10380 to U+1039F. The following example uses the method to instantiate a string that represents UGARITIC LETTER ALPA (U+10380), which is the first letter of the Ugaritic alphabet. As the output from the example shows, the method returns if it is passed the high surrogate of this character, which indicates that it considers the surrogate pair. However, if it is passed the low surrogate, it considers only the low surrogate in isolation and returns . + :::code language="csharp" source="~/snippets/csharp/System.Globalization/CharUnicodeInfo/GetUnicodeCategory/getunicodecategory1.cs" interactive="try-dotnet-method" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.charunicodeinfo.getunicodecategory/vb/getunicodecategory1.vb" id="Snippet2"::: - - Note that method does not always return the same value as the method when passed a particular character as a parameter. The method is designed to reflect the current version of the Unicode standard. In contrast, although the method usually reflects the current version of the Unicode standard, it might return a character's category based on a previous version of the standard, or it might return a category that differs from the current standard to preserve backward compatibility. - - - -## Examples - The following code example shows the values returned by each method for different types of characters. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.charunicodeinfo.getunicodecategory/vb/getunicodecategory1.vb" id="Snippet2"::: + + Note that method does not always return the same value as the method when passed a particular character as a parameter. The method is designed to reflect the current version of the Unicode standard. In contrast, although the method usually reflects the current version of the Unicode standard, it might return a character's category based on a previous version of the standard, or it might return a category that differs from the current standard to preserve backward compatibility. + + + +## Examples + The following code example shows the values returned by each method for different types of characters. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Globalization.CharUnicodeInfo_String/CPP/charunicodeinfo_string.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Globalization/CharUnicodeInfo/GetDecimalDigitValue/charunicodeinfo_string.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.CharUnicodeInfo_String/VB/charunicodeinfo_string.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.CharUnicodeInfo_String/VB/charunicodeinfo_string.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.Globalization/CompareInfo.xml b/xml/System.Globalization/CompareInfo.xml index 778d7c5d4af..70f47af00ef 100644 --- a/xml/System.Globalization/CompareInfo.xml +++ b/xml/System.Globalization/CompareInfo.xml @@ -1037,7 +1037,7 @@ System.Globalization.CompareInfo - + An integer representing the culture identifier. @@ -1177,8 +1177,8 @@ System.Globalization.CompareInfo - - + + An integer representing the culture identifier. @@ -1242,8 +1242,8 @@ System.Globalization.CompareInfo - - + + A string representing the culture name. @@ -1529,7 +1529,7 @@ System.Globalization.SortKey - + The string for which a object is obtained. @@ -1589,8 +1589,8 @@ System.Globalization.SortKey - - + + The string for which a object is obtained. @@ -2141,9 +2141,9 @@ Use System.Int32 - - - + + + The string to search. @@ -2326,9 +2326,9 @@ Use System.Int32 - - - + + + The string to search. @@ -3428,7 +3428,7 @@ This method has greater overhead than other System.Boolean - + A Unicode character. @@ -3537,7 +3537,7 @@ This method has greater overhead than other System.Boolean - + A string of zero or more Unicode characters. @@ -4321,9 +4321,9 @@ This method has greater overhead than other System.Int32 - - - + + + The string to search. @@ -4512,9 +4512,9 @@ This method has greater overhead than other System.Int32 - - - + + + The string to search. @@ -5422,7 +5422,7 @@ This method has greater overhead than other System.Void - + The object that initiated the callback. diff --git a/xml/System.Globalization/CultureInfo.xml b/xml/System.Globalization/CultureInfo.xml index 0a6bc898328..7919569ab9b 100644 --- a/xml/System.Globalization/CultureInfo.xml +++ b/xml/System.Globalization/CultureInfo.xml @@ -144,7 +144,7 @@ System.Globalization - + A predefined identifier, property of an existing object, or Windows-only culture identifier. @@ -321,8 +321,8 @@ The property of the new System.Globalization - - + + A predefined identifier, property of an existing object, or Windows-only culture identifier. @@ -414,8 +414,8 @@ Predefined culture identifiers available on Windows systems are listed in the ** System.Globalization - - + + A predefined name, of an existing , or Windows-only culture name. is not case-sensitive. @@ -767,7 +767,7 @@ If `name` is , the constr System.Globalization.CultureInfo - + A predefined name or the name of an existing object. is not case-sensitive. @@ -1787,7 +1787,7 @@ csc /resource:GreetingStrings.resources Example1.cs System.Globalization.CultureInfo - + A locale identifier (LCID). @@ -1852,7 +1852,7 @@ csc /resource:GreetingStrings.resources Example1.cs System.Globalization.CultureInfo - + The name of a culture. is not case-sensitive. @@ -1972,8 +1972,8 @@ Setting `predefinedOnly` to `true` will ensure a culture is created only if the System.Globalization.CultureInfo - - + + The name of a culture. is not case-sensitive. @@ -2041,7 +2041,7 @@ Setting `predefinedOnly` to `true` will ensure a culture is created only if the System.Globalization.CultureInfo - + The name of a language as specified by the RFC 4646 standard. @@ -2115,7 +2115,7 @@ Setting `predefinedOnly` to `true` will ensure a culture is created only if the System.Globalization.CultureInfo[] - + A bitwise combination of the enumeration values that filter the cultures to retrieve. diff --git a/xml/System.Globalization/CultureNotFoundException.xml b/xml/System.Globalization/CultureNotFoundException.xml index b87199f3bd2..40cf85d80e4 100644 --- a/xml/System.Globalization/CultureNotFoundException.xml +++ b/xml/System.Globalization/CultureNotFoundException.xml @@ -79,24 +79,24 @@ The exception that is thrown when a method attempts to construct a culture that is not available. - exception is thrown whenever the construction of an invalid culture is eventually attempted within a method. Most commonly, this exception is thrown when a call to one of the following methods fails to create or return a culture: - -- constructors. - -- The method. - -- The method. - + exception is thrown whenever the construction of an invalid culture is eventually attempted within a method. Most commonly, this exception is thrown when a call to one of the following methods fails to create or return a culture: + +- constructors. + +- The method. + +- The method. + > [!WARNING] -> On Windows 7 and later operating systems, the .NET Framework retrieves culture data from the operating system. The exception is thrown if the operating system is unable to find the culture, and the culture is not a custom culture or a replacement culture. - - If the calling code attempted to instantiate a object by using a culture name, the property contains the invalid name, and the property of the object returned by the property is `false`. If the calling code attempted to instantiate a object by using a culture identifier, the property of the object returned by the property contains the invalid identifier, and the value of the property is `null`. - - uses the HRESULT COR_E_ARGUMENT, which has the value 0x80070057. - +> On Windows 7 and later operating systems, the .NET Framework retrieves culture data from the operating system. The exception is thrown if the operating system is unable to find the culture, and the culture is not a custom culture or a replacement culture. + + If the calling code attempted to instantiate a object by using a culture name, the property contains the invalid name, and the property of the object returned by the property is `false`. If the calling code attempted to instantiate a object by using a culture identifier, the property of the object returned by the property contains the invalid identifier, and the value of the property is `null`. + + uses the HRESULT COR_E_ARGUMENT, which has the value 0x80070057. + ]]> @@ -110,11 +110,11 @@ Initializes a new instance of the class. - uses the HRESULT COR_E_ARGUMENT, which has the value 0x80070057. - + uses the HRESULT COR_E_ARGUMENT, which has the value 0x80070057. + ]]> @@ -156,11 +156,11 @@ Initializes a new instance of the class with its message string set to a system-supplied message. - uses the HRESULT COR_E_ARGUMENT, which has the value 0x80070057. - + uses the HRESULT COR_E_ARGUMENT, which has the value 0x80070057. + ]]> @@ -207,13 +207,13 @@ The error message to display with this exception. Initializes a new instance of the class with the specified error message. - property of the new instance using the value of the `message` parameter. The content of the `message` parameter is intended to be understood by humans. The caller of this constructor is required to ensure that this string has been localized for the current system culture. - - uses the HRESULT COR_E_ARGUMENT, which has the value 0x80070057. - + property of the new instance using the value of the `message` parameter. The content of the `message` parameter is intended to be understood by humans. The caller of this constructor is required to ensure that this string has been localized for the current system culture. + + uses the HRESULT COR_E_ARGUMENT, which has the value 0x80070057. + ]]> @@ -269,19 +269,19 @@ - - + + The object that holds the serialized object data. The contextual information about the source or destination. Initializes a new instance of the class using the specified serialization data and context. - @@ -330,13 +330,13 @@ The exception that is the cause of the current exception. If the parameter is not a null reference, the current exception is raised in a block that handles the inner exception. Initializes a new instance of the class with a specified error message and a reference to the inner exception that is the cause of this exception. - property of the new instance using the value of the `message` parameter. The content of the `message` parameter is intended to be understood by humans. The caller of this constructor is required to ensure that this string has been localized for the current system culture. - - An exception that is thrown as a direct result of a previous exception should include a reference to the previous exception in the property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. - + property of the new instance using the value of the `message` parameter. The content of the `message` parameter is intended to be understood by humans. The caller of this constructor is required to ensure that this string has been localized for the current system culture. + + An exception that is thrown as a direct result of a previous exception should include a reference to the previous exception in the property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. + ]]> @@ -385,15 +385,15 @@ The error message to display with this exception. Initializes a new instance of the class with a specified error message and the name of the parameter that is the cause this exception. - property of the new instance using the value of the `message` parameter. The content of the `message` parameter is intended to be understood by humans. The caller of this constructor is required to ensure that this string has been localized for the current system culture. - - This constructor initializes the property of the new instance using `paramName`. The content of `paramName` is intended to be understood by humans. - - uses the HRESULT COR_E_ARGUMENT, which has the value 0x80070057. - + property of the new instance using the value of the `message` parameter. The content of the `message` parameter is intended to be understood by humans. The caller of this constructor is required to ensure that this string has been localized for the current system culture. + + This constructor initializes the property of the new instance using `paramName`. The content of `paramName` is intended to be understood by humans. + + uses the HRESULT COR_E_ARGUMENT, which has the value 0x80070057. + ]]> @@ -432,9 +432,9 @@ System.Globalization - - - + + + The error message to display with this exception. @@ -442,13 +442,13 @@ The exception that is the cause of the current exception. If the parameter is not a null reference, the current exception is raised in a block that handles the inner exception. Initializes a new instance of the class with a specified error message, the invalid Culture ID, and a reference to the inner exception that is the cause of this exception. - property of the new instance using the value of the `message` parameter. The content of the `message` parameter is intended to be understood by humans. The caller of this constructor is required to ensure that this string has been localized for the current system culture. - - property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. - + property of the new instance using the value of the `message` parameter. The content of the `message` parameter is intended to be understood by humans. The caller of this constructor is required to ensure that this string has been localized for the current system culture. + + property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. + ]]> @@ -487,9 +487,9 @@ System.Globalization - - - + + + The name of the parameter that is the cause the current exception. @@ -497,15 +497,15 @@ The error message to display with this exception. Initializes a new instance of the class with a specified error message, the invalid Culture ID, and the name of the parameter that is the cause this exception. - property of the new instance using the value of the `message` parameter. The content of the `message` parameter is intended to be understood by humans. The caller of this constructor is required to ensure that this string has been localized for the current system culture. - - This constructor initializes the property of the new instance using `paramName`. The content of `paramName` is intended to be understood by humans. - - uses the HRESULT COR_E_ARGUMENT, which has the value 0x80070057. - + property of the new instance using the value of the `message` parameter. The content of the `message` parameter is intended to be understood by humans. The caller of this constructor is required to ensure that this string has been localized for the current system culture. + + This constructor initializes the property of the new instance using `paramName`. The content of `paramName` is intended to be understood by humans. + + uses the HRESULT COR_E_ARGUMENT, which has the value 0x80070057. + ]]> @@ -556,13 +556,13 @@ The exception that is the cause of the current exception. If the parameter is not a null reference, the current exception is raised in a block that handles the inner exception. Initializes a new instance of the class with a specified error message, the invalid Culture Name, and a reference to the inner exception that is the cause of this exception. - property of the new instance using the value of the `message` parameter. The content of the `message` parameter is intended to be understood by humans. The caller of this constructor is required to ensure that this string has been localized for the current system culture. - - property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. - + property of the new instance using the value of the `message` parameter. The content of the `message` parameter is intended to be understood by humans. The caller of this constructor is required to ensure that this string has been localized for the current system culture. + + property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. + ]]> @@ -613,15 +613,15 @@ The error message to display with this exception. Initializes a new instance of the class with a specified error message, the invalid Culture Name, and the name of the parameter that is the cause this exception. - property of the new instance using the value of the `message` parameter. The content of the `message` parameter is intended to be understood by humans. The caller of this constructor is required to ensure that this string has been localized for the current system culture. - - This constructor initializes the property of the new instance using `paramName`. The content of `paramName` is intended to be understood by humans. - - uses the HRESULT COR_E_ARGUMENT, which has the value 0x80070057. - + property of the new instance using the value of the `message` parameter. The content of the `message` parameter is intended to be understood by humans. The caller of this constructor is required to ensure that this string has been localized for the current system culture. + + This constructor initializes the property of the new instance using `paramName`. The content of `paramName` is intended to be understood by humans. + + uses the HRESULT COR_E_ARGUMENT, which has the value 0x80070057. + ]]> @@ -683,21 +683,21 @@ System.Void - - + + The object that holds the serialized object data. The contextual information about the source or destination. Sets the object with the parameter name and additional exception information. - 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 . - + 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 . + ]]> @@ -743,11 +743,11 @@ Gets the culture identifier that cannot be found. The invalid culture identifier. - object by using an invalid culture identifier, the property of the object returned by the property contains the invalid identifier. Otherwise, its property is `false`. - + object by using an invalid culture identifier, the property of the object returned by the property contains the invalid identifier. Otherwise, its property is `false`. + ]]> @@ -794,11 +794,11 @@ Gets the culture name that cannot be found. The invalid culture name. - object by using a culture name, the property contains the invalid name. Otherwise, its value is `null`. - + object by using a culture name, the property contains the invalid name. Otherwise, its value is `null`. + ]]> diff --git a/xml/System.Globalization/DateTimeFormatInfo.xml b/xml/System.Globalization/DateTimeFormatInfo.xml index 101a9eb0118..2db53071067 100644 --- a/xml/System.Globalization/DateTimeFormatInfo.xml +++ b/xml/System.Globalization/DateTimeFormatInfo.xml @@ -1335,7 +1335,7 @@ Changing the value of this property affects the following properties as well: System.String[] - + A standard format string. @@ -1875,7 +1875,7 @@ Changing the value of this property affects the following properties as well: System.String - + One of the values. @@ -2675,8 +2675,8 @@ Changing the value of this property affects the following properties as well: System.Void - - + + An array of custom format strings. diff --git a/xml/System.Globalization/RegionInfo.xml b/xml/System.Globalization/RegionInfo.xml index 653535d7cd7..751d12c4d67 100644 --- a/xml/System.Globalization/RegionInfo.xml +++ b/xml/System.Globalization/RegionInfo.xml @@ -136,7 +136,7 @@ - + A culture identifier. diff --git a/xml/System.Globalization/StringInfo.xml b/xml/System.Globalization/StringInfo.xml index d656871212e..e7f2dd3f85e 100644 --- a/xml/System.Globalization/StringInfo.xml +++ b/xml/System.Globalization/StringInfo.xml @@ -75,41 +75,41 @@ Provides functionality to split a string into text elements and to iterate through those text elements. - class enables you to work with a string as a series of textual elements rather than individual objects. - -To instantiate a object that represents a specified string, you can do either of the following: - -- Call the constructor and pass it the string that the object is to represent as an argument. - -- Call the default constructor, and assign the string that the object is to represent to the property. - - You can work with the individual text elements in a string in two ways: - -- By enumerating each text element. To do this, you call the method, and then repeatedly call the method on the returned object until the method returns `false`. - -- By calling the method to retrieve an array that contains the starting index of each text element. You can then retrieve individual text elements by passing these indexes to the method. - -The following example illustrates both ways of working with the text elements in a string. It creates two strings: - -- `strCombining`, which is a string of Arabic characters that includes three text elements with multiple objects. The first text element is the base character ARABIC LETTER ALEF (U+0627) followed by ARABIC HAMZA BELOW (U+0655) and ARABIC KASRA (U+0650). The second text element is ARABIC LETTER HEH (U+0647) followed by ARABIC FATHA (U+064E). The third text element is ARABIC LETTER BEH (U+0628) followed by ARABIC DAMMATAN (U+064C). - -- `strSurrogates`, which is a string that includes three surrogate pairs: GREEK ACROPHONIC FIVE TALENTS (U+10148) from the Supplementary Multilingual Plane, U+20026 from the Supplementary Ideographic Plane, and U+F1001 from the private user area. The UTF-16 encoding of each character is a surrogate pair that consists of a high surrogate followed by a low surrogate. - -Each string is parsed once by the method and then by the method. Both methods correctly parse the text elements in the two strings and display the results of the parsing operation. - +.NET defines a text element as a unit of text that is displayed as a single character, that is, a grapheme. A text element can be a base character, a surrogate pair, or a combining character sequence. The [Unicode Standard](https://go.microsoft.com/fwlink/?linkid=37123) defines a surrogate pair as a coded character representation for a single abstract character that consists of a sequence of two code units, where the first unit of the pair is a high surrogate and the second is a low surrogate. The Unicode Standard defines a combining character sequence as a combination of a base character and one or more combining characters. A surrogate pair can represent a base character or a combining character. + +The class enables you to work with a string as a series of textual elements rather than individual objects. + +To instantiate a object that represents a specified string, you can do either of the following: + +- Call the constructor and pass it the string that the object is to represent as an argument. + +- Call the default constructor, and assign the string that the object is to represent to the property. + + You can work with the individual text elements in a string in two ways: + +- By enumerating each text element. To do this, you call the method, and then repeatedly call the method on the returned object until the method returns `false`. + +- By calling the method to retrieve an array that contains the starting index of each text element. You can then retrieve individual text elements by passing these indexes to the method. + +The following example illustrates both ways of working with the text elements in a string. It creates two strings: + +- `strCombining`, which is a string of Arabic characters that includes three text elements with multiple objects. The first text element is the base character ARABIC LETTER ALEF (U+0627) followed by ARABIC HAMZA BELOW (U+0655) and ARABIC KASRA (U+0650). The second text element is ARABIC LETTER HEH (U+0647) followed by ARABIC FATHA (U+064E). The third text element is ARABIC LETTER BEH (U+0628) followed by ARABIC DAMMATAN (U+064C). + +- `strSurrogates`, which is a string that includes three surrogate pairs: GREEK ACROPHONIC FIVE TALENTS (U+10148) from the Supplementary Multilingual Plane, U+20026 from the Supplementary Ideographic Plane, and U+F1001 from the private user area. The UTF-16 encoding of each character is a surrogate pair that consists of a high surrogate followed by a low surrogate. + +Each string is parsed once by the method and then by the method. Both methods correctly parse the text elements in the two strings and display the results of the parsing operation. + :::code language="csharp" source="~/snippets/csharp/System.Globalization/StringInfo/Overview/indexing1.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.stringinfo.class/vb/indexing1.vb" id="Snippet1"::: - -## Examples -This example uses the and methods of the class to manipulate a string that contains surrogate and combining characters. - +## Examples + +This example uses the and methods of the class to manipulate a string that contains surrogate and combining characters. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/StringInfo/cpp/StringInfo.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Globalization/StringInfo/Overview/StringInfo.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/StringInfo/vb/stringinfo.vb" id="Snippet1"::: @@ -172,11 +172,11 @@ This example uses the Initializes a new instance of the class. - object is initialized to the empty string (""). You can assign another string to it by using the property. You can also instantiate a object that represents a specified string in a single step by calling the constructor. - + object is initialized to the empty string (""). You can assign another string to it by using the property. You can also instantiate a object that represents a specified string in a single step by calling the constructor. + ]]> @@ -224,11 +224,11 @@ This example uses the A string to initialize this object. Initializes a new instance of the class to a specified string. - property. - + property. + ]]> @@ -352,11 +352,11 @@ This example uses the Calculates a hash code for the value of the current object. A 32-bit signed integer hash code based on the string value of this object. - is dependent on its implementation, which might change from one version of the common language runtime to another. This might happen to improve the performance of . To make the behavior of constant, the application should override the runtime implementation of with an implementation known to never change. - + is dependent on its implementation, which might change from one version of the common language runtime to another. This might happen to improve the performance of . To make the behavior of constant, the application should override the runtime implementation of with an implementation known to never change. + ]]> @@ -419,14 +419,14 @@ This example uses the Gets the first text element in a specified string. A string containing the first text element in the specified string. - object generated by the method. - + object generated by the method. + ]]> @@ -490,14 +490,14 @@ This example uses the Gets the text element at the specified index of the specified string. A string containing the text element at the specified index of the specified string. - generated by the method. - + +.NET defines a text element as a unit of text that is displayed as a single character, that is, a grapheme. A text element can be a base character, a surrogate pair, or a combining character sequence. The [Unicode Standard](https://go.microsoft.com/fwlink/?linkid=37123) defines a surrogate pair as a coded character representation for a single abstract character that consists of a sequence of two code units, where the first unit of the pair is a high surrogate and the second is a low surrogate. The Unicode Standard defines a combining character sequence as a combination of a base character and one or more combining characters. A surrogate pair can represent a base character or a combining character. + + This method only returns the first text element of the substring that starts at the specified index. To iterate through the text elements of the string, the application should use the generated by the method. + ]]> @@ -714,30 +714,30 @@ A grapheme cluster is a sequence of one or more Unicode code points that should Returns an enumerator that iterates through the text elements of the entire string. A for the entire string. - throws an exception. - - Initially, the enumerator is positioned before the first text element in the string. also brings the enumerator back to this position. Therefore, after an enumerator is created or after is called, must be called to advance the enumerator to the first text element of the string before reading the value of . - - returns the same object until either or is called. - - After the end of the string is passed, the enumerator is again in an invalid state and calling returns `false`. Calling throws an exception if the last call to returned `false`. - - - -## Examples - The following example demonstrates calling the method. This example is part of a larger example provided for the class. - + throws an exception. + + Initially, the enumerator is positioned before the first text element in the string. also brings the enumerator back to this position. Therefore, after an enumerator is created or after is called, must be called to advance the enumerator to the first text element of the string before reading the value of . + + returns the same object until either or is called. + + After the end of the string is passed, the enumerator is again in an invalid state and calling returns `false`. Calling throws an exception if the last call to returned `false`. + + + +## Examples + The following example demonstrates calling the method. This example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/StringInfo/cpp/StringInfo.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Globalization/StringInfo/Overview/StringInfo.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/StringInfo/vb/stringinfo.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/StringInfo/vb/stringinfo.vb" id="Snippet1"::: + ]]> @@ -800,21 +800,21 @@ A grapheme cluster is a sequence of one or more Unicode code points that should Returns an enumerator that iterates through the text elements of the string, starting at the specified index. A for the string starting at . - throws an exception. - - Initially, the enumerator is positioned before the first text element in the string. also brings the enumerator back to this position. Therefore, after an enumerator is created or after is called, must be called to advance the enumerator to the first text element of the string before reading the value of . - - returns the same object until either or is called. - - After the end of the string is passed, the enumerator is again in an invalid state and calling returns `false`. Calling throws an exception if the last call to returned `false`. - + throws an exception. + + Initially, the enumerator is positioned before the first text element in the string. also brings the enumerator back to this position. Therefore, after an enumerator is created or after is called, must be called to advance the enumerator to the first text element of the string before reading the value of . + + returns the same object until either or is called. + + After the end of the string is passed, the enumerator is again in an invalid state and calling returns `false`. Calling throws an exception if the last call to returned `false`. + ]]> @@ -921,33 +921,33 @@ A grapheme cluster is a sequence of one or more Unicode code points that should Returns the indexes of each base character, high surrogate, or control character within the specified string. An array of integers that contains the zero-based indexes of each base character, high surrogate, or control character within the specified string. - method and property provide an easy to use implementation of the functionality offered by the method. - - - -## Examples - The following example demonstrates calling the method. This code example is part of a larger example provided for the class. - + method and property provide an easy to use implementation of the functionality offered by the method. + + + +## Examples + The following example demonstrates calling the method. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/StringInfo/cpp/StringInfo.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Globalization/StringInfo/Overview/StringInfo.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/StringInfo/vb/stringinfo.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/StringInfo/vb/stringinfo.vb" id="Snippet1"::: + ]]> @@ -998,15 +998,15 @@ A grapheme cluster is a sequence of one or more Unicode code points that should Gets or sets the value of the current object. The string that is the value of the current object. - object is instantiated, its property is set to one of the following values: - -- if the default is called. You should then use the property to assign the string that this object rperesents. - -- The string supplied as the `value` argument to the constructor. - + object is instantiated, its property is set to one of the following values: + +- if the default is called. You should then use the property to assign the string that this object rperesents. + +- The string supplied as the `value` argument to the constructor. + ]]> The value in a set operation is . @@ -1059,25 +1059,25 @@ A grapheme cluster is a sequence of one or more Unicode code points that should System.String - + The zero-based index of a text element in this object. Retrieves a substring of text elements from the current object starting from a specified text element and continuing through the last text element. A substring of text elements in this object, starting from the text element index specified by the parameter and continuing through the last text element in this object. - method returns a substring that consists of the text elements for which the indexes are 1, 2, 3, and 4. - + method returns a substring that consists of the text elements for which the indexes are 1, 2, 3, and 4. + ]]> - is less than zero. - - -or- - + is less than zero. + + -or- + The string that is the value of the current object is the empty string (""). @@ -1118,8 +1118,8 @@ A grapheme cluster is a sequence of one or more Unicode code points that should System.String - - + + The zero-based index of a text element in this object. @@ -1127,30 +1127,30 @@ A grapheme cluster is a sequence of one or more Unicode code points that should Retrieves a substring of text elements from the current object starting from a specified text element and continuing through the specified number of text elements. A substring of text elements in this object. The substring consists of the number of text elements specified by the parameter and starts from the text element index specified by the parameter. - method returns a substring that consists of the text elements for which the indexes are 1, 2, and 3. - + method returns a substring that consists of the text elements for which the indexes are 1, 2, and 3. + ]]> - is less than zero. - - -or- - - is greater than or equal to the length of the string that is the value of the current object. - - -or- - - is less than zero. - - -or- - - The string that is the value of the current object is the empty string (""). - - -or- - + is less than zero. + + -or- + + is greater than or equal to the length of the string that is the value of the current object. + + -or- + + is less than zero. + + -or- + + The string that is the value of the current object is the empty string (""). + + -or- + + specify an index that is greater than the number of text elements in this object. diff --git a/xml/System.Globalization/TextInfo.xml b/xml/System.Globalization/TextInfo.xml index 700d43e6e1c..c6925935dd0 100644 --- a/xml/System.Globalization/TextInfo.xml +++ b/xml/System.Globalization/TextInfo.xml @@ -863,7 +863,7 @@ The property always reflects a spec System.Globalization.TextInfo - + A object. @@ -930,7 +930,7 @@ The property always reflects a spec System.Void - + The source of the deserialization event. @@ -1208,7 +1208,7 @@ The property always reflects a spec System.String - + The string to convert to title case. diff --git a/xml/System.IO.IsolatedStorage/IsolatedStorage.xml b/xml/System.IO.IsolatedStorage/IsolatedStorage.xml index df3e33f7a1f..ff2e31088e9 100644 --- a/xml/System.IO.IsolatedStorage/IsolatedStorage.xml +++ b/xml/System.IO.IsolatedStorage/IsolatedStorage.xml @@ -56,17 +56,17 @@ Represents the abstract base class from which all isolated storage implementations must derive. - class. - + For information about file-based isolated storage, see the class. + > [!IMPORTANT] -> Isolated storage is not available for Windows 8.x Store apps. Instead, use the application data classes in the `Windows.Storage` namespaces included in the Windows Runtime API to store local data and files. For more information, see [Application data](https://go.microsoft.com/fwlink/?LinkId=229175) in the Windows Dev Center. - +> Isolated storage is not available for Windows 8.x Store apps. Instead, use the application data classes in the `Windows.Storage` namespaces included in the Windows Runtime API to store local data and files. For more information, see [Application data](https://go.microsoft.com/fwlink/?LinkId=229175) in the Windows Dev Center. + ]]> Isolated Storage @@ -154,11 +154,11 @@ Gets an application identity that scopes isolated storage. An that represents the identity. - The code lacks the required to access this object. These permissions are granted by the runtime based on security policy. @@ -255,11 +255,11 @@ When overridden in a derived class, gets the available free space for isolated storage, in bytes. The available free space for isolated storage, in bytes. - property overrides this property. - + property overrides this property. + ]]> An operation was performed that requires access to , but that property is not defined for this store. Stores that are obtained by using enumerations do not have a well-defined property, because partial evidence is used to open the store. @@ -317,11 +317,11 @@ Gets a value representing the current size of isolated storage. The number of storage units currently used within the isolated storage scope. - implements this property. In the case of objects, this value is in bytes. In the case of implementations of other storage objects, such as a database, this value might be in other units of storage. - + implements this property. In the case of objects, this value is in bytes. In the case of implementations of other storage objects, such as a database, this value might be in other units of storage. + ]]> The current size of the isolated store is undefined. @@ -399,18 +399,18 @@ System.Security.Permissions.IsolatedStoragePermission - + The object that contains the set of permissions granted to code attempting to use isolated storage. When implemented by a derived class, returns a permission that represents access to isolated storage from within a permission set. An object. - @@ -462,11 +462,11 @@ in all cases. - method overrides this method. - + method overrides this method. + ]]> @@ -529,11 +529,11 @@ The type of that you can choose from the list of for the calling application. lets the object choose the evidence. Initializes a new object. - The assembly specified has insufficient permissions to create isolated stores. @@ -595,11 +595,11 @@ The type of that you can choose from the list of present in the assembly of the calling application. lets the object choose the evidence. Initializes a new object. - The assembly specified has insufficient permissions to create isolated stores. @@ -657,13 +657,13 @@ Gets a value representing the maximum amount of space available for isolated storage. When overridden in a derived class, this value can take different units of measure. The maximum amount of isolated storage space in bytes. Derived classes can return different units of value. - property returns the value of , which is expressed in bytes. Derived classes can express the value in other units of measure. A potential example of such an implementation is an isolated storage database. - - You cannot set , but the quota is configured in the security policy, and can be set. Code receives a quota of space on the basis of its evidence, so the same code can receive a different quota if it is run with different evidence (for example, the same application run locally and from a share on an intranet can receive different quotas). implements this property. - + property returns the value of , which is expressed in bytes. Derived classes can express the value in other units of measure. A potential example of such an implementation is an isolated storage database. + + You cannot set , but the quota is configured in the security policy, and can be set. Code receives a quota of space on the basis of its evidence, so the same code can receive a different quota if it is run with different evidence (for example, the same application run locally and from a share on an intranet can receive different quotas). implements this property. + ]]> The quota has not been defined. @@ -711,11 +711,11 @@ When overridden in a derived class, gets a value that represents the maximum amount of space available for isolated storage. The limit of isolated storage space, in bytes. - property overrides this property. - + property overrides this property. + ]]> An operation was performed that requires access to , but that property is not defined for this store. Stores that are obtained by using enumerations do not have a well-defined property, because partial evidence is used to open the store. @@ -759,11 +759,11 @@ When overridden in a derived class, removes the individual isolated store and all contained data. - implements this method. - + implements this method. + ]]> @@ -806,11 +806,11 @@ Gets an enumeration value specifying the scope used to isolate the store. A bitwise combination of values specifying the scope used to isolate the store. - @@ -853,11 +853,11 @@ Gets a backslash character that can be used in a directory string. When overridden in a derived class, another character might be returned. The default implementation returns the '\\' (backslash) character. - @@ -903,11 +903,11 @@ Gets a period character that can be used in a directory string. When overridden in a derived class, another character might be returned. The default implementation returns the '.' (period) character. - @@ -957,11 +957,11 @@ When overridden in a derived class, gets a value that represents the amount of the space used for isolated storage. The used amount of isolated storage space, in bytes. - property overrides this property. - + property overrides this property. + ]]> An operation was performed that requires access to , but that property is not defined for this store. Stores that are obtained by using enumerations do not have a well-defined property, because partial evidence is used to open the store. diff --git a/xml/System.IO.IsolatedStorage/IsolatedStorageException.xml b/xml/System.IO.IsolatedStorage/IsolatedStorageException.xml index baf6466c656..7850fc53d6c 100644 --- a/xml/System.IO.IsolatedStorage/IsolatedStorageException.xml +++ b/xml/System.IO.IsolatedStorage/IsolatedStorageException.xml @@ -62,19 +62,19 @@ The exception that is thrown when an operation in isolated storage fails. - operations are not supported for isolated storage. - - For a list of initial property values for an instance of `IsolatedStorageException`, see the constructors. - + operations are not supported for isolated storage. + + For a list of initial property values for an instance of `IsolatedStorageException`, see the constructors. + ]]> @@ -126,16 +126,16 @@ Initializes a new instance of the class with default properties. - . - -|Property|Value| -|--------------|-----------| -||`null`.| -||The localized error message string.| - + . + +|Property|Value| +|--------------|-----------| +||`null`.| +||The localized error message string.| + ]]> @@ -180,16 +180,16 @@ The error message that explains the reason for the exception. Initializes a new instance of the class with a specified error message. - . - -|Property|Value| -|--------------|-----------| -||`null`.| -||The error message string.| - + . + +|Property|Value| +|--------------|-----------| +||`null`.| +||The error message string.| + ]]> @@ -244,19 +244,19 @@ - - + + The object that holds the serialized object data. The contextual information about the source or destination. Initializes a new instance of the class with serialized data. - @@ -303,18 +303,18 @@ The exception that is the cause of the current exception. If the parameter is not , the current exception is raised in a block that handles the inner exception. Initializes a new instance of the class with a specified error message and a reference to the inner exception that is the cause of this exception. - property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||The inner exception reference.| -||The error message string.| - + property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||The inner exception reference.| +||The error message string.| + ]]> diff --git a/xml/System.IO.IsolatedStorage/IsolatedStorageFile.xml b/xml/System.IO.IsolatedStorage/IsolatedStorageFile.xml index 378aa06d54b..74ab4993438 100644 --- a/xml/System.IO.IsolatedStorage/IsolatedStorageFile.xml +++ b/xml/System.IO.IsolatedStorage/IsolatedStorageFile.xml @@ -67,26 +67,26 @@ Represents an isolated storage area containing files and directories. - objects exist. Applications can use isolated storage to save data in their own isolated portion of the file system, without having to specify a particular path within the file system. Since isolated stores are scoped to particular assemblies, most other managed code will not be able to access your code's data (highly trusted managed code and administration tools can access stores from other assemblies). Unmanaged code can access any isolated stores. - - For more information, see [Isolated Storage](/dotnet/standard/io/isolated-storage). - - 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. - + objects exist. Applications can use isolated storage to save data in their own isolated portion of the file system, without having to specify a particular path within the file system. Since isolated stores are scoped to particular assemblies, most other managed code will not be able to access your code's data (highly trusted managed code and administration tools can access stores from other assemblies). Unmanaged code can access any isolated stores. + + For more information, see [Isolated Storage](/dotnet/standard/io/isolated-storage). + + 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] -> Isolated storage is not available for Windows 8.x Store apps. Instead, use the application data classes in the `Windows.Storage` namespaces included in the Windows Runtime API to store local data and files. For more information, see [Application data](https://go.microsoft.com/fwlink/?LinkId=229175) in the Windows Dev Center. - - - -## Examples - The following code example illustrates how to create files and directories in an isolated store. First, a store that is isolated by user, domain, and assembly is retrieved and placed in the `isoStore` variable. The method is then called to create directories, and two instances of the class create files in these directories. - +> Isolated storage is not available for Windows 8.x Store apps. Instead, use the application data classes in the `Windows.Storage` namespaces included in the Windows Runtime API to store local data and files. For more information, see [Application data](https://go.microsoft.com/fwlink/?LinkId=229175) in the Windows Dev Center. + + + +## Examples + The following code example illustrates how to create files and directories in an isolated store. First, a store that is isolated by user, domain, and assembly is retrieved and placed in the `isoStore` variable. The method is then called to create directories, and two instances of the class create files in these directories. + :::code language="csharp" source="~/snippets/csharp/System.IO.IsolatedStorage/IsolatedStorageFile/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/conceptual.isolatedstorage/vb/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/conceptual.isolatedstorage/vb/source.vb" id="Snippet1"::: + ]]> Isolated Storage @@ -139,10 +139,10 @@ The available free space for isolated storage, in bytes. To be added. The isolated store is closed. - The isolated store has been removed. - - -or- - + The isolated store has been removed. + + -or- + Isolated storage is disabled. The isolated store has been disposed. Isolated Storage @@ -192,15 +192,15 @@ Closes a store previously opened with , , or . - method. For the complete context of this example, see the overview. - + method. For the complete context of this example, see the overview. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/CPP/source.cpp" id="Snippet10"::: :::code language="csharp" source="~/snippets/csharp/System.IO.IsolatedStorage/IsolatedStorageFile/Close/source.cs" id="Snippet10"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/VB/source.vb" id="Snippet10"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/VB/source.vb" id="Snippet10"::: + ]]> Isolated Storage @@ -264,11 +264,11 @@ The name of the destination file. This cannot be a directory or an existing file. Copies an existing file to a new file. - method overload to overwrite an existing file. - + method overload to overwrite an existing file. + ]]> @@ -281,18 +281,18 @@ was not found. was not found. - The isolated store has been removed. - - -or- - - Isolated storage is disabled. - - -or- - - exists. - - -or- - + The isolated store has been removed. + + -or- + + Isolated storage is disabled. + + -or- + + exists. + + -or- + An I/O error has occurred. Isolated Storage @@ -352,11 +352,11 @@ if the destination file can be overwritten; otherwise, . Copies an existing file to a new file, and optionally overwrites an existing file. - @@ -369,14 +369,14 @@ was not found. was not found. - The isolated store has been removed. - - -or- - - Isolated storage is disabled. - - -or- - + The isolated store has been removed. + + -or- + + Isolated storage is disabled. + + -or- + An I/O error has occurred. Isolated Storage @@ -429,20 +429,20 @@ The relative path of the directory to create within the isolated storage scope. Creates a directory in the isolated storage scope. - method returns without creating a new directory. The [How to: Create Files and Directories in Isolated Storage](/dotnet/standard/io/how-to-create-files-and-directories-in-isolated-storage) example demonstrates the use of the method - - - -## Examples - The following code example demonstrates the method. For the complete context of this example, see the overview. - + method returns without creating a new directory. The [How to: Create Files and Directories in Isolated Storage](/dotnet/standard/io/how-to-create-files-and-directories-in-isolated-storage) example demonstrates the use of the method + + + +## Examples + The following code example demonstrates the method. For the complete context of this example, see the overview. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/CPP/source.cpp" id="Snippet7"::: :::code language="csharp" source="~/snippets/csharp/System.IO.IsolatedStorage/IsolatedStorageFile/Close/source.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/VB/source.vb" id="Snippet7"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/VB/source.vb" id="Snippet7"::: + ]]> The current code has insufficient permissions to create isolated storage directory. @@ -497,17 +497,17 @@ Creates a file in the isolated store. A new isolated storage file. - constructor. - + constructor. + ]]> - The isolated store has been removed. - - -or- - + The isolated store has been removed. + + -or- + Isolated storage is disabled. is malformed. @@ -574,24 +574,24 @@ Gets the current size of the isolated storage. The total number of bytes of storage currently in use within the isolated storage scope. - property. - - - -## Examples - The following code example demonstrates the property. For the complete context of this example, see the overview. - + property. + + + +## Examples + The following code example demonstrates the property. For the complete context of this example, see the overview. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/CPP/source.cpp" id="Snippet5"::: :::code language="csharp" source="~/snippets/csharp/System.IO.IsolatedStorage/IsolatedStorageFile/Close/source.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/VB/source.vb" id="Snippet5"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/VB/source.vb" id="Snippet5"::: + ]]> The property is unavailable. The current store has a roaming scope or is not open. @@ -647,20 +647,20 @@ The relative path of the directory to delete within the isolated storage scope. Deletes a directory in the isolated storage scope. - method. - - - -## Examples + method. + + + +## Examples :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/CPP/source.cpp" id="Snippet8"::: :::code language="csharp" source="~/snippets/csharp/System.IO.IsolatedStorage/IsolatedStorageFile/Close/source.cs" id="Snippet8"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/VB/source.vb" id="Snippet8"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/VB/source.vb" id="Snippet8"::: + ]]> The directory could not be deleted. @@ -716,22 +716,22 @@ The relative path of the file to delete within the isolated storage scope. Deletes a file in the isolated storage scope. - method. - - - -## Examples - The following code example uses the method to delete a number of files in isolated storage. - + method. + + + +## Examples + The following code example uses the method to delete a number of files in isolated storage. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/CPP/source.cpp" id="Snippet6"::: :::code language="csharp" source="~/snippets/csharp/System.IO.IsolatedStorage/IsolatedStorageFile/Close/source.cs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/VB/source.vb" id="Snippet6"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/VB/source.vb" id="Snippet6"::: + ]]> The target file is open or the path is incorrect. @@ -795,10 +795,10 @@ is . The isolated store is closed. The isolated store has been disposed. - The isolated store has been removed. - - -or- - + The isolated store has been removed. + + -or- + Isolated storage is disabled. Isolated Storage @@ -845,23 +845,23 @@ Releases all resources used by the . - . 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 was occupying. - + . 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 was occupying. + > [!NOTE] -> Always call Dispose before you release your last reference to the . Otherwise, the resources the is using will not be freed until garbage collection calls the object's method. - - - -## Examples - The following code example opens an isolated storage file, uses it to write information to a stream, closes the file, and then uses the method to release all resources. - +> Always call Dispose before you release your last reference to the . Otherwise, the resources the is using will not be freed until garbage collection calls the object's method. + + + +## Examples + The following code example opens an isolated storage file, uses it to write information to a stream, closes the file, and then uses the method to release all resources. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/CPP/source.cpp" id="Snippet10"::: :::code language="csharp" source="~/snippets/csharp/System.IO.IsolatedStorage/IsolatedStorageFile/Close/source.cs" id="Snippet10"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/VB/source.vb" id="Snippet10"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/VB/source.vb" id="Snippet10"::: + ]]> Isolated Storage @@ -1011,11 +1011,11 @@ Returns the creation date and time of a specified file or directory. The creation date and time for the specified file or directory. This value is expressed in local time. - @@ -1024,10 +1024,10 @@ is . The isolated store has been closed. The isolated store has been disposed. - The isolated store has been removed. - - -or- - + The isolated store has been removed. + + -or- + Isolated storage is disabled. Isolated Storage @@ -1090,11 +1090,11 @@ Enumerates the directories at the root of an isolated store. An array of relative paths of directories at the root of the isolated store. A zero-length array specifies that there are no directories at the root. - method with "*" specified for the search pattern. - + method with "*" specified for the search pattern. + ]]> The isolated store has been disposed. @@ -1154,26 +1154,26 @@ Enumerates the directories in an isolated storage scope that match a given search pattern. An array of the relative paths of directories in the isolated storage scope that match . A zero-length array specifies that there are no directories that match. - class. - - For information on getting file names, see the method. - - The [How to: Find Existing Files and Directories in Isolated Storage](/dotnet/standard/io/how-to-find-existing-files-and-directories-in-isolated-storage) example demonstrates the use of the method. - - - -## Examples - The following code example demonstrates the method. For the complete context of this example, see the overview. - + class. + + For information on getting file names, see the method. + + The [How to: Find Existing Files and Directories in Isolated Storage](/dotnet/standard/io/how-to-find-existing-files-and-directories-in-isolated-storage) example demonstrates the use of the method. + + + +## Examples + The following code example demonstrates the method. For the complete context of this example, see the overview. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/CPP/source.cpp" id="Snippet16"::: :::code language="csharp" source="~/snippets/csharp/System.IO.IsolatedStorage/IsolatedStorageFile/Close/source.cs" id="Snippet16"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/VB/source.vb" id="Snippet16"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/VB/source.vb" id="Snippet16"::: + ]]> @@ -1227,18 +1227,18 @@ System.Collections.IEnumerator - + Represents the for which to return isolated stores. and are the only combinations supported. Gets the enumerator for the stores within an isolated storage scope. Enumerator for the stores within the specified isolated storage scope. - method. - + method. + ]]> Isolated Storage @@ -1298,11 +1298,11 @@ Enumerates the file names at the root of an isolated store. An array of relative paths of files at the root of the isolated store. A zero-length array specifies that there are no files at the root. - method with "*" specified for the search pattern. - + method with "*" specified for the search pattern. + ]]> The isolated store has been removed. @@ -1360,24 +1360,24 @@ Gets the file names that match a search pattern. An array of relative paths of files in the isolated storage scope that match . A zero-length array specifies that there are no files that match. - . - - For information about how to find directory names, see the method. - - The [How to: Find Existing Files and Directories in Isolated Storage](/dotnet/standard/io/how-to-find-existing-files-and-directories-in-isolated-storage) example demonstrates the use of the method. - - - -## Examples - The following code example demonstrates the method. For the complete context of this example, see the overview. - + . + + For information about how to find directory names, see the method. + + The [How to: Find Existing Files and Directories in Isolated Storage](/dotnet/standard/io/how-to-find-existing-files-and-directories-in-isolated-storage) example demonstrates the use of the method. + + + +## Examples + The following code example demonstrates the method. For the complete context of this example, see the overview. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/CPP/source.cpp" id="Snippet16"::: :::code language="csharp" source="~/snippets/csharp/System.IO.IsolatedStorage/IsolatedStorageFile/Close/source.cs" id="Snippet16"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/VB/source.vb" id="Snippet16"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/VB/source.vb" id="Snippet16"::: + ]]> @@ -1439,11 +1439,11 @@ Returns the date and time a specified file or directory was last accessed. The date and time that the specified file or directory was last accessed. This value is expressed in local time. - @@ -1452,10 +1452,10 @@ is . The isolated store has been closed. The isolated store has been disposed. - The isolated store has been removed. - - -or- - + The isolated store has been removed. + + -or- + Isolated storage is disabled. Isolated Storage @@ -1511,11 +1511,11 @@ Returns the date and time a specified file or directory was last written to. The date and time that the specified file or directory was last written to. This value is expressed in local time. - @@ -1524,10 +1524,10 @@ is . The isolated store has been closed. The isolated store has been disposed. - The isolated store has been removed. - - -or- - + The isolated store has been removed. + + -or- + Isolated storage is disabled. Isolated Storage @@ -1576,27 +1576,27 @@ Obtains machine-scoped isolated storage corresponding to the calling code's application identity. An object corresponding to the isolated storage scope based on the calling code's application identity. - is functionally equivalent to the following code: - + is functionally equivalent to the following code: + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/CPP/remarks.cpp" id="Snippet18"::: :::code language="csharp" source="~/snippets/csharp/System.IO.IsolatedStorage/IsolatedStorageFile/Close/remarks.cs" id="Snippet18"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/VB/remarks.vb" id="Snippet18"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/VB/remarks.vb" id="Snippet18"::: + ]]> - The application identity of the caller could not be determined. - - -or- - - The granted permission set for the application domain could not be determined. - - -or- - + The application identity of the caller could not be determined. + + -or- + + The granted permission set for the application domain could not be determined. + + -or- + An isolated storage location cannot be initialized. Sufficient isolated storage permissions have not been granted. Isolated Storage @@ -1646,20 +1646,20 @@ Obtains machine-scoped isolated storage corresponding to the calling code's assembly identity. An object corresponding to the isolated storage scope based on the calling code's assembly identity. - is functionally equivalent to the following code: - + is functionally equivalent to the following code: + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/CPP/remarks.cpp" id="Snippet19"::: :::code language="csharp" source="~/snippets/csharp/System.IO.IsolatedStorage/IsolatedStorageFile/Close/remarks.cs" id="Snippet19"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/VB/remarks.vb" id="Snippet19"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/VB/remarks.vb" id="Snippet19"::: + > [!NOTE] -> Different assemblies running within the same application domain always have distinct isolated stores. - +> Different assemblies running within the same application domain always have distinct isolated stores. + ]]> An isolated storage location cannot be initialized. @@ -1711,46 +1711,46 @@ Obtains machine-scoped isolated storage corresponding to the application domain identity and the assembly identity. An object corresponding to the , based on a combination of the application domain identity and the assembly identity. - is functionally equivalent to the following code: - + is functionally equivalent to the following code: + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/CPP/remarks.cpp" id="Snippet20"::: :::code language="csharp" source="~/snippets/csharp/System.IO.IsolatedStorage/IsolatedStorageFile/Close/remarks.cs" id="Snippet20"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/VB/remarks.vb" id="Snippet20"::: - - Different assemblies running within the same application domain always have distinct isolated stores. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/VB/remarks.vb" id="Snippet20"::: + + Different assemblies running within the same application domain always have distinct isolated stores. + > [!NOTE] -> will return an object without a quota if the application domain into which the assembly is installed does not have . Later attempts to create an object using the object that does not have a quota will fail with an . - - - -## Examples - The following code example demonstrates the method. For the complete context of this example, see the overview. - +> will return an object without a quota if the application domain into which the assembly is installed does not have . Later attempts to create an object using the object that does not have a quota will fail with an . + + + +## Examples + The following code example demonstrates the method. For the complete context of this example, see the overview. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/CPP/source.cpp" id="Snippet10"::: :::code language="csharp" source="~/snippets/csharp/System.IO.IsolatedStorage/IsolatedStorageFile/Close/source.cs" id="Snippet10"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/VB/source.vb" id="Snippet10"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/VB/source.vb" id="Snippet10"::: + ]]> Sufficient isolated storage permissions have not been granted. - The store failed to open. - - -or- - - The assembly specified has insufficient permissions to create isolated stores. - - -or- - - The permissions for the application domain cannot be determined. - - -or- - + The store failed to open. + + -or- + + The assembly specified has insufficient permissions to create isolated stores. + + -or- + + The permissions for the application domain cannot be determined. + + -or- + An isolated storage location cannot be initialized. Isolated Storage @@ -1779,7 +1779,7 @@ System.Security.Permissions.IsolatedStoragePermission - + To be added. @@ -1839,8 +1839,8 @@ System.IO.IsolatedStorage.IsolatedStorageFile - - + + [System.Runtime.CompilerServices.Nullable(2)] @@ -1855,30 +1855,30 @@ Obtains isolated storage corresponding to the given application identity. An object that represents the parameters. - [!NOTE] -> If the `scope` parameter is and the application domain in which the assembly is installed does not have , the method will return an object without a quota. Later attempts to create an object using the object that does not have a quota will fail with an . - +> If the `scope` parameter is and the application domain in which the assembly is installed does not have , the method will return an object without a quota. Later attempts to create an object using the object that does not have a quota will fail with an . + ]]> Sufficient isolated storage permissions have not been granted. The identity has not been passed in. The is invalid. - An isolated storage location cannot be initialized. - - -or- - - contains the enumeration value , but the application identity of the caller cannot be determined,because the for the current application domain returned . - - -or- - - contains the value , but the permissions for the application domain cannot be determined. - - -or- - + An isolated storage location cannot be initialized. + + -or- + + contains the enumeration value , but the application identity of the caller cannot be determined,because the for the current application domain returned . + + -or- + + contains the value , but the permissions for the application domain cannot be determined. + + -or- + contains the value , but the permissions for the calling assembly cannot be determined. @@ -1927,8 +1927,8 @@ System.IO.IsolatedStorage.IsolatedStorageFile - - + + [System.Runtime.CompilerServices.Nullable(2)] @@ -1943,30 +1943,30 @@ Obtains isolated storage corresponding to the isolation scope and the application identity object. An object that represents the parameters. - [!NOTE] -> If the `scope` parameter is and the application domain in which the assembly is installed does not have , the method will return an object without a quota. Later attempts to create an object using the object that does not have a quota will fail with an . - +> If the `scope` parameter is and the application domain in which the assembly is installed does not have , the method will return an object without a quota. Later attempts to create an object using the object that does not have a quota will fail with an . + ]]> Sufficient isolated storage permissions have not been granted. The identity has not been passed in. The is invalid. - An isolated storage location cannot be initialized. - - -or- - - contains the enumeration value , but the application identity of the caller cannot be determined, because the for the current application domain returned . - - -or- - - contains the value , but the permissions for the application domain cannot be determined. - - -or- - + An isolated storage location cannot be initialized. + + -or- + + contains the enumeration value , but the application identity of the caller cannot be determined, because the for the current application domain returned . + + -or- + + contains the value , but the permissions for the application domain cannot be determined. + + -or- + contains the value , but the permissions for the calling assembly cannot be determined. @@ -2020,9 +2020,9 @@ System.IO.IsolatedStorage.IsolatedStorageFile - - - + + + A bitwise combination of the enumeration values. @@ -2031,35 +2031,35 @@ Obtains the isolated storage corresponding to the given application domain and assembly evidence objects. An object that represents the parameters. - [!NOTE] -> If the `scope` parameter is and the application domain in which the assembly is installed does not have , the method will return an object without a quota. Later attempts to create an object using the object that does not have a quota will fail with an . - +> If the `scope` parameter is and the application domain in which the assembly is installed does not have , the method will return an object without a quota. Later attempts to create an object using the object that does not have a quota will fail with an . + ]]> Sufficient isolated storage permissions have not been granted. - Neither nor has been passed in. This verifies that the correct constructor is being used. - - -or- - + Neither nor has been passed in. This verifies that the correct constructor is being used. + + -or- + Either or is . The is invalid. - An isolated storage location cannot be initialized. - - -or- - - contains the enumeration value , but the application identity of the caller cannot be determined, because the for the current application domain returned . - - -or- - - contains the value , but the permissions for the application domain cannot be determined. - - -or- - + An isolated storage location cannot be initialized. + + -or- + + contains the enumeration value , but the application identity of the caller cannot be determined, because the for the current application domain returned . + + -or- + + contains the value , but the permissions for the application domain cannot be determined. + + -or- + contains the value , but the permissions for the calling assembly cannot be determined. @@ -2113,9 +2113,9 @@ System.IO.IsolatedStorage.IsolatedStorageFile - - - + + + A bitwise combination of the enumeration values. @@ -2124,45 +2124,45 @@ Obtains isolated storage corresponding to the isolated storage scope given the application domain and assembly evidence types. An object that represents the parameters. - most likely to be called from application code. - - This overload of opens an isolated store for the evidence types that are passed in. - + most likely to be called from application code. + + This overload of opens an isolated store for the evidence types that are passed in. + > [!NOTE] -> If the `scope` parameter is and the application domain in which the assembly is installed does not have , the method will return an object without a quota. Later attempts to create an object using the object that does not have a quota will fail with an . - - - -## Examples - The following code example demonstrates the method. For the complete context of this example, see the overview. - +> If the `scope` parameter is and the application domain in which the assembly is installed does not have , the method will return an object without a quota. Later attempts to create an object using the object that does not have a quota will fail with an . + + + +## Examples + The following code example demonstrates the method. For the complete context of this example, see the overview. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/CPP/source.cpp" id="Snippet15"::: :::code language="csharp" source="~/snippets/csharp/System.IO.IsolatedStorage/IsolatedStorageFile/Close/source.cs" id="Snippet15"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/VB/source.vb" id="Snippet15"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/VB/source.vb" id="Snippet15"::: + ]]> Sufficient isolated storage permissions have not been granted. The is invalid. - The evidence type provided is missing in the assembly evidence list. - - -or- - - An isolated storage location cannot be initialized. - - -or- - - contains the enumeration value , but the application identity of the caller cannot be determined, because the for the current application domain returned . - - -or- - - contains the value , but the permissions for the application domain cannot be determined. - - -or- - + The evidence type provided is missing in the assembly evidence list. + + -or- + + An isolated storage location cannot be initialized. + + -or- + + contains the enumeration value , but the application identity of the caller cannot be determined, because the for the current application domain returned . + + -or- + + contains the value , but the permissions for the application domain cannot be determined. + + -or- + contains , but the permissions for the calling assembly cannot be determined. @@ -2200,11 +2200,11 @@ System.IO.IsolatedStorage.IsolatedStorageFile - - - - - + + + + + A bitwise combination of the enumeration values. @@ -2215,38 +2215,38 @@ Obtains isolated storage corresponding to the given application domain and the assembly evidence objects and types. An object that represents the parameters. - [!NOTE] -> If the `scope` parameter is and the application domain in which the assembly is installed does not have , the method will return an object without a quota. Later attempts to create an object using the object that does not have a quota will fail with an . - - - -## Examples - The following code example obtains storage based on publisher evidence. - +> If the `scope` parameter is and the application domain in which the assembly is installed does not have , the method will return an object without a quota. Later attempts to create an object using the object that does not have a quota will fail with an . + + + +## Examples + The following code example obtains storage based on publisher evidence. + :::code language="csharp" source="~/snippets/csharp/System.IO.IsolatedStorage/IsolatedStorageFile/GetStore/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.IsolatedStorage.GetStore/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.IsolatedStorage.GetStore/VB/source.vb" id="Snippet1"::: + ]]> Sufficient isolated storage permissions have not been granted. The or identity has not been passed in. The is invalid. - An isolated storage location cannot be initialized. - - -or- - - contains the enumeration value , but the application identity of the caller cannot be determined, because the for the current application domain returned . - - -or- - - contains the value , but the permissions for the application domain cannot be determined. - - -or- - + An isolated storage location cannot be initialized. + + -or- + + contains the enumeration value , but the application identity of the caller cannot be determined, because the for the current application domain returned . + + -or- + + contains the value , but the permissions for the application domain cannot be determined. + + -or- + contains the value , but the permissions for the calling assembly cannot be determined. @@ -2299,30 +2299,30 @@ Obtains user-scoped isolated storage corresponding to the calling code's application identity. An object corresponding to the isolated storage scope based on the calling code's assembly identity. - exception, because the application identity of the caller cannot be determined. - - is functionally equivalent to the following code: - + exception, because the application identity of the caller cannot be determined. + + is functionally equivalent to the following code: + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/CPP/remarks.cpp" id="Snippet21"::: :::code language="csharp" source="~/snippets/csharp/System.IO.IsolatedStorage/IsolatedStorageFile/Close/remarks.cs" id="Snippet21"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/VB/remarks.vb" id="Snippet21"::: - - In this code, the `applicationIdentity` parameter for `GetStore(IsolatedStorageScope scope, Object applicationIdentity)` is `null`. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/VB/remarks.vb" id="Snippet21"::: + + In this code, the `applicationIdentity` parameter for `GetStore(IsolatedStorageScope scope, Object applicationIdentity)` is `null`. + ]]> Sufficient isolated storage permissions have not been granted. - An isolated storage location cannot be initialized. - - -or- - - The application identity of the caller cannot be determined, because the property returned . - - -or- - + An isolated storage location cannot be initialized. + + -or- + + The application identity of the caller cannot be determined, because the property returned . + + -or- + The permissions for the application domain cannot be determined. Isolated Storage @@ -2372,27 +2372,27 @@ Obtains user-scoped isolated storage corresponding to the calling code's assembly identity. An object corresponding to the isolated storage scope based on the calling code's assembly identity. - is functionally equivalent to the following code: - + is functionally equivalent to the following code: + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/CPP/remarks.cpp" id="Snippet22"::: :::code language="csharp" source="~/snippets/csharp/System.IO.IsolatedStorage/IsolatedStorageFile/Close/remarks.cs" id="Snippet22"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/VB/remarks.vb" id="Snippet22"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/VB/remarks.vb" id="Snippet22"::: + > [!NOTE] -> Different assemblies running within the same application domain always have distinct isolated stores. - +> Different assemblies running within the same application domain always have distinct isolated stores. + ]]> Sufficient isolated storage permissions have not been granted. - An isolated storage location cannot be initialized. - - -or- - + An isolated storage location cannot be initialized. + + -or- + The permissions for the calling assembly cannot be determined. Isolated Storage @@ -2442,46 +2442,46 @@ Obtains user-scoped isolated storage corresponding to the application domain identity and assembly identity. An object corresponding to the , based on a combination of the application domain identity and the assembly identity. - is functionally equivalent to the following code: - + is functionally equivalent to the following code: + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/CPP/remarks.cpp" id="Snippet23"::: :::code language="csharp" source="~/snippets/csharp/System.IO.IsolatedStorage/IsolatedStorageFile/Close/remarks.cs" id="Snippet23"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/VB/remarks.vb" id="Snippet23"::: - - Different assemblies running within the same application domain always have distinct isolated stores. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/VB/remarks.vb" id="Snippet23"::: + + Different assemblies running within the same application domain always have distinct isolated stores. + > [!NOTE] -> will return an object without a quota if the application domain in which the assembly is installed does not have . Later attempts to create an object using the object that does not have a quota will fail with an . - - - -## Examples - The following code example demonstrates the method. For the complete context of this example, see the overview. - +> will return an object without a quota if the application domain in which the assembly is installed does not have . Later attempts to create an object using the object that does not have a quota will fail with an . + + + +## Examples + The following code example demonstrates the method. For the complete context of this example, see the overview. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/CPP/source.cpp" id="Snippet10"::: :::code language="csharp" source="~/snippets/csharp/System.IO.IsolatedStorage/IsolatedStorageFile/Close/source.cs" id="Snippet10"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/VB/source.vb" id="Snippet10"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/VB/source.vb" id="Snippet10"::: + ]]> Sufficient isolated storage permissions have not been granted. - The store failed to open. - - -or- - - The assembly specified has insufficient permissions to create isolated stores. - - -or- - - An isolated storage location cannot be initialized. - - -or- - + The store failed to open. + + -or- + + The assembly specified has insufficient permissions to create isolated stores. + + -or- + + An isolated storage location cannot be initialized. + + -or- + The permissions for the application domain cannot be determined. Isolated Storage @@ -2533,11 +2533,11 @@ Obtains a user-scoped isolated store for use by applications in a virtual host domain. The isolated storage file that corresponds to the isolated storage scope based on the calling code's application identity. - Isolated Storage @@ -2586,7 +2586,7 @@ System.Boolean - + The requested size, in bytes. @@ -2594,19 +2594,19 @@ if the new quota is accepted; otherwise, . - method enables an application to explicitly request a larger quota size in bytes. The new quota size must not be smaller than the current quota size, because only quota increases are allowed. - - Whenever the method is called, isolated storage calls the method. - - You can implement policy decisions by creating a custom object that overrides the method so that the object can perform policy decisions based on a object. - - If there is no custom object, the quota increase request is denied, because the default implementation for returns `false`. - - Currently, none of the hosts in the .NET Framework provide this customization, so always returns `false`. - + method enables an application to explicitly request a larger quota size in bytes. The new quota size must not be smaller than the current quota size, because only quota increases are allowed. + + Whenever the method is called, isolated storage calls the method. + + You can implement policy decisions by creating a custom object that overrides the method so that the object can perform policy decisions based on a object. + + If there is no custom object, the quota increase request is denied, because the default implementation for returns `false`. + + Currently, none of the hosts in the .NET Framework provide this customization, so always returns `false`. + ]]> @@ -2616,10 +2616,10 @@ The isolated store has been closed. The current scope is not for an application user. The isolated store has been disposed. - The isolated store has been removed. - - -or- - + The isolated store has been removed. + + -or- + Isolated storage is disabled. Isolated Storage @@ -2667,11 +2667,11 @@ in all cases. - Isolated Storage @@ -2733,22 +2733,22 @@ Gets a value representing the maximum amount of space available for isolated storage within the limits established by the quota. The limit of isolated storage space in bytes. - property. - - - -## Examples - The following code example demonstrates the property. For the complete context of this example, see the overview. - + property. + + + +## Examples + The following code example demonstrates the property. For the complete context of this example, see the overview. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/CPP/source.cpp" id="Snippet5"::: :::code language="csharp" source="~/snippets/csharp/System.IO.IsolatedStorage/IsolatedStorageFile/Close/source.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/VB/source.vb" id="Snippet5"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/VB/source.vb" id="Snippet5"::: + ]]> The property is unavailable. cannot be determined without evidence from the assembly's creation. The evidence could not be determined when the object was created. @@ -2808,11 +2808,11 @@ The path to the new location for . This cannot be the path to an existing directory. Moves a specified directory and its contents to a new location. - @@ -2823,18 +2823,18 @@ The isolated store has been disposed. does not exist. - The isolated store has been removed. - - -or- - - Isolated storage is disabled. - - -or- - - already exists. - - -or- - + The isolated store has been removed. + + -or- + + Isolated storage is disabled. + + -or- + + already exists. + + -or- + and refer to the same directory. Isolated Storage @@ -2891,11 +2891,11 @@ The path to the new location for the file. If a file name is included, the moved file will have that name. Moves a specified file to a new location, and optionally lets you specify a new file name. - @@ -2906,10 +2906,10 @@ The isolated store has been disposed. was not found. - The isolated store has been removed. - - -or- - + The isolated store has been removed. + + -or- + Isolated storage is disabled. Isolated Storage @@ -2973,17 +2973,17 @@ Opens a file in the specified mode. A file that is opened in the specified mode, with read/write access, and is unshared. - constructor. - + constructor. + ]]> - The isolated store has been removed. - - -or- - + The isolated store has been removed. + + -or- + Isolated storage is disabled. is malformed. @@ -3046,17 +3046,17 @@ Opens a file in the specified mode with the specified read/write access. A file that is opened in the specified mode and access, and is unshared. - constructor. - + constructor. + ]]> - The isolated store has been removed. - - -or- - + The isolated store has been removed. + + -or- + Isolated storage is disabled. is malformed. @@ -3121,17 +3121,17 @@ Opens a file in the specified mode, with the specified read/write access and sharing permission. A file that is opened in the specified mode and access, and with the specified sharing options. - constructor. - + constructor. + ]]> - The isolated store has been removed. - - -or- - + The isolated store has been removed. + + -or- + Isolated storage is disabled. is malformed. @@ -3193,10 +3193,10 @@ Gets a value that represents the maximum amount of space available for isolated storage. The limit of isolated storage space, in bytes. To be added. - The isolated store has been removed. - - -or- - + The isolated store has been removed. + + -or- + Isolated storage is disabled. The isolated store has been disposed. Isolated Storage @@ -3256,24 +3256,24 @@ Removes the isolated storage scope and all its contents. - [!CAUTION] -> This method irrevocably removes the entire scope and all contained directories and files. - - If any of the directories or files in the store are in use, the removal attempt for the store fails and the store is marked for removal. Any subsequent attempts to modify the store throw an . - - - -## Examples - The following code example uses the method to delete the isolated storage file after its contents have been emptied. The [How to: Delete Stores in Isolated Storage](/dotnet/standard/io/how-to-delete-stores-in-isolated-storage) example also demonstrates the use of the method. - +> This method irrevocably removes the entire scope and all contained directories and files. + + If any of the directories or files in the store are in use, the removal attempt for the store fails and the store is marked for removal. Any subsequent attempts to modify the store throw an . + + + +## Examples + The following code example uses the method to delete the isolated storage file after its contents have been emptied. The [How to: Delete Stores in Isolated Storage](/dotnet/standard/io/how-to-delete-stores-in-isolated-storage) example also demonstrates the use of the method. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/CPP/source.cpp" id="Snippet16"::: :::code language="csharp" source="~/snippets/csharp/System.IO.IsolatedStorage/IsolatedStorageFile/Close/source.cs" id="Snippet16"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/VB/source.vb" id="Snippet16"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/VB/source.vb" id="Snippet16"::: + ]]> The isolated store cannot be deleted. @@ -3322,21 +3322,21 @@ System.Void - + A bitwise combination of the values. Removes the specified isolated storage scope for all identities. - [!CAUTION] -> This method irrevocably removes the entire scope and all contained directories and files. - - If any of the directories or files in the store are in use, the removal attempt for the store fails and the store is marked for removal. Any subsequent attempts to modify the store throw an . - +> This method irrevocably removes the entire scope and all contained directories and files. + + If any of the directories or files in the store are in use, the removal attempt for the store fails and the store is marked for removal. Any subsequent attempts to modify the store throw an . + ]]> The isolated store cannot be removed. diff --git a/xml/System.IO.IsolatedStorage/IsolatedStorageFileStream.xml b/xml/System.IO.IsolatedStorage/IsolatedStorageFileStream.xml index 6f33027abac..5944c1e8454 100644 --- a/xml/System.IO.IsolatedStorage/IsolatedStorageFileStream.xml +++ b/xml/System.IO.IsolatedStorage/IsolatedStorageFileStream.xml @@ -63,27 +63,27 @@ Exposes a file within isolated storage. - , you can use an instance of in most situations where a might otherwise be used, such as to construct a or . - - 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 use an instance of in most situations where a might otherwise be used, such as to construct a or . + + 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] -> Isolated storage is not available for Windows 8.x Store apps. Instead, use the application data classes in the `Windows.Storage` namespaces included in the Windows Runtime API to store local data and files. For more information, see [Application data](https://go.microsoft.com/fwlink/?LinkId=229175) in the Windows Dev Center. - - - -## Examples - The following console application demonstrates how you can use and to write data to an Isolated Storage file. The user is requested to log in. If the user is a new user, a News URL and a Sports URL are recorded as personal preferences in Isolated Storage. If the user is a returning user, the user's current preferences are displayed. The code examples used throughout this namespace are presented in the context of this sample application. You can use the [Storeadm.exe (Isolated Storage Tool)](/dotnet/framework/tools/storeadm-exe-isolated-storage-tool) utility to list and remove the Isolated Storage files that are created with this console application. - +> Isolated storage is not available for Windows 8.x Store apps. Instead, use the application data classes in the `Windows.Storage` namespaces included in the Windows Runtime API to store local data and files. For more information, see [Application data](https://go.microsoft.com/fwlink/?LinkId=229175) in the Windows Dev Center. + + + +## Examples + The following console application demonstrates how you can use and to write data to an Isolated Storage file. The user is requested to log in. If the user is a new user, a News URL and a Sports URL are recorded as personal preferences in Isolated Storage. If the user is a returning user, the user's current preferences are displayed. The code examples used throughout this namespace are presented in the context of this sample application. You can use the [Storeadm.exe (Isolated Storage Tool)](/dotnet/framework/tools/storeadm-exe-isolated-storage-tool) utility to list and remove the Isolated Storage files that are created with this console application. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.IO.IsolatedStorage/IsolatedStorageFile/Close/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/VB/source.vb" id="Snippet1"::: + ]]> @@ -130,24 +130,24 @@ 9.0.0.0 - - + + The relative path of the file within isolated storage. One of the values. Initializes a new instance of an object giving access to the file designated by in the specified . - object. To specify a different isolated storage scope, or to allow the store to remain open (so multiple objects can be opened from it), use the form of the constructor that accepts an object. - - The `mode` parameter indicates whether a new file should be created, an existing one used, and so on. - + object. To specify a different isolated storage scope, or to allow the store to remain open (so multiple objects can be opened from it), use the form of the constructor that accepts an object. + + The `mode` parameter indicates whether a new file should be created, an existing one used, and so on. + > [!CAUTION] -> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable and can cause an exception to be thrown. - +> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable and can cause an exception to be thrown. + ]]> The is badly formed. @@ -188,9 +188,9 @@ 9.0.0.0 - - - + + + The relative path of the file within isolated storage. @@ -198,16 +198,16 @@ A bitwise combination of the values. Initializes a new instance of the class giving access to the file designated by , in the specified , with the kind of requested. - object. To specify a different isolated storage scope, or to allow the store to remain open (so multiple objects can be opened from it), use the form of the constructor that accepts an object. - - The `mode` parameter indicates whether a new file should be created or an existing one used. The `access` parameter includes read-only, read/write, and write-only. - + object. To specify a different isolated storage scope, or to allow the store to remain open (so multiple objects can be opened from it), use the form of the constructor that accepts an object. + + The `mode` parameter indicates whether a new file should be created or an existing one used. The `access` parameter includes read-only, read/write, and write-only. + > [!CAUTION] -> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and can cause an exception to be thrown. - +> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and can cause an exception to be thrown. + ]]> The is badly formed. @@ -266,23 +266,23 @@ The in which to open the . Initializes a new instance of the class giving access to the file designated by , in the specified , and in the context of the specified by . - [!CAUTION] -> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and can cause an exception to be thrown. - - - -## Examples - The following code example demonstrates the use of this constructor. For the complete context of this example, see the overview. - +> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and can cause an exception to be thrown. + + + +## Examples + The following code example demonstrates the use of this constructor. For the complete context of this example, see the overview. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/CPP/source.cpp" id="Snippet11"::: :::code language="csharp" source="~/snippets/csharp/System.IO.IsolatedStorage/IsolatedStorageFile/Close/source.cs" id="Snippet11"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/VB/source.vb" id="Snippet11"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/VB/source.vb" id="Snippet11"::: + ]]> The is badly formed. @@ -324,10 +324,10 @@ 9.0.0.0 - - - - + + + + The relative path of the file within isolated storage. @@ -336,23 +336,23 @@ A bitwise combination of the values. Initializes a new instance of the class giving access to the file designated by , in the specified , with the specified file , using the file sharing mode specified by . - object. To specify a different isolated storage scope, or to allow the store to remain open (so multiple objects can be opened from it), use the form of the constructor that accepts an object. - + object. To specify a different isolated storage scope, or to allow the store to remain open (so multiple objects can be opened from it), use the form of the constructor that accepts an object. + > [!CAUTION] -> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable and can cause an exception to be thrown. - - - -## Examples - The following code example demonstrates the use of this constructor. For the complete context of this example, see the overview. - +> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable and can cause an exception to be thrown. + + + +## Examples + The following code example demonstrates the use of this constructor. For the complete context of this example, see the overview. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/CPP/source.cpp" id="Snippet15"::: :::code language="csharp" source="~/snippets/csharp/System.IO.IsolatedStorage/IsolatedStorageFile/Close/source.cs" id="Snippet15"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/VB/source.vb" id="Snippet15"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/VB/source.vb" id="Snippet15"::: + ]]> The is badly formed. @@ -413,23 +413,23 @@ The in which to open the . Initializes a new instance of the class giving access to the file designated by in the specified , with the specified file , and in the context of the specified by . - [!CAUTION] -> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and can cause an exception to be thrown. - - - -## Examples - The following code example demonstrates the use of this constructor. For the complete context of this example, see the overview. - +> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and can cause an exception to be thrown. + + + +## Examples + The following code example demonstrates the use of this constructor. For the complete context of this example, see the overview. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/CPP/source.cpp" id="Snippet10"::: :::code language="csharp" source="~/snippets/csharp/System.IO.IsolatedStorage/IsolatedStorageFile/Close/source.cs" id="Snippet10"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/VB/source.vb" id="Snippet10"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/VB/source.vb" id="Snippet10"::: + ]]> The is badly formed. @@ -472,11 +472,11 @@ 9.0.0.0 - - - - - + + + + + The relative path of the file within isolated storage. @@ -486,16 +486,16 @@ The buffer size. Initializes a new instance of the class giving access to the file designated by , in the specified , with the specified file , using the file sharing mode specified by , with the specified. - object. To specify a different isolated storage scope, or to allow the store to remain open (so multiple objects can be opened from it), use the form of the constructor that accepts an object. - - The `mode` parameter indicates whether a new file should be created or an existing one used. The `access` parameter includes read-only, read/write, and write-only. - + object. To specify a different isolated storage scope, or to allow the store to remain open (so multiple objects can be opened from it), use the form of the constructor that accepts an object. + + The `mode` parameter indicates whether a new file should be created or an existing one used. The `access` parameter includes read-only, read/write, and write-only. + > [!CAUTION] -> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and can cause an exception to be thrown. - +> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and can cause an exception to be thrown. + ]]> The is badly formed. @@ -558,23 +558,23 @@ The in which to open the . Initializes a new instance of the class giving access to the file designated by , in the specified , with the specified file , using the file sharing mode specified by , and in the context of the specified by . - [!CAUTION] -> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and can cause an exception to be thrown. - - - -## Examples - The following code example demonstrates the use of this constructor. For the complete context of this example, see the overview. - +> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and can cause an exception to be thrown. + + + +## Examples + The following code example demonstrates the use of this constructor. For the complete context of this example, see the overview. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/CPP/source.cpp" id="Snippet11"::: :::code language="csharp" source="~/snippets/csharp/System.IO.IsolatedStorage/IsolatedStorageFile/Close/source.cs" id="Snippet11"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/VB/source.vb" id="Snippet11"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/VB/source.vb" id="Snippet11"::: + ]]> The is badly formed. @@ -623,12 +623,12 @@ - - - - - - + + + + + + [System.Runtime.CompilerServices.Nullable(2)] @@ -646,23 +646,23 @@ The in which to open the . Initializes a new instance of the class giving access to the file designated by , in the specified , with the specified file , using the file sharing mode specified by , with the specified, and in the context of the specified by . - [!CAUTION] -> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and can cause an exception to be thrown. - - - -## Examples - The following code example demonstrates the use of this constructor. For the complete context of this example, see the overview. - +> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and can cause an exception to be thrown. + + + +## Examples + The following code example demonstrates the use of this constructor. For the complete context of this example, see the overview. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/CPP/source.cpp" id="Snippet12"::: :::code language="csharp" source="~/snippets/csharp/System.IO.IsolatedStorage/IsolatedStorageFile/Close/source.cs" id="Snippet12"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/VB/source.vb" id="Snippet12"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/VB/source.vb" id="Snippet12"::: + ]]> The is badly formed. @@ -712,11 +712,11 @@ System.IAsyncResult - + - - - + + + [System.Runtime.CompilerServices.Nullable(2)] @@ -724,7 +724,7 @@ - + [System.Runtime.CompilerServices.Nullable(2)] @@ -743,13 +743,13 @@ Begins an asynchronous read. An object that represents the asynchronous read, which is possibly still pending. This must be passed to this stream's method to determine how many bytes were read. This can be done either by the same code that called or in a callback passed to . - with this to find out how many bytes were read. - + with this to find out how many bytes were read. + ]]> An asynchronous read was attempted past the end of the file. @@ -801,11 +801,11 @@ System.IAsyncResult - + - - - + + + [System.Runtime.CompilerServices.Nullable(2)] @@ -813,7 +813,7 @@ - + [System.Runtime.CompilerServices.Nullable(2)] @@ -832,15 +832,15 @@ Begins an asynchronous write. An that represents the asynchronous write, which is possibly still pending. This must be passed to this stream's method to ensure that the write is complete, then frees resources appropriately. This can be done either by the same code that called or in a callback passed to . - object is writable, writing at the end of the stream expands the stream. - - The current position in the stream is updated when you issue the asynchronous read or write, not when the I/O operation completes. - - You must call with the object that this method returns to find out how many bytes were written. - + object is writable, writing at the end of the stream expands the stream. + + The current position in the stream is updated when you issue the asynchronous read or write, not when the I/O operation completes. + + You must call with the object that this method returns to find out how many bytes were written. + ]]> An asynchronous write was attempted past the end of the file. @@ -886,20 +886,20 @@ if an object can be read; otherwise, . - object can be read. - - - -## Examples - The following code example demonstrates how you could use the property, as a check to see whether a stream can be read before calling the or methods. For the complete context of this example, see the overview. - + object can be read. + + + +## Examples + The following code example demonstrates how you could use the property, as a check to see whether a stream can be read before calling the or methods. For the complete context of this example, see the overview. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/CPP/source.cpp" id="Snippet11"::: :::code language="csharp" source="~/snippets/csharp/System.IO.IsolatedStorage/IsolatedStorageFile/Close/source.cs" id="Snippet11"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/VB/source.vb" id="Snippet11"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/VB/source.vb" id="Snippet11"::: + ]]> @@ -944,11 +944,11 @@ if an object supports seek operations; otherwise, . - object supports seek operations. - + object supports seek operations. + ]]> @@ -993,20 +993,20 @@ if an object can be written; otherwise, . - object can be written. - - - -## Examples - The following code example demonstrates how you could use the property, as a check to see whether a stream can be read before calling the or methods. For the complete context of this example, see the overview. - + object can be written. + + + +## Examples + The following code example demonstrates how you could use the property, as a check to see whether a stream can be read before calling the or methods. For the complete context of this example, see the overview. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/CPP/source.cpp" id="Snippet13"::: :::code language="csharp" source="~/snippets/csharp/System.IO.IsolatedStorage/IsolatedStorageFile/Close/source.cs" id="Snippet13"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/VB/source.vb" id="Snippet13"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/VB/source.vb" id="Snippet13"::: + ]]> @@ -1137,19 +1137,19 @@ Dim source As New IsolatedStorageFileStream(UserName,FileMode.Open,isoFile) to release both managed and unmanaged resources; to release only unmanaged resources. Releases the unmanaged resources used by the and optionally releases the managed resources. - method and the method, if it has been overridden. invokes the protected method with the `disposing` parameter set to true. `Finalize` invokes with `disposing` set to 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. - + method and the method, if it has been overridden. invokes the protected method with the `disposing` parameter set to true. `Finalize` invokes with `disposing` set to 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. + ]]> - can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). - + can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). + For more information about and , see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). @@ -1224,18 +1224,18 @@ Dim source As New IsolatedStorageFileStream(UserName,FileMode.Open,isoFile) System.Int32 - + The pending asynchronous request. Ends a pending asynchronous read request. The number of bytes read from the stream, between zero and the number of requested bytes. Streams will only return zero at the end of the stream. Otherwise, they will block until at least one byte is available. - must be called exactly once on every object from , and calling is the only way to know how many bytes were read from the . will block until the I/O operation has completed. - + must be called exactly once on every object from , and calling is the only way to know how many bytes were read from the . will block until the I/O operation has completed. + ]]> The is . @@ -1276,19 +1276,19 @@ Dim source As New IsolatedStorageFileStream(UserName,FileMode.Open,isoFile) System.Void - + The pending asynchronous I/O request to end. Ends an asynchronous write. - must be called exactly once on every from . - - will block until the I/O operation has completed. - + must be called exactly once on every from . + + will block until the I/O operation has completed. + ]]> The parameter is . @@ -1343,13 +1343,13 @@ Dim source As New IsolatedStorageFileStream(UserName,FileMode.Open,isoFile) Clears buffers for this stream and causes any buffered data to be written to the file. - performs two functions. First, any data previously written to the buffer is copied to the file and the buffer is cleared. Second, if is `true` and data was previously copied from the file to the buffer for reading, the current position within the file is decremented by the number of unread bytes in the buffer. The buffer is then cleared. - - Use the method overload when you want to ensure that all buffered data in intermediate file buffers is written to disk. - + performs two functions. First, any data previously written to the buffer is copied to the file and the buffer is cleared. Second, if is `true` and data was previously copied from the file to the buffer for reading, the current position within the file is decremented by the number of unread bytes in the buffer. The buffer is then cleared. + + Use the method overload when you want to ensure that all buffered data in intermediate file buffers is written to disk. + ]]> @@ -1388,18 +1388,18 @@ Dim source As New IsolatedStorageFileStream(UserName,FileMode.Open,isoFile) System.Void - + to flush all intermediate file buffers; otherwise, . Clears buffers for this stream and causes any buffered data to be written to the file, and also clears all intermediate file buffers. - @@ -1498,20 +1498,20 @@ Dim source As New IsolatedStorageFileStream(UserName,FileMode.Open,isoFile) Gets the file handle for the file that the current object encapsulates. Accessing this property is not permitted on an object, and throws an . The file handle for the file that the current object encapsulates. - . - - - -## Examples - The following code example demonstrates the property. - + . + + + +## Examples + The following code example demonstrates the property. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/CPP/source.cpp" id="Snippet4"::: :::code language="csharp" source="~/snippets/csharp/System.IO.IsolatedStorage/IsolatedStorageFile/Close/source.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/VB/source.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/VB/source.vb" id="Snippet4"::: + ]]> The property always generates this exception. @@ -1556,20 +1556,20 @@ Dim source As New IsolatedStorageFileStream(UserName,FileMode.Open,isoFile) if the object supports asynchronous access; otherwise, . - objects cannot be created, unlike . However, the , , , and methods are supported on synchronous instances, with some performance penalties. - - - -## Examples - The following code example demonstrates how you can use the property to verify that an is synchronous. For the complete context of this example, see the overview. - + objects cannot be created, unlike . However, the , , , and methods are supported on synchronous instances, with some performance penalties. + + + +## Examples + The following code example demonstrates how you can use the property to verify that an is synchronous. For the complete context of this example, see the overview. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/CPP/source.cpp" id="Snippet7"::: :::code language="csharp" source="~/snippets/csharp/System.IO.IsolatedStorage/IsolatedStorageFile/Close/source.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/VB/source.vb" id="Snippet7"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/VB/source.vb" id="Snippet7"::: + ]]> @@ -1614,20 +1614,20 @@ Dim source As New IsolatedStorageFileStream(UserName,FileMode.Open,isoFile) Gets the length of the object. The length of the object in bytes. - represents the number of bytes currently in the file. It is not affected by isolated storage quota. - - - -## Examples - The following code example demonstrates the property. - + represents the number of bytes currently in the file. It is not affected by isolated storage quota. + + + +## Examples + The following code example demonstrates the property. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/CPP/source.cpp" id="Snippet14"::: :::code language="csharp" source="~/snippets/csharp/System.IO.IsolatedStorage/IsolatedStorageFile/Close/source.cs" id="Snippet14"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/VB/source.vb" id="Snippet14"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/VB/source.vb" id="Snippet14"::: + ]]> @@ -1678,11 +1678,11 @@ Dim source As New IsolatedStorageFileStream(UserName,FileMode.Open,isoFile) The number of bytes to lock. Prevents other processes from reading from or writing to the stream. - @@ -1730,20 +1730,20 @@ Dim source As New IsolatedStorageFileStream(UserName,FileMode.Open,isoFile) Gets or sets the current position of the current object. The current position of this object. - property is `true`. - - - -## Examples - The following code example uses the property to write data to a file. - + property is `true`. + + + +## Examples + The following code example uses the property to write data to a file. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/CPP/source.cpp" id="Snippet14"::: :::code language="csharp" source="~/snippets/csharp/System.IO.IsolatedStorage/IsolatedStorageFile/Close/source.cs" id="Snippet14"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/VB/source.vb" id="Snippet14"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/VB/source.vb" id="Snippet14"::: + ]]> The position cannot be set to a negative number. @@ -1840,11 +1840,11 @@ Dim source As New IsolatedStorageFileStream(UserName,FileMode.Open,isoFile) Copies bytes from the current buffered object to a byte array. The total number of bytes read into the . This can be less than the number of bytes requested if that many bytes are not currently available, or zero if the end of the stream is reached. - class, or an array of one of the following types: , , , , , , , , , , or . +The `buffer` parameter can be an instance of the class, or an array of one of the following types: , , , , , , , , , , or . If the read operation is successful, the current position of the stream is advanced by the number of bytes read. If an exception occurs, the current position of the stream is unchanged. @@ -1942,11 +1942,11 @@ The method wi Asynchronously copies bytes from the current buffered object to a byte array. A task that represents the asynchronous read operation. It wraps the total number of bytes read into the . This can be less than the number of bytes requested if that many bytes are not currently available, or zero if the end of the stream is reached. - class, or an array of one of the following types: , , , , , , , , , , or . +The `buffer` parameter can be an instance of the class, or an array of one of the following types: , , , , , , , , , , or . If the read operation is successful, the current position of the stream is advanced by the number of bytes read. If an exception occurs, the current position of the stream is unchanged. @@ -2001,15 +2001,15 @@ This method stores in the task it returns all non-usage exceptions that the meth Reads a single byte from the object in isolated storage. The 8-bit unsigned integer value read from the isolated storage file. - method can be used to read data from an object. For the complete context of this example, see the overview. - + method can be used to read data from an object. For the complete context of this example, see the overview. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/CPP/source.cpp" id="Snippet14"::: :::code language="csharp" source="~/snippets/csharp/System.IO.IsolatedStorage/IsolatedStorageFile/Close/source.cs" id="Snippet14"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/VB/source.vb" id="Snippet14"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/VB/source.vb" id="Snippet14"::: + ]]> @@ -2057,11 +2057,11 @@ This method stores in the task it returns all non-usage exceptions that the meth Gets a object that represents the operating system file handle for the file that the current object encapsulates. A object that represents the operating system file handle for the file that the current object encapsulates. - property is not supported and always generates an exception. - + property is not supported and always generates an exception. + ]]> The property always generates this exception. @@ -2118,11 +2118,11 @@ This method stores in the task it returns all non-usage exceptions that the meth Sets the current position of this object to the specified value. The new position in the object. - objects support positioning beyond the length of the stream, others will throw an exception in this case. - + objects support positioning beyond the length of the stream, others will throw an exception in this case. + ]]> The must be one of the values. @@ -2176,11 +2176,11 @@ This method stores in the task it returns all non-usage exceptions that the meth The new length of the object. Sets the length of this object to the specified . - object, the stream is truncated. If the specified `value` is larger than the current length of the stream, the stream is expanded. If the stream is expanded, the contents of the stream between the old and the new length are undefined. In order to use this method, an object must support both writing and seeking. - + object, the stream is truncated. If the specified `value` is larger than the current length of the stream, the stream is expanded. If the stream is expanded, the contents of the stream between the old and the new length are undefined. In order to use this method, an object must support both writing and seeking. + ]]> @@ -2332,11 +2332,11 @@ This method stores in the task it returns all non-usage exceptions that the meth The maximum number of bytes to write. Writes a block of bytes to the isolated storage file stream object using data read from a buffer consisting of a byte array. - object is advanced by the number of bytes written. If an exception occurs, the current position of the object is unchanged. +If the write operation is successful, the current position of the object is advanced by the number of bytes written. If an exception occurs, the current position of the object is unchanged. ]]> @@ -2429,11 +2429,11 @@ If the write operation is successful, the current position of the Asynchronously writes a block of bytes to the isolated storage file stream object using data read from a buffer consisting of a byte array. A task that represents the asynchronous write operation. - object is advanced by the number of bytes written. If an exception occurs, the current position of the object is unchanged. +If the write operation is successful, the current position of the object is advanced by the number of bytes written. If an exception occurs, the current position of the object is unchanged. 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 . @@ -2490,15 +2490,15 @@ This method stores in the task it returns all non-usage exceptions that the meth The byte value to write to the isolated storage file. Writes a single byte to the object. - method can be used to read data from an object. For the complete context of this example, see the overview. - + method can be used to read data from an object. For the complete context of this example, see the overview. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/CPP/source.cpp" id="Snippet14"::: :::code language="csharp" source="~/snippets/csharp/System.IO.IsolatedStorage/IsolatedStorageFile/Close/source.cs" id="Snippet14"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/VB/source.vb" id="Snippet14"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.IsolatedStorage.IsolatedStorage/VB/source.vb" id="Snippet14"::: + ]]> The write attempt exceeds the quota for the object. diff --git a/xml/System.IO.MemoryMappedFiles/MemoryMappedFile.xml b/xml/System.IO.MemoryMappedFiles/MemoryMappedFile.xml index 28e6e005c44..755dc6eb990 100644 --- a/xml/System.IO.MemoryMappedFiles/MemoryMappedFile.xml +++ b/xml/System.IO.MemoryMappedFiles/MemoryMappedFile.xml @@ -55,27 +55,27 @@ Represents a memory-mapped file. - methods create a memory-mapped file from a specified path or a of an existing file on disk. Changes are automatically propagated to disk when the file is unmapped. - - The methods create a memory-mapped file that is not mapped to an existing file on disk; and are suitable for creating shared memory for interprocess communication (IPC). - - A memory-mapped file can be associated with an optional name that allows the memory-mapped file to be shared with other processes. - - You can create multiple views of the memory-mapped file, including views of parts of the file. You can map the same part of a file to more than one address to create concurrent memory. For two views to remain concurrent, they have to be created from the same memory-mapped file. Creating two file mappings of the same file with two views does not provide concurrency. - - - -## Examples - The following example creates a memory-mapped view of a part of an extremely large file and manipulates a portion of it. - + methods create a memory-mapped file from a specified path or a of an existing file on disk. Changes are automatically propagated to disk when the file is unmapped. + + The methods create a memory-mapped file that is not mapped to an existing file on disk; and are suitable for creating shared memory for interprocess communication (IPC). + + A memory-mapped file can be associated with an optional name that allows the memory-mapped file to be shared with other processes. + + You can create multiple views of the memory-mapped file, including views of parts of the file. You can map the same part of a file to more than one address to create concurrent memory. For two views to remain concurrent, they have to be created from the same memory-mapped file. Creating two file mappings of the same file with two views does not provide concurrency. + + + +## Examples + The following example creates a memory-mapped view of a part of an extremely large file and manipulates a portion of it. + :::code language="csharp" source="~/snippets/csharp/System.IO.MemoryMappedFiles/MemoryMappedFile/Overview/program.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/memorymappedfiles.memorymappedfile.createfromfile/vb/program.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/memorymappedfiles.memorymappedfile.createfromfile/vb/program.vb" id="Snippet1"::: + ]]> Memory-Mapped Files @@ -132,21 +132,21 @@ Creates a memory-mapped file from a file on disk. A memory-mapped file. - method to create a memory-mapped file, and then creates a memory-mapped view to a portion of an extremely large file. - + method to create a memory-mapped file, and then creates a memory-mapped view to a portion of an extremely large file. + :::code language="csharp" source="~/snippets/csharp/System.IO.MemoryMappedFiles/MemoryMappedFile/Overview/program.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/memorymappedfiles.memorymappedfile.createfromfile/vb/program.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/memorymappedfiles.memorymappedfile.createfromfile/vb/program.vb" id="Snippet1"::: + ]]> - is an empty string, contains only white space, or has one or more invalid characters, as defined by the method. - - -or- - + is an empty string, contains only white space, or has one or more invalid characters, as defined by the method. + + -or- + refers to an invalid device. is . @@ -200,34 +200,34 @@ Creates a memory-mapped file that has the specified access mode from a file on disk. A memory-mapped file that has the specified access mode. - enumeration value to create the memory-mapped file from the source file on disk. - + enumeration value to create the memory-mapped file from the source file on disk. + ]]> - is an empty string, contains only white space, or has one or more invalid characters, as defined by the method. - - -or- - - refers to an invalid device. - - -or- - + is an empty string, contains only white space, or has one or more invalid characters, as defined by the method. + + -or- + + refers to an invalid device. + + -or- + is . is . - is , , or . - - -or- - - is and the file on disk does not exist. - - -or- - + is , , or . + + -or- + + is and the file on disk does not exist. + + -or- + An I/O error occurred. exceeds the maximum length defined by the operating system. @@ -288,38 +288,38 @@ Creates a memory-mapped file that has the specified access mode and name from a file on disk. A memory-mapped file that has the specified name and access mode. - enumeration value to create the memory-mapped file from the source file on disk. - + enumeration value to create the memory-mapped file from the source file on disk. + ]]> - is an empty string, contains only white space, or has one or more invalid characters, as defined by the method. - - -or- - - refers to an invalid device. - - -or- - - is an empty string. - - -or- - + is an empty string, contains only white space, or has one or more invalid characters, as defined by the method. + + -or- + + refers to an invalid device. + + -or- + + is an empty string. + + -or- + is . is . - is , , or . - - -or- - - is and the file on disk does not exist. - - -or- - + is , , or . + + -or- + + is and the file on disk does not exist. + + -or- + An I/O error occurred. exceeds the maximum length defined by the operating system. @@ -387,44 +387,44 @@ Creates a memory-mapped file that has the specified access mode, name, and capacity from a file on disk. A memory-mapped file that has the specified characteristics. - - is an empty string, contains only white space, or has one or more invalid characters, as defined by the method. - - -or- - - refers to an invalid device. - - -or- - - is an empty string. - - -or- - + is an empty string, contains only white space, or has one or more invalid characters, as defined by the method. + + -or- + + refers to an invalid device. + + -or- + + is an empty string. + + -or- + is . is . - is greater than the size of the logical address space. - - -or- - - is less than zero. - - -or- - - is less than the file size (but not zero). - - -or- - + is greater than the size of the logical address space. + + -or- + + is less than zero. + + -or- + + is less than the file size (but not zero). + + -or- + is zero, and the size of the file on disk is also zero. An I/O error occurred. @@ -495,59 +495,59 @@ Creates a memory-mapped file that has the specified access mode, name, capacity, and access type from a file on disk. A memory-mapped file that has the specified characteristics. - - is an empty string. - - -or- - - is not an allowed value. - - -or- - - specifies an empty file. - - -or- - - is specified as and capacity is greater than the size of the file indicated by . - - -or- - + is an empty string. + + -or- + + is not an allowed value. + + -or- + + specifies an empty file. + + -or- + + is specified as and capacity is greater than the size of the file indicated by . + + -or- + is . is . - is greater than the size of the logical address space. - - -or- - - is less than zero. - - -or- - - is less than the file size (but not zero). - - -or- - - is zero, and the size of the file on disk is also zero. - - -or- - - is not a defined value. - - -or- - + is greater than the size of the logical address space. + + -or- + + is less than zero. + + -or- + + is less than the file size (but not zero). + + -or- + + is zero, and the size of the file on disk is also zero. + + -or- + + is not a defined value. + + -or- + The size of the file indicated by is greater than . - -or- - + -or- + An I/O error occurred. exceeds the maximum length defined by the operating system. @@ -684,8 +684,8 @@ The file stream of the existing file. A name to assign to the memory-mapped file, or for a that you do not intend to share across processes. The maximum size, in bytes, to allocate to the memory-mapped file. Specify 0 to set the capacity to the size of filestream. - One of the enumeration values that specifies the type of access allowed to the memory-mapped file. - + One of the enumeration values that specifies the type of access allowed to the memory-mapped file. + This parameter can't be set to . One of the enumeration values that specifies whether a handle to the memory-mapped file can be inherited by a child process. The default is . A value that indicates whether to close the source file stream when the is disposed. @@ -693,34 +693,34 @@ A memory-mapped file that has the specified characteristics. To be added. - is or an empty string. - - -or- - - and the length of the file are zero. - - -or- - - is set to or enumeration value, which is not allowed. - - -or- - + is or an empty string. + + -or- + + and the length of the file are zero. + + -or- + + is set to or enumeration value, which is not allowed. + + -or- + is set to and is larger than the length of . is . - is less than zero. - - -or- - - is less than the file size. - - -or- - - is not a valid enumeration value. - - -or- - + is less than zero. + + -or- + + is less than the file size. + + -or- + + is not a valid enumeration value. + + -or- + is not a valid enumeration value. @@ -752,23 +752,23 @@ System.IO.MemoryMappedFiles.MemoryMappedFile - - - - - - - + + + + + + + The to the file to map. A name to assign to the memory-mapped file, or for a that you do not intend to share across processes. The maximum size, in bytes, to allocate to the memory-mapped file. Specify 0 to set the capacity to the size of the file on disk. - One of the enumeration values that specifies the type of access allowed to the memory-mapped file. - + One of the enumeration values that specifies the type of access allowed to the memory-mapped file. + This parameter can't be set to . - The permissions that can be granted for file access and operations on memory-mapped files. - + The permissions that can be granted for file access and operations on memory-mapped files. + This parameter can be . One of the enumeration values that specifies whether a handle to the memory-mapped file can be inherited by a child process. The default is . @@ -776,38 +776,38 @@ Creates a memory-mapped file that has the specified name, capacity, access type, security permissions, inheritability, and disposal requirement from a file on disk. A memory-mapped file that has the specified characteristics. - - is an empty string. - - -or- - - and the length of the file are zero. - - -or- - + is an empty string. + + -or- + + and the length of the file are zero. + + -or- + is set to the or enumeration value, which is not allowed. is . - is less than zero. - - -or- - - is less than the file size. - - -or- - - is not a valid enumeration value. - - -or- - + is less than zero. + + -or- + + is less than the file size. + + -or- + + is not a valid enumeration value. + + -or- + is not a valid enumeration value. was closed. @@ -885,65 +885,65 @@ Creates a memory-mapped file that has the specified capacity in system memory. A memory-mapped file that has the specified name and capacity. - @@ -1013,24 +1013,24 @@ Process C says: True Creates a memory-mapped file that has the specified capacity and access type in system memory. A memory-mapped file that has the specified characteristics. - - is an empty string. - - -or- - + is an empty string. + + -or- + is set to write-only with the enumeration value. - is less than or equal to zero. - - -or- - + is less than or equal to zero. + + -or- + is not a valid enumeration value. .NET Core and .NET 5+ only: Calls to the CreateNew method with a named memory mapped file (that is, a non-null ) are supported on Windows operating systems only. Memory-Mapped Files @@ -1094,20 +1094,20 @@ Process C says: True A memory-mapped file that has the specified characteristics. To be added. - is an empty string. - - -or- - + is an empty string. + + -or- + is set to write-only with the enumeration value. - is less than or equal to zero. - - -or- - - is not a valid enumeration value. - - -or- - + is less than or equal to zero. + + -or- + + is not a valid enumeration value. + + -or- + is not a valid value. .NET Core and .NET 5+ only: Calls to the CreateNew method with a named memory mapped file (that is, a non-null ) are supported on Windows operating systems only. @@ -1140,47 +1140,47 @@ Process C says: True System.IO.MemoryMappedFiles.MemoryMappedFile - - - - - - + + + + + + A name to assign to the memory-mapped file, or for a that you do not intend to share across processes. The maximum size, in bytes, to allocate to the memory-mapped file. One of the enumeration values that specifies the type of access allowed to the memory-mapped file. The default is . A bitwise combination of enumeration values that specifies memory allocation options for the memory-mapped file. - The permissions that can be granted for file access and operations on memory-mapped files. - + The permissions that can be granted for file access and operations on memory-mapped files. + This parameter can be . One of the enumeration values that specifies whether a handle to the memory-mapped file can be inherited by a child process. The default is . Creates a memory-mapped file that has the specified capacity, access type, memory allocation, security permissions, and inheritability in system memory. A memory-mapped file that has the specified characteristics. - - is an empty string. - - -or- - + is an empty string. + + -or- + is set to write-only with the enumeration value. - is less than or equal to zero. - - -or- - - is not a valid enumeration value. - - -or- - + is less than or equal to zero. + + -or- + + is not a valid enumeration value. + + -or- + is not a valid enumeration value. Memory-Mapped Files @@ -1248,20 +1248,20 @@ Process C says: True Creates or opens a memory-mapped file that has the specified name and capacity in system memory. A memory-mapped file that has the specified name and size. - is an empty string. - is greater than the size of the logical address space. - - -or- - + is greater than the size of the logical address space. + + -or- + is less than or equal to zero. Memory-Mapped Files @@ -1321,30 +1321,30 @@ Process C says: True Creates or opens a memory-mapped file that has the specified name, capacity and access type in system memory. A memory-mapped file that has the specified characteristics. - is . - is an empty string. - - -or- - + is an empty string. + + -or- + is set to write-only with the enumeration value. - is greater than the size of the logical address space. - - -or- - - is less than or equal to zero. - - -or- - + is greater than the size of the logical address space. + + -or- + + is less than or equal to zero. + + -or- + is not a valid enumeration value. The operating system denied the specified access to the file; for example, access is set to or , but the file or directory is read-only. Memory-Mapped Files @@ -1408,24 +1408,24 @@ Process C says: True is . - is an empty string. - - -or- - + is an empty string. + + -or- + is set to write-only with the enumeration value. - is greater than the size of the logical address space. - - -or- - - is less than or equal to zero. - - -or- - - is not a valid enumeration value. - - -or- - + is greater than the size of the logical address space. + + -or- + + is less than or equal to zero. + + -or- + + is not a valid enumeration value. + + -or- + is not a valid enumeration value. The operating system denied the specified access to the file; for example, access is set to or , but the file or directory is read-only. @@ -1458,53 +1458,53 @@ Process C says: True System.IO.MemoryMappedFiles.MemoryMappedFile - - - - - - + + + + + + The name of the memory-mapped file. The maximum size, in bytes, to allocate to the memory-mapped file. One of the enumeration values that specifies the type of access allowed to the memory-mapped file. The default is . A bitwise combination of enumeration values that specifies memory allocation options for the memory-mapped file. - The permissions that can be granted for file access and operations on memory-mapped files. - + The permissions that can be granted for file access and operations on memory-mapped files. + This parameter can be . One of the enumeration values that specifies whether a handle to the memory-mapped file can be inherited by a child process. The default is . Creates or opens a memory-mapped file that has the specified name, capacity, access type, memory allocation, security permissions, and inheritability in system memory. A memory-mapped file that has the specified characteristics. - is . - is an empty string. - - -or- - + is an empty string. + + -or- + is set to write-only with the enumeration value. - is greater than the size of the logical address space. - - -or- - - is less than or equal to zero. - - -or- - - is not a valid enumeration value. - - -or- - + is greater than the size of the logical address space. + + -or- + + is less than or equal to zero. + + -or- + + is not a valid enumeration value. + + -or- + is not a valid enumeration value. The operating system denied the specified to the file; for example, is set to or , but the file or directory is read-only. Memory-Mapped Files @@ -1558,11 +1558,11 @@ Process C says: True Creates a that maps to a view of the memory-mapped file. A randomly accessible block of memory. - Access to the memory-mapped file is unauthorized. @@ -1618,28 +1618,28 @@ Process C says: True Creates a that maps to a view of the memory-mapped file, and that has the specified offset and size. A randomly accessible block of memory. - class. - + class. + :::code language="csharp" source="~/snippets/csharp/System.IO.MemoryMappedFiles/MemoryMappedFile/Overview/program.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/memorymappedfiles.memorymappedfile.createfromfile/vb/program.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/memorymappedfiles.memorymappedfile.createfromfile/vb/program.vb" id="Snippet2"::: + ]]> - or is a negative value. - - -or- - + or is a negative value. + + -or- + is greater than the logical address space. Access to the memory-mapped file is unauthorized. An I/O error occurred. @@ -1697,20 +1697,20 @@ Process C says: True Creates a that maps to a view of the memory-mapped file, and that has the specified offset, size, and access restrictions. A randomly accessible block of memory. - - or is a negative value. - - -or- - + or is a negative value. + + -or- + is greater than the logical address space. is invalid for the memory-mapped file. @@ -1766,19 +1766,19 @@ Process C says: True Creates a stream that maps to a view of the memory-mapped file. A stream of memory. - method. - + method. + :::code language="csharp" source="~/snippets/csharp/System.IO.MemoryMappedFiles/MemoryMappedFile/CreateNew/program2.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.io.memorymappedfiles_ipc_x/vb/program.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.io.memorymappedfiles_ipc_x/vb/program.vb" id="Snippet2"::: + ]]> Access to the memory-mapped file is unauthorized. @@ -1834,20 +1834,20 @@ Process C says: True Creates a stream that maps to a view of the memory-mapped file, and that has the specified offset and size. A stream of memory that has the specified offset and size. - - or is a negative value. - - -or- - + or is a negative value. + + -or- + is greater than the logical address space. Access to the memory-mapped file is unauthorized. @@ -1906,32 +1906,32 @@ Process C says: True Creates a stream that maps to a view of the memory-mapped file, and that has the specified offset, size, and access type. A stream of memory that has the specified characteristics. - - or is a negative value. - - -or- - - is greater than the logical address space. - - -or- - + or is a negative value. + + -or- + + is greater than the logical address space. + + -or- + is not a valid enumeration value. is invalid for the memory-mapped file. - is greater than the total virtual memory. - - -or- - + is greater than the total virtual memory. + + -or- + is invalid for the memory-mapped file. Memory-Mapped Files @@ -2082,10 +2082,10 @@ Process C says: True An underlying call to set security information failed. An underlying call to set security information failed. The memory-mapped file is closed. - An underlying call to set security information failed. - - -or- - + An underlying call to set security information failed. + + -or- + The memory-mapped file was opened as only. Memory-Mapped Files @@ -2151,25 +2151,25 @@ Process C says: True Opens an existing memory-mapped file that has the specified name in system memory. A memory-mapped file that has the specified name. - method). - + method). + :::code language="csharp" source="~/snippets/csharp/System.IO.MemoryMappedFiles/MemoryMappedFile/OpenExisting/program.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/memorymappedfiles.memorymappedfile.openexisting/vb/program.vb" id="Snippet1"::: - - **Opening a Non-Persisted Memory-Mapped File** - - The following example opens a memory-mapped file used for inter-process communication. This code example is part of a larger example provided for the method. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/memorymappedfiles.memorymappedfile.openexisting/vb/program.vb" id="Snippet1"::: + + **Opening a Non-Persisted Memory-Mapped File** + + The following example opens a memory-mapped file used for inter-process communication. This code example is part of a larger example provided for the method. + ]]> @@ -2303,10 +2303,10 @@ Process C says: True is an empty string. - is not a valid enumeration value. - - -or- - + is not a valid enumeration value. + + -or- + is not a valid enumeration value. The requested access is invalid for the memory-mapped file. The file specified for does not exist. @@ -2391,7 +2391,7 @@ Process C says: True System.Void - + The permissions that can be granted for file access and operations on memory-mapped files. diff --git a/xml/System.IO.Pipes/AnonymousPipeServerStream.xml b/xml/System.IO.Pipes/AnonymousPipeServerStream.xml index 81e050c386d..6ef6573e7fb 100644 --- a/xml/System.IO.Pipes/AnonymousPipeServerStream.xml +++ b/xml/System.IO.Pipes/AnonymousPipeServerStream.xml @@ -52,29 +52,29 @@ Exposes a stream around an anonymous pipe, which supports both synchronous and asynchronous read and write operations. - class enables a parent process to send or receive information from a child process. - - Anonymous pipes are unnamed, one-way pipes that typically transfer data between parent and child processes. Anonymous pipes are always local; they cannot be used over a network. A value of is not supported because anonymous pipes are defined to be one-way. - - Anonymous pipes do not support the read mode. - - The client side of an anonymous pipe must be created from a pipe handle provided by the server side by calling the method. The string is then passed as a parameter when creating the client process. From the client process, it is then passed to the constructor as the `pipeHandleAsString` parameter. - - The object must dispose the client handle using the method in order to be notified when the client exits. - -## Examples - -The following example sends a string from a parent process to a child process using anonymous pipes. This example creates an object in a parent process with a value of . It also creates an object in a child process with a value of . The parent process then sends a user-supplied string to the child process. The string is displayed to the console. - - This example is for the server process, which uses the class. For the entire code example, including the code for both the pipe client and server, see [How to: Use Anonymous Pipes for Local Interprocess Communication](/dotnet/standard/io/how-to-use-anonymous-pipes-for-local-interprocess-communication). - + class enables a parent process to send or receive information from a child process. + + Anonymous pipes are unnamed, one-way pipes that typically transfer data between parent and child processes. Anonymous pipes are always local; they cannot be used over a network. A value of is not supported because anonymous pipes are defined to be one-way. + + Anonymous pipes do not support the read mode. + + The client side of an anonymous pipe must be created from a pipe handle provided by the server side by calling the method. The string is then passed as a parameter when creating the client process. From the client process, it is then passed to the constructor as the `pipeHandleAsString` parameter. + + The object must dispose the client handle using the method in order to be notified when the client exits. + +## Examples + +The following example sends a string from a parent process to a child process using anonymous pipes. This example creates an object in a parent process with a value of . It also creates an object in a child process with a value of . The parent process then sends a user-supplied string to the child process. The string is displayed to the console. + + This example is for the server process, which uses the class. For the entire code example, including the code for both the pipe client and server, see [How to: Use Anonymous Pipes for Local Interprocess Communication](/dotnet/standard/io/how-to-use-anonymous-pipes-for-local-interprocess-communication). + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.Pipes.AnonymousPipeServerStream_Sample/cpp/program.cpp"::: :::code language="csharp" source="~/snippets/csharp/System.IO.Pipes/AnonymousPipeServerStream/Overview/Program.cs"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.Pipes.AnonymousPipeServerStream_Sample/vb/program.vb"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.Pipes.AnonymousPipeServerStream_Sample/vb/program.vb"::: + ]]> @@ -133,13 +133,13 @@ The following example sends a string from a parent process to a child process us Initializes a new instance of the class. - constructors without a parameter, the default direction is . A value of is not supported because anonymous pipes are defined to be one-way. - - This constructor creates an object that has the default buffer size, no pipe security, and a value of . - + constructors without a parameter, the default direction is . A value of is not supported because anonymous pipes are defined to be one-way. + + This constructor creates an object that has the default buffer size, no pipe security, and a value of . + ]]> @@ -189,18 +189,18 @@ The following example sends a string from a parent process to a child process us - One of the enumeration values that determines the direction of the pipe. - + One of the enumeration values that determines the direction of the pipe. + Anonymous pipes can only be in one direction, so cannot be set to . Initializes a new instance of the class with the specified pipe direction. - value of is not supported because anonymous pipes are defined to be one-way. - - This constructor creates an object that has the default buffer size, no pipe security, and a value of . - + value of is not supported because anonymous pipes are defined to be one-way. + + This constructor creates an object that has the default buffer size, no pipe security, and a value of . + ]]> @@ -253,28 +253,28 @@ The following example sends a string from a parent process to a child process us - One of the enumeration values that determines the direction of the pipe. - + One of the enumeration values that determines the direction of the pipe. + Anonymous pipes can only be in one direction, so cannot be set to . One of the enumeration values that determines whether the underlying handle can be inherited by child processes. Must be set to either or . Initializes a new instance of the class with the specified pipe direction and inheritability mode. - value of is not supported because anonymous pipes are defined to be one-way. - - This constructor creates an object that has the default buffer size and no pipe security. - - - -## Examples - The following example demonstrates a method to send a string from a parent process to a child process using anonymous pipes. In this example, an object is created in a parent process with a value of . - + value of is not supported because anonymous pipes are defined to be one-way. + + This constructor creates an object that has the default buffer size and no pipe security. + + + +## Examples + The following example demonstrates a method to send a string from a parent process to a child process using anonymous pipes. In this example, an object is created in a parent process with a value of . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.Pipes.AnonymousPipeServerStream_Sample/cpp/program.cpp"::: :::code language="csharp" source="~/snippets/csharp/System.IO.Pipes/AnonymousPipeServerStream/Overview/Program.cs"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.Pipes.AnonymousPipeServerStream_Sample/vb/program.vb"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.Pipes.AnonymousPipeServerStream_Sample/vb/program.vb"::: + ]]> @@ -330,18 +330,18 @@ The following example sends a string from a parent process to a child process us - One of the enumeration values that determines the direction of the pipe. - + One of the enumeration values that determines the direction of the pipe. + Anonymous pipes can only be in one direction, so cannot be set to . A safe handle for the pipe that this object will encapsulate. A safe handle for the object. Initializes a new instance of the class from the specified pipe handles. - value of is not supported because anonymous pipes are defined to be one-way. - + value of is not supported because anonymous pipes are defined to be one-way. + ]]> @@ -350,10 +350,10 @@ The following example sends a string from a parent process to a child process us or is . is set to . - An I/O error, such as a disk error, has occurred. - - -or- - + An I/O error, such as a disk error, has occurred. + + -or- + The stream has been closed. @@ -404,27 +404,27 @@ The following example sends a string from a parent process to a child process us - One of the enumeration values that determines the direction of the pipe. - + One of the enumeration values that determines the direction of the pipe. + Anonymous pipes can only be in one direction, so cannot be set to . One of the enumeration values that determines whether the underlying handle can be inherited by child processes. Must be set to either or . The size of the buffer. This value must be greater than or equal to 0. Initializes a new instance of the class with the specified pipe direction, inheritability mode, and buffer size. - value of is not supported because anonymous pipes are defined to be one-way. - - This constructor creates an object without pipe security. - + value of is not supported because anonymous pipes are defined to be one-way. + + This constructor creates an object without pipe security. + ]]> - is not set to either or . - - -or- - + is not set to either or . + + -or- + is less than 0. is set to . @@ -460,32 +460,32 @@ The following example sends a string from a parent process to a child process us - - - - + + + + - One of the enumeration values that determines the direction of the pipe. - + One of the enumeration values that determines the direction of the pipe. + Anonymous pipes can only be in one direction, so cannot be set to . One of the enumeration values that determines whether the underlying handle can be inherited by child processes. The size of the buffer. This value must be greater than or equal to 0. An object that determines the access control and audit security for the pipe. Initializes a new instance of the class with the specified pipe direction, inheritability mode, buffer size, and pipe security. - value of is not supported because anonymous pipes are defined to be one-way. - + value of is not supported because anonymous pipes are defined to be one-way. + ]]> - is not set to either or . - - -or- - + is not set to either or . + + -or- + is less than 0. is set to . @@ -535,11 +535,11 @@ The following example sends a string from a parent process to a child process us Gets the safe handle for the object that is currently connected to the object. A handle for the object that is currently connected to the object. - method should be called after a client handle has been passed to a client process. If this method is not called, the object will not receive notice when the client disposes of its object. - + method should be called after a client handle has been passed to a client process. If this method is not called, the object will not receive notice when the client disposes of its object. + ]]> @@ -636,20 +636,20 @@ The following example sends a string from a parent process to a child process us Closes the local copy of the object's handle. - method should be called after the client handle has been passed to the client. If this method is not called, the object will not receive notice when the client disposes of its object. - - - -## Examples - The following example demonstrates a way to send a string from a parent process to a child process by using anonymous pipes. In this example, an object is created in a parent process with a value of . - + method should be called after the client handle has been passed to the client. If this method is not called, the object will not receive notice when the client disposes of its object. + + + +## Examples + The following example demonstrates a way to send a string from a parent process to a child process by using anonymous pipes. In this example, an object is created in a parent process with a value of . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.Pipes.AnonymousPipeServerStream_Sample/cpp/program.cpp"::: :::code language="csharp" source="~/snippets/csharp/System.IO.Pipes/AnonymousPipeServerStream/Overview/Program.cs"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.Pipes.AnonymousPipeServerStream_Sample/vb/program.vb"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.Pipes.AnonymousPipeServerStream_Sample/vb/program.vb"::: + ]]> @@ -737,20 +737,20 @@ The following example sends a string from a parent process to a child process us Gets the connected object's handle as a string. A string that represents the connected object's handle. - method should be called after a client handle has been passed to a client process. If this method is not called, the object will not receive notice when the client disposes of its object. - - - -## Examples - The following example demonstrates a way to send a string from a parent process to a child process by using anonymous pipes. In this example, an object is created in a parent process with a value of . - + method should be called after a client handle has been passed to a client process. If this method is not called, the object will not receive notice when the client disposes of its object. + + + +## Examples + The following example demonstrates a way to send a string from a parent process to a child process by using anonymous pipes. In this example, an object is created in a parent process with a value of . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.Pipes.AnonymousPipeServerStream_Sample/cpp/program.cpp"::: :::code language="csharp" source="~/snippets/csharp/System.IO.Pipes/AnonymousPipeServerStream/Overview/Program.cs"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.Pipes.AnonymousPipeServerStream_Sample/vb/program.vb"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.Pipes.AnonymousPipeServerStream_Sample/vb/program.vb"::: + ]]> @@ -799,11 +799,11 @@ The following example sends a string from a parent process to a child process us Sets the reading mode for the object. For anonymous pipes, transmission mode must be . The reading mode for the object. - read mode. Because the default value of this property is , there is never a reason to set this property in your code. +Anonymous pipes do not support the read mode. Because the default value of this property is , there is never a reason to set this property in your code. ]]> @@ -857,19 +857,19 @@ Anonymous pipes do not support the Gets the pipe transmission mode that is supported by the current pipe. The that is supported by the current pipe. - read mode. - -## Examples - The following example demonstrates a way to send a string from a parent process to a child process by using anonymous pipes. In this example, an object is created in a parent process and the property is displayed to the console. - +Anonymous pipes do not support the read mode. + +## Examples + The following example demonstrates a way to send a string from a parent process to a child process by using anonymous pipes. In this example, an object is created in a parent process and the property is displayed to the console. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.Pipes.AnonymousPipeServerStream_Sample/cpp/program.cpp"::: :::code language="csharp" source="~/snippets/csharp/System.IO.Pipes/AnonymousPipeServerStream/Overview/Program.cs"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.Pipes.AnonymousPipeServerStream_Sample/vb/program.vb"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.Pipes.AnonymousPipeServerStream_Sample/vb/program.vb"::: + ]]> diff --git a/xml/System.IO.Pipes/NamedPipeClientStream.xml b/xml/System.IO.Pipes/NamedPipeClientStream.xml index 522bdcf11c3..319b954aa7f 100644 --- a/xml/System.IO.Pipes/NamedPipeClientStream.xml +++ b/xml/System.IO.Pipes/NamedPipeClientStream.xml @@ -52,21 +52,21 @@ Exposes a around a named pipe, which supports both synchronous and asynchronous read and write operations. - objects. - - Any process can act as either a named pipe server or client, or both. - -## Examples - The following example demonstrates a way to send a string from a parent process to a child process on the same computer using named pipes. This example creates a object in a parent process. The object has a value of . The server then waits for a object in a child process to connect to it. In this example, both processes are on the same computer and the object has a value of . The parent process then sends a user-supplied string to the child process. The string is displayed to the console. - - This example is for the client process, which connects to the server process. For the entire code sample, including the code for both the pipe client and server, see [How to: Use Named Pipes for Network Interprocess Communication](/dotnet/standard/io/how-to-use-named-pipes-for-network-interprocess-communication). - + objects. + + Any process can act as either a named pipe server or client, or both. + +## Examples + The following example demonstrates a way to send a string from a parent process to a child process on the same computer using named pipes. This example creates a object in a parent process. The object has a value of . The server then waits for a object in a child process to connect to it. In this example, both processes are on the same computer and the object has a value of . The parent process then sends a user-supplied string to the child process. The string is displayed to the console. + + This example is for the client process, which connects to the server process. For the entire code sample, including the code for both the pipe client and server, see [How to: Use Named Pipes for Network Interprocess Communication](/dotnet/standard/io/how-to-use-named-pipes-for-network-interprocess-communication). + :::code language="csharp" source="~/snippets/csharp/System.IO.Pipes/NamedPipeClientStream/Overview/Program.cs" id="Snippet01"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.Pipes.NamedPipeClientStream_Sample1/vb/program.vb" id="Snippet01"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.Pipes.NamedPipeClientStream_Sample1/vb/program.vb" id="Snippet01"::: + ]]> @@ -129,21 +129,21 @@ The name of the pipe. Initializes a new instance of the class with the specified pipe name. - value of . - -- A default value of . - -- A default value of . - -- A default value of . - + value of . + +- A default value of . + +- A default value of . + +- A default value of . + ]]> @@ -204,19 +204,19 @@ The name of the pipe. Initializes a new instance of the class with the specified pipe and server names. - value of . - -- A default value of . - -- A default value of . - -- A default value of . - + value of . + +- A default value of . + +- A default value of . + +- A default value of . + ]]> @@ -279,25 +279,25 @@ One of the enumeration values that determines the direction of the pipe. Initializes a new instance of the class with the specified pipe and server names, and the specified pipe direction. - value of . - -- A default value of . - -- A default value of . - - - -## Examples - The following example demonstrates a method to send a string from a parent process to a child process using named pipes. This example creates a object in a child process, which then connects to a pipe on the local computer. The server example can be seen in the class. This example is part of a larger example provided for the and classes. - + value of . + +- A default value of . + +- A default value of . + + + +## Examples + The following example demonstrates a method to send a string from a parent process to a child process using named pipes. This example creates a object in a child process, which then connects to a pipe on the local computer. The server example can be seen in the class. This example is part of a larger example provided for the and classes. + :::code language="csharp" source="~/snippets/csharp/System.IO.Pipes/NamedPipeClientStream/Overview/Program.cs" id="Snippet01"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.Pipes.NamedPipeClientStream_Sample1/vb/program.vb" id="Snippet01"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.Pipes.NamedPipeClientStream_Sample1/vb/program.vb" id="Snippet01"::: + ]]> @@ -305,10 +305,10 @@ or is a zero-length string. - is set to "anonymous". - - -or- - + is set to "anonymous". + + -or- + is not a valid value. @@ -431,15 +431,15 @@ One of the enumeration values that determines how to open or create the pipe. Initializes a new instance of the class with the specified pipe and server names, and the specified pipe direction and pipe options. - value of . - -- A default value of . - + value of . + +- A default value of . + ]]> @@ -447,14 +447,14 @@ or is a zero-length string. - is set to "anonymous". - - -or- - - is not a valid value. - - -or- - + is set to "anonymous". + + -or- + + is not a valid value. + + -or- + is not a valid value. @@ -514,11 +514,11 @@ One of the enumeration values that determines the security impersonation level. Initializes a new instance of the class with the specified pipe and server names, and the specified pipe direction, pipe options, and security impersonation level. - value of . - + value of . + ]]> @@ -526,18 +526,18 @@ or is a zero-length string. - is set to "anonymous". - - -or- - - is not a valid value. - - -or- - - is not a valid value. - - -or- - + is set to "anonymous". + + -or- + + is not a valid value. + + -or- + + is not a valid value. + + -or- + is not a valid value. @@ -567,12 +567,12 @@ - - - - - - + + + + + + The name of the remote computer to connect to, or "." to specify the local computer. @@ -583,11 +583,11 @@ One of the enumeration values that determines whether the underlying handle will be inheritable by child processes. Initializes a new instance of the class with the specified pipe and server names, and the specified pipe options, security impersonation level, and inheritability mode. - , the pipe direction will be . If the value of `desiredAccessRights` is , the pipe direction will be . If the value of `desiredAccessRights` includes both and , the pipe direction will be . - + , the pipe direction will be . If the value of `desiredAccessRights` is , the pipe direction will be . If the value of `desiredAccessRights` includes both and , the pipe direction will be . + ]]> @@ -595,18 +595,18 @@ or is a zero-length string. - is set to "anonymous". - - -or- - - is not a valid value. - - -or- - - is not a valid value. - - -or- - + is set to "anonymous". + + -or- + + is not a valid value. + + -or- + + is not a valid value. + + -or- + is not a valid value. @@ -668,22 +668,22 @@ or is a zero-length string. - is set to "anonymous". - - -or- - - is not a valid value. - - -or- - - is not a valid value. - - -or- - - is not a valid value. - - -or- - + is set to "anonymous". + + -or- + + is not a valid value. + + -or- + + is not a valid value. + + -or- + + is not a valid value. + + -or- + is not a valid value. @@ -786,23 +786,23 @@ Connects to a waiting server with an infinite time-out value. - method with an infinite time-out value. - - This method waits for a pipe instance to become available. might return before is called from the object, but will not return until has returned. - - Any data written to the pipe after a object has connected, but before the server has called , will be available to the server following the call to . - - - -## Examples - The following example demonstrates a method to send a string from a parent process to a child process using named pipes. This example creates a object in a child process, which then connects to a pipe on the local computer. The server example can be seen in the class. This example is part of a larger example provided for the and classes. - + method with an infinite time-out value. + + This method waits for a pipe instance to become available. might return before is called from the object, but will not return until has returned. + + Any data written to the pipe after a object has connected, but before the server has called , will be available to the server following the call to . + + + +## Examples + The following example demonstrates a method to send a string from a parent process to a child process using named pipes. This example creates a object in a child process, which then connects to a pipe on the local computer. The server example can be seen in the class. This example is part of a larger example provided for the and classes. + :::code language="csharp" source="~/snippets/csharp/System.IO.Pipes/NamedPipeClientStream/Overview/Program.cs" id="Snippet01"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.Pipes.NamedPipeClientStream_Sample1/vb/program.vb" id="Snippet01"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.Pipes.NamedPipeClientStream_Sample1/vb/program.vb" id="Snippet01"::: + ]]> The client is already connected. @@ -855,13 +855,13 @@ The number of milliseconds to wait for the server to respond before the connection times out. Connects to a waiting server within the specified time-out period. - might return before is called from the , but will not return until has returned. You set the `timeout` parameter to to specify an infinite time-out value. - - Any data written to the pipe after a object has connected, but before the server has called , will be available to the server following the call to . - + might return before is called from the , but will not return until has returned. You set the `timeout` parameter to to specify an infinite time-out value. + + Any data written to the pipe after a object has connected, but before the server has called , will be available to the server following the call to . + ]]> Could not connect to the server within the specified period. @@ -1202,25 +1202,25 @@ Gets the number of server instances that share the same pipe name. The number of server instances that share the same pipe name. - object that the current object has a handle to or is connected to. If the current object has not yet connected to a named pipe server, or if the current pipe handle has not yet been set, this property throws an . - - - -## Examples - The following example demonstrates a method to send a string from a parent process to a child process using named pipes. In this example, a object is created in a child process, which then connects to a pipe on the local computer. The server example can be seen in the class. This example is part of a larger example provided for the and classes. - + object that the current object has a handle to or is connected to. If the current object has not yet connected to a named pipe server, or if the current pipe handle has not yet been set, this property throws an . + + + +## Examples + The following example demonstrates a method to send a string from a parent process to a child process using named pipes. In this example, a object is created in a child process, which then connects to a pipe on the local computer. The server example can be seen in the class. This example is part of a larger example provided for the and classes. + :::code language="csharp" source="~/snippets/csharp/System.IO.Pipes/NamedPipeClientStream/Overview/Program.cs" id="Snippet01"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.Pipes.NamedPipeClientStream_Sample1/vb/program.vb" id="Snippet01"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.Pipes.NamedPipeClientStream_Sample1/vb/program.vb" id="Snippet01"::: + ]]> - The pipe handle has not been set. - - -or- - + The pipe handle has not been set. + + -or- + The current object has not yet connected to a object. The pipe is broken or an I/O error occurred. The underlying pipe handle is closed. diff --git a/xml/System.IO.Pipes/NamedPipeServerStream.xml b/xml/System.IO.Pipes/NamedPipeServerStream.xml index 419742a02ae..83de2e3650d 100644 --- a/xml/System.IO.Pipes/NamedPipeServerStream.xml +++ b/xml/System.IO.Pipes/NamedPipeServerStream.xml @@ -53,21 +53,21 @@ Exposes a around a named pipe, supporting both synchronous and asynchronous read and write operations. - objects. - - Any process can act as either a named pipe server or client, or both. - -## Examples - The following example demonstrates a way to send a string from a parent process to a child process on the same computer using named pipes. This example creates a object in a parent process with a value of . The server then waits for a object in a child process to connect to it. In this example, both processes are on the same computer and the object has a value of . The parent process then sends a user-supplied string to the child process. The string is displayed to the console. - - This example is for the server process, which uses the class. For the entire code example, including the code for both the pipe client and server, see [How to: Use Named Pipes for Network Interprocess Communication](/dotnet/standard/io/how-to-use-named-pipes-for-network-interprocess-communication). - + objects. + + Any process can act as either a named pipe server or client, or both. + +## Examples + The following example demonstrates a way to send a string from a parent process to a child process on the same computer using named pipes. This example creates a object in a parent process with a value of . The server then waits for a object in a child process to connect to it. In this example, both processes are on the same computer and the object has a value of . The parent process then sends a user-supplied string to the child process. The string is displayed to the console. + + This example is for the server process, which uses the class. For the entire code example, including the code for both the pipe client and server, see [How to: Use Named Pipes for Network Interprocess Communication](/dotnet/standard/io/how-to-use-named-pipes-for-network-interprocess-communication). + :::code language="csharp" source="~/snippets/csharp/System.IO.Pipes/NamedPipeServerStream/Overview/Program.cs" id="Snippet01"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.Pipes.NamedPipeServerStream_Sample1/vb/program.vb" id="Snippet01"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.Pipes.NamedPipeServerStream_Sample1/vb/program.vb" id="Snippet01"::: + ]]> @@ -130,27 +130,27 @@ The name of the pipe. Initializes a new instance of the class with the specified pipe name. - object that has the following characteristics: - -- A default pipe direction of . - -- The maximum number of server instances that share the same name set to 1. - -- A value of . - -- A value of . - -- Default input and output buffer sizes. - -- No pipe security. - -- A value of . - -- No specified additional . - + object that has the following characteristics: + +- A default pipe direction of . + +- The maximum number of server instances that share the same name set to 1. + +- A value of . + +- A value of . + +- Default input and output buffer sizes. + +- No pipe security. + +- A value of . + +- No specified additional . + ]]> @@ -214,31 +214,31 @@ One of the enumeration values that determines the direction of the pipe. Initializes a new instance of the class with the specified pipe name and pipe direction. - object that has the following characteristics: - -- A value of . - -- A value of . - -- Default input and output buffer sizes. - -- No pipe security. - -- A value of . - -- No specified additional . - - - -## Examples - The following example demonstrates a method to send a string from a parent process to a child process using named pipes. This example creates a object in a parent process. The object has a value of , which then blocks until a object establishes a connection to the current object. - + object that has the following characteristics: + +- A value of . + +- A value of . + +- Default input and output buffer sizes. + +- No pipe security. + +- A value of . + +- No specified additional . + + + +## Examples + The following example demonstrates a method to send a string from a parent process to a child process using named pipes. This example creates a object in a parent process. The object has a value of , which then blocks until a object establishes a connection to the current object. + :::code language="csharp" source="~/snippets/csharp/System.IO.Pipes/NamedPipeServerStream/Overview/Program.cs" id="Snippet01"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.Pipes.NamedPipeServerStream_Sample1/vb/program.vb" id="Snippet01"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.Pipes.NamedPipeServerStream_Sample1/vb/program.vb" id="Snippet01"::: + ]]> @@ -246,10 +246,10 @@ is a zero-length string. - is set to "anonymous". - - -or- - + is set to "anonymous". + + -or- + is not a valid value. contains a colon (":"). @@ -308,25 +308,25 @@ The maximum number of server instances that share the same name. You can pass for this value. Initializes a new instance of the class with the specified pipe name, pipe direction, and maximum number of server instances. - object that has the following characteristics: - -- A default value of 1 for the maximum number of server instances that share the same name. - -- A default value of . - -- A value of . - -- Default input and output buffer sizes. - -- No pipe security. - -- A value of . - -- No specified additional . - + object that has the following characteristics: + +- A default value of 1 for the maximum number of server instances that share the same name. + +- A default value of . + +- A value of . + +- Default input and output buffer sizes. + +- No pipe security. + +- A value of . + +- No specified additional . + ]]> @@ -334,26 +334,26 @@ is a zero-length string. - is set to "anonymous". - - -or- - - is not a valid value. - - -or- - - A non-negative number is required. - - -or- - - is less than -1 or greater than 254 (-1 indicates ) - - -or- - - or is required. - - -or- - + is set to "anonymous". + + -or- + + is not a valid value. + + -or- + + A non-negative number is required. + + -or- + + is less than -1 or greater than 254 (-1 indicates ) + + -or- + + or is required. + + -or- + Access rights is limited to the , , and flags. contains a colon (":"). @@ -423,10 +423,10 @@ is an invalid handle. - is not a valid pipe handle. - - -or- - + is not a valid pipe handle. + + -or- + The maximum number of server instances has been exceeded. @@ -484,21 +484,21 @@ One of the enumeration values that determines the transmission mode of the pipe. Initializes a new instance of the class with the specified pipe name, pipe direction, maximum number of server instances, and transmission mode. - object that has the following characteristics: - -- A default value of . - -- Default input and output buffer sizes. - -- No pipe security. - -- A value of . - -- No specified additional . - + object that has the following characteristics: + +- A default value of . + +- Default input and output buffer sizes. + +- No pipe security. + +- A value of . + +- No specified additional . + ]]> @@ -506,14 +506,14 @@ is a zero-length string. - is set to "anonymous". - - -or- - - is not a valid value. - - -or- - + is set to "anonymous". + + -or- + + is not a valid value. + + -or- + is less than -1 or greater than 254 (-1 indicates ) contains a colon (":"). @@ -576,19 +576,19 @@ One of the enumeration values that determines how to open or create the pipe. Initializes a new instance of the class with the specified pipe name, pipe direction, maximum number of server instances, transmission mode, and pipe options. - object that has the following characteristics: - -- Default input and output buffer sizes. - -- No pipe security. - -- A value of . - -- No specified additional . - + object that has the following characteristics: + +- Default input and output buffer sizes. + +- No pipe security. + +- A value of . + +- No specified additional . + ]]> @@ -596,18 +596,18 @@ is a zero-length string. - is set to "anonymous". - - -or- - - is not a valid value. - - -or- - - is less than -1 or greater than 254 (-1 indicates ) - - -or- - + is set to "anonymous". + + -or- + + is not a valid value. + + -or- + + is less than -1 or greater than 254 (-1 indicates ) + + -or- + is not a valid value. contains a colon (":"). @@ -674,17 +674,17 @@ A positive value greater than 0 that indicates the output buffer size. Initializes a new instance of the class with the specified pipe name, pipe direction, maximum number of server instances, transmission mode, pipe options, and recommended in and out buffer sizes. - object that has the following characteristics: - -- No additional pipe security. - -- A default value of . - -- No specified additional . - + object that has the following characteristics: + +- No additional pipe security. + +- A default value of . + +- No specified additional . + ]]> @@ -692,22 +692,22 @@ is a zero-length string. - is set to "anonymous". - - -or- - - is not a valid value. - - -or- - - is less than -1 or greater than 254 (-1 indicates ) - - -or- - - is not a valid value. - - -or- - + is set to "anonymous". + + -or- + + is not a valid value. + + -or- + + is less than -1 or greater than 254 (-1 indicates ) + + -or- + + is not a valid value. + + -or- + is negative. contains a colon (":"). @@ -744,14 +744,14 @@ - - - - - - - - + + + + + + + + The name of the pipe. @@ -764,15 +764,15 @@ An object that determines the access control and audit security for the pipe. Initializes a new instance of the class with the specified pipe name, pipe direction, maximum number of server instances, transmission mode, pipe options, recommended in and out buffer sizes, and pipe security. - object that has the following characteristics: - -- A default value of . - -- No specified additional . - + object that has the following characteristics: + +- A default value of . + +- No specified additional . + ]]> @@ -780,22 +780,22 @@ is a zero-length string. - is set to "anonymous". - - -or- - - is not a valid value. - - -or- - - is less than -1 or greater than 254 (-1 indicates ) - - -or- - - is not a valid value. - - -or- - + is set to "anonymous". + + -or- + + is not a valid value. + + -or- + + is less than -1 or greater than 254 (-1 indicates ) + + -or- + + is not a valid value. + + -or- + is negative. contains a colon (":"). @@ -832,15 +832,15 @@ - - - - - - - - - + + + + + + + + + The name of the pipe. @@ -854,11 +854,11 @@ One of the enumeration values that determines whether the underlying handle can be inherited by child processes. Initializes a new instance of the class with the specified pipe name, pipe direction, maximum number of server instances, transmission mode, pipe options, recommended in and out buffer sizes, pipe security, and inheritability mode. - object that has no specified additional . - + object that has no specified additional . + ]]> @@ -866,26 +866,26 @@ is a zero-length string. - is set to "anonymous". - - -or- - - is not a valid value. - - -or- - - is less than -1 or greater than 254 (-1 indicates ) - - -or- - - is not a valid value. - - -or- - - is negative. - - -or- - + is set to "anonymous". + + -or- + + is not a valid value. + + -or- + + is less than -1 or greater than 254 (-1 indicates ) + + -or- + + is not a valid value. + + -or- + + is negative. + + -or- + is not a valid value. contains a colon (":"). @@ -922,16 +922,16 @@ - - - - - - - - - - + + + + + + + + + + The name of the pipe. @@ -951,30 +951,30 @@ is a zero-length string. - is set to "anonymous". - - -or- - - is not a valid value. - - -or- - - is less than -1 or greater than 254 (-1 indicates ) - - -or- - - is not a valid value. - - -or- - - is negative. - - -or- - - is not a valid value. - - -or- - + is set to "anonymous". + + -or- + + is not a valid value. + + -or- + + is less than -1 or greater than 254 (-1 indicates ) + + -or- + + is not a valid value. + + -or- + + is negative. + + -or- + + is not a valid value. + + -or- + is not a valid value. contains a colon (":"). @@ -1035,23 +1035,23 @@ Begins an asynchronous operation to wait for a client to connect. An object that references the asynchronous request. - . - - must be called exactly once for every call to . - + . + + must be called exactly once for every call to . + ]]> - The pipe was not opened asynchronously. - - -or- - - A pipe connection has already been established. - - -or- - + The pipe was not opened asynchronously. + + -or- + + A pipe connection has already been established. + + -or- + The pipe handle has not been set. The pipe connection has been broken. The pipe is closed. @@ -1101,21 +1101,21 @@ Disconnects the current connection. - method will block until all the sent characters have been read unless the transmission mode of the pipe is set to and the buffer size is set in the constructor that created the object. In this case, not all of the messages will be received. Calling causes the server to block until all the data has been read from the pipe. - + method will block until all the sent characters have been read unless the transmission mode of the pipe is set to and the buffer size is set in the constructor that created the object. In this case, not all of the messages will be received. Calling causes the server to block until all the data has been read from the pipe. + ]]> - No pipe connections have been made yet. - - -or- - - The connected pipe has already disconnected. - - -or- - + No pipe connections have been made yet. + + -or- + + The connected pipe has already disconnected. + + -or- + The pipe handle has not been set. The pipe is closed. @@ -1166,19 +1166,19 @@ The pending asynchronous request. Ends an asynchronous operation to wait for a client to connect. - must be called exactly once for every call to . - + must be called exactly once for every call to . + ]]> is . - The pipe was not opened asynchronously. - - -or- - + The pipe was not opened asynchronously. + + -or- + The pipe handle has not been set. The pipe connection has been broken. The pipe is closed. @@ -1267,36 +1267,36 @@ Gets the user name of the client on the other end of the pipe. The user name of the client on the other end of the pipe. - method returns `null` if the client has not yet written to the pipe or if the connected client did not connect with a of . - - - -## Examples - The following example demonstrates a method to create a pipe server that can respond to multiple simultaneous client requests, and a method for client impersonation. This example creates a object in a parent process, which then creates multiple threads that wait for objects to connect. After a client is connected, it supplies a file name to the server and the contents of that file are read and sent back to the client. Because the impersonates the client when opening the file, the client can request only files that it has sufficient permissions to open. - + method returns `null` if the client has not yet written to the pipe or if the connected client did not connect with a of . + + + +## Examples + The following example demonstrates a method to create a pipe server that can respond to multiple simultaneous client requests, and a method for client impersonation. This example creates a object in a parent process, which then creates multiple threads that wait for objects to connect. After a client is connected, it supplies a file name to the server and the contents of that file are read and sent back to the client. Because the impersonates the client when opening the file, the client can request only files that it has sufficient permissions to open. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.Pipes.NamedPipeServerStream_ImpersonationSample1/cpp/program.cpp" id="Snippet01"::: :::code language="csharp" source="~/snippets/csharp/System.IO.Pipes/NamedPipeServerStream/GetImpersonationUserName/Program.cs" id="Snippet01"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.Pipes.NamedPipeServerStream_ImpersonationSample1/vb/program.vb" id="Snippet01"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.Pipes.NamedPipeServerStream_ImpersonationSample1/vb/program.vb" id="Snippet01"::: + ]]> - No pipe connections have been made yet. - - -or- - - The connected pipe has already disconnected. - - -or- - + No pipe connections have been made yet. + + -or- + + The connected pipe has already disconnected. + + -or- + The pipe handle has not been set. The pipe is closed. - The pipe connection has been broken. - - -or- - + The pipe connection has been broken. + + -or- + The user name of the client is longer than 19 characters. @@ -1337,11 +1337,11 @@ Represents the maximum number of server instances that the system resources allow. - when creating a object to set the maximum number of server instances that the system resources allow. - + when creating a object to set the maximum number of server instances that the system resources allow. + ]]> @@ -1392,36 +1392,36 @@ The delegate that specifies a method to call. Calls a delegate while impersonating the client. - object in a parent process, which then creates multiple threads that wait for objects to connect. After a client is connected, it supplies a file name to the server and the contents of that file are read and sent back to the client. Because the impersonates the client when opening the file, the client can request only files that it has sufficient permissions to open. - + object in a parent process, which then creates multiple threads that wait for objects to connect. After a client is connected, it supplies a file name to the server and the contents of that file are read and sent back to the client. Because the impersonates the client when opening the file, the client can request only files that it has sufficient permissions to open. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.Pipes.NamedPipeServerStream_ImpersonationSample1/cpp/program.cpp" id="Snippet01"::: :::code language="csharp" source="~/snippets/csharp/System.IO.Pipes/NamedPipeServerStream/GetImpersonationUserName/Program.cs" id="Snippet01"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.Pipes.NamedPipeServerStream_ImpersonationSample1/vb/program.vb" id="Snippet01"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.Pipes.NamedPipeServerStream_ImpersonationSample1/vb/program.vb" id="Snippet01"::: + ]]> - No pipe connections have been made yet. - - -or- - - The connected pipe has already disconnected. - - -or- - + No pipe connections have been made yet. + + -or- + + The connected pipe has already disconnected. + + -or- + The pipe handle has not been set. The pipe is closed. - The pipe connection has been broken. - - -or- - + The pipe connection has been broken. + + -or- + An I/O error occurred. @@ -1469,25 +1469,25 @@ Waits for a client to connect to this object. - object to block until a client connects. - - - -## Examples - The following example demonstrates a method to send a string from a parent process to a child process using named pipes. This example creates a object in a parent process. This object has a value of , which then blocks until a object establishes a connection to the object. This example is part of a larger example provided for the and classes. - + object to block until a client connects. + + + +## Examples + The following example demonstrates a method to send a string from a parent process to a child process using named pipes. This example creates a object in a parent process. This object has a value of , which then blocks until a object establishes a connection to the object. This example is part of a larger example provided for the and classes. + :::code language="csharp" source="~/snippets/csharp/System.IO.Pipes/NamedPipeServerStream/Overview/Program.cs" id="Snippet01"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.Pipes.NamedPipeServerStream_Sample1/vb/program.vb" id="Snippet01"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.Pipes.NamedPipeServerStream_Sample1/vb/program.vb" id="Snippet01"::: + ]]> - A pipe connection has already been established. - - -or- - + A pipe connection has already been established. + + -or- + The pipe handle has not been set. The pipe is closed. The pipe connection has been broken. @@ -1541,11 +1541,11 @@ Asynchronously waits for a client to connect to this object. A task that represents the asynchronous wait operation. - or . - + or . + 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 . ]]> @@ -1593,13 +1593,13 @@ Asynchronously waits for a client to connect to this object and monitors cancellation requests. A task that represents the asynchronous wait operation. - or . - - Cancellation requests using the cancellation token will only work if the object was created with a pipe option value of or if the cancellation occurs before the method is called. - + or . + + Cancellation requests using the cancellation token will only work if the object was created with a pipe option value of or if the cancellation occurs before the method is called. + 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.IO.Pipes/PipeStream.xml b/xml/System.IO.Pipes/PipeStream.xml index a1ea001fbd0..bfe61313f79 100644 --- a/xml/System.IO.Pipes/PipeStream.xml +++ b/xml/System.IO.Pipes/PipeStream.xml @@ -53,13 +53,13 @@ Exposes a object around a pipe, which supports both anonymous and named pipes. - class provides the base class for named and anonymous pipes operations in the .NET Framework. Use the and classes for named pipe operations. Use the and classes for anonymous pipe operations. - - For more information about pipes, see [Pipes](/dotnet/standard/io/pipe-operations). For an example of anonymous pipes, see [How to: Use Anonymous Pipes for Local Interprocess Communication](/dotnet/standard/io/how-to-use-anonymous-pipes-for-local-interprocess-communication). For an example of named pipes, see [How to: Use Named Pipes for Network Interprocess Communication](/dotnet/standard/io/how-to-use-named-pipes-for-network-interprocess-communication). - + class provides the base class for named and anonymous pipes operations in the .NET Framework. Use the and classes for named pipe operations. Use the and classes for anonymous pipe operations. + + For more information about pipes, see [Pipes](/dotnet/standard/io/pipe-operations). For an example of anonymous pipes, see [How to: Use Anonymous Pipes for Local Interprocess Communication](/dotnet/standard/io/how-to-use-anonymous-pipes-for-local-interprocess-communication). For an example of named pipes, see [How to: Use Named Pipes for Network Interprocess Communication](/dotnet/standard/io/how-to-use-named-pipes-for-network-interprocess-communication). + ]]> @@ -114,18 +114,18 @@ A positive value greater than or equal to 0 that indicates the buffer size. Initializes a new instance of the class using the specified value and buffer size. - . - + . + ]]> - is not a valid value. - - -or- - + is not a valid value. + + -or- + is less than 0. @@ -172,14 +172,14 @@ Initializes a new instance of the class using the specified , , and buffer size. To be added. - is not a valid value. - - -or- - - is not a valid value. - - -or- - + is not a valid value. + + -or- + + is not a valid value. + + -or- + is less than 0. @@ -253,24 +253,24 @@ Begins an asynchronous read operation. An object that references the asynchronous read. - object to the method to determine how many bytes were read and to release operating system resources used for reading. must be called once for every call to . This can be done either in the same code that called or in a callback that is passed to . - - Use the property to determine whether the current object supports read operations. - - If the pipe is closed or an invalid argument is passed to , the appropriate exceptions are raised immediately. Errors that occur during an asynchronous read request occur on the thread pool thread that is performing the request. The exceptions are raised when the code calls the method. - + object to the method to determine how many bytes were read and to release operating system resources used for reading. must be called once for every call to . This can be done either in the same code that called or in a callback that is passed to . + + Use the property to determine whether the current object supports read operations. + + If the pipe is closed or an invalid argument is passed to , the appropriate exceptions are raised immediately. Errors that occur during an asynchronous read request occur on the thread pool thread that is performing the request. The exceptions are raised when the code calls the method. + ]]> is . - is less than 0. - - -or- - + is less than 0. + + -or- + is less than 0. is greater than the number of bytes available in . @@ -350,24 +350,24 @@ Begins an asynchronous write operation. An object that references the asynchronous write operation. - must be called once for every call to . This can be done either in the same code that called or in a callback that is passed to . - - Use the property to determine whether the current object supports write operations. - - If the pipe is closed or an invalid argument is passed to , the appropriate exceptions are raised immediately. Errors that occur during an asynchronous write request occur on the thread pool thread that is performing the request. The exceptions are raised when the code calls the method. - + must be called once for every call to . This can be done either in the same code that called or in a callback that is passed to . + + Use the property to determine whether the current object supports write operations. + + If the pipe is closed or an invalid argument is passed to , the appropriate exceptions are raised immediately. Errors that occur during an asynchronous write request occur on the thread pool thread that is performing the request. The exceptions are raised when the code calls the method. + ]]> is . - is less than 0. - - -or- - + is less than 0. + + -or- + is less than 0. is greater than the number of bytes available in . @@ -422,11 +422,11 @@ if the stream supports read operations; otherwise, . - object is closed, this property returns `false`. - + object is closed, this property returns `false`. + ]]> @@ -470,11 +470,11 @@ in all cases. - object is closed, this property returns `false`. - + object is closed, this property returns `false`. + ]]> @@ -524,11 +524,11 @@ if the stream supports write operations; otherwise, . - object is closed, this property returns `false`. - + object is closed, this property returns `false`. + ]]> @@ -716,20 +716,20 @@ to release both managed and unmanaged resources; to release only unmanaged resources. Releases the unmanaged resources used by the class and optionally releases the managed resources. - method and the method, if it has been overridden. invokes the protected method with the `disposing` parameter set to `true`. `Finalize` invokes with `disposing` set to `false`. - -When the disposing parameter is `true`, this method releases all resources held by any managed objects that this object 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 object references. This method invokes the method of each referenced object. + ]]> - In derived classes, put all cleanup logic in the method. - - can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). - + In derived classes, put all cleanup logic in the method. + + can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). + For more information about and , see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). @@ -781,17 +781,17 @@ When the disposing parameter is `true`, this method releases all resources held Ends a pending asynchronous read request. The number of bytes that were read. A return value of 0 indicates the end of the stream (the pipe has been closed). - . - - Pass the returned object to the method to determine how many bytes were read and to release operating system resources used for reading. must be called once for every call to . This can be done either in the same code that called or in a callback that is passed to . - - Use the property to determine whether the current object supports read operations. - - If the pipe is closed or an invalid argument is passed to , the appropriate exceptions are raised immediately. Errors that occur during an asynchronous read request occur on the thread pool thread that is performing the request. The exceptions are raised when the code calls the method. - + . + + Pass the returned object to the method to determine how many bytes were read and to release operating system resources used for reading. must be called once for every call to . This can be done either in the same code that called or in a callback that is passed to . + + Use the property to determine whether the current object supports read operations. + + If the pipe is closed or an invalid argument is passed to , the appropriate exceptions are raised immediately. Errors that occur during an asynchronous read request occur on the thread pool thread that is performing the request. The exceptions are raised when the code calls the method. + ]]> @@ -847,15 +847,15 @@ When the disposing parameter is `true`, this method releases all resources held The reference to the pending asynchronous request. Ends a pending asynchronous write request. - must be called once for every call to . This can be done either in the same code that called or in a callback that is passed to . - - Use the property to determine whether the current object supports write operations. - - If the pipe is closed or an invalid argument is passed to , the appropriate exceptions are raised immediately. Errors that occur during an asynchronous write request occur on the thread pool thread that is performing the request. The exceptions are raised when the code the calls method. - + must be called once for every call to . This can be done either in the same code that called or in a callback that is passed to . + + Use the property to determine whether the current object supports write operations. + + If the pipe is closed or an invalid argument is passed to , the appropriate exceptions are raised immediately. Errors that occur during an asynchronous write request occur on the thread pool thread that is performing the request. The exceptions are raised when the code the calls method. + ]]> @@ -909,11 +909,11 @@ When the disposing parameter is `true`, this method releases all resources held Clears the buffer for the current stream and causes any buffered data to be written to the underlying device. - method is not supported in the class and does nothing when it is called. - + method is not supported in the class and does nothing when it is called. + ]]> The pipe is closed. @@ -987,11 +987,11 @@ When the disposing parameter is `true`, this method releases all resources held Gets a object that encapsulates the access control list (ACL) entries for the pipe described by the current object. A object that encapsulates the access control list (ACL) entries for the pipe described by the current object. - The pipe is closed. @@ -1044,11 +1044,11 @@ When the disposing parameter is `true`, this method releases all resources held Gets the size, in bytes, of the inbound buffer for a pipe. An integer value that represents the inbound buffer size, in bytes. - is 0, the buffer size is allocated as needed. - + is 0, the buffer size is allocated as needed. + ]]> The stream is unreadable. @@ -1113,11 +1113,11 @@ When the disposing parameter is `true`, this method releases all resources held to indicate that the handle was opened asynchronously; otherwise, . Initializes a object from the specified object. - property to `true`. - + property to `true`. + ]]> A handle cannot be bound to the pipe. @@ -1168,11 +1168,11 @@ When the disposing parameter is `true`, this method releases all resources held if the object was opened asynchronously; otherwise, . - property correctly. - + property correctly. + ]]> @@ -1216,11 +1216,11 @@ When the disposing parameter is `true`, this method releases all resources held if the object is connected; otherwise, . - property returns `true` only if the object is connected. If this property returns `false`, the pipe may be waiting to connect, or may be disconnected, closed, or broken. - + property returns `true` only if the object is connected. If this property returns `false`, the pipe may be waiting to connect, or may be disconnected, closed, or broken. + ]]> @@ -1269,11 +1269,11 @@ When the disposing parameter is `true`, this method releases all resources held if a handle to the object is exposed; otherwise, . - object. - + object. + ]]> @@ -1323,21 +1323,21 @@ When the disposing parameter is `true`, this method releases all resources held if there are no more characters to read in the message; otherwise, . - property was set to by the most recent call to or . - + property was set to by the most recent call to or . + ]]> - The pipe is not connected. - - -or- - - The pipe handle has not been set. - - -or- - + The pipe is not connected. + + -or- + + The pipe handle has not been set. + + -or- + The pipe's property value is not . The pipe is closed. @@ -1380,11 +1380,11 @@ When the disposing parameter is `true`, this method releases all resources held Gets the length of a stream, in bytes. 0 in all cases. - class does not support the property. - + class does not support the property. + ]]> Always thrown. @@ -1434,11 +1434,11 @@ When the disposing parameter is `true`, this method releases all resources held Gets the size, in bytes, of the outbound buffer for a pipe. The outbound buffer size, in bytes. - is 0, the buffer size is allocated as needed. - + is 0, the buffer size is allocated as needed. + ]]> The stream is unwriteable. @@ -1484,11 +1484,11 @@ When the disposing parameter is `true`, this method releases all resources held Gets or sets the current position of the current stream. 0 in all cases. - class does not support the property. - + class does not support the property. + ]]> Always thrown. @@ -1621,31 +1621,31 @@ The pipe handle has not been set. (Did your . This might be less than the number of bytes requested if that number of bytes is not currently available, or 0 if the end of the stream is reached. - property to determine whether the current object supports read operations. - - Calling the method blocks until `count` bytes are read or the end of the stream is reached. For asynchronous read operations, see and . - - - -## Examples - The following example creates an anonymous pipe client and pipe server. The pipe server uses the method to read a series of bytes from the pipe client as a validation code. Both the pipe client and the pipe server are part of the same example. The server portion of the example creates a client process and passes it an anonymous pipe handle as an argument. - + property to determine whether the current object supports read operations. + + Calling the method blocks until `count` bytes are read or the end of the stream is reached. For asynchronous read operations, see and . + + + +## Examples + The following example creates an anonymous pipe client and pipe server. The pipe server uses the method to read a series of bytes from the pipe client as a validation code. Both the pipe client and the pipe server are part of the same example. The server portion of the example creates a client process and passes it an anonymous pipe handle as an argument. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.io.pipes.pipestream/cpp/sample.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.IO.Pipes/PipeStream/Read/sample.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.io.pipes.pipestream/vb/sample.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.io.pipes.pipestream/vb/sample.vb" id="Snippet1"::: + ]]> is . - is less than 0. - - -or- - + is less than 0. + + -or- + is less than 0. is greater than the number of bytes available in . @@ -1695,15 +1695,15 @@ The pipe handle has not been set. (Did your property contains the total number of bytes read into the buffer. The result value can be less than the number of bytes allocated in the buffer if that many bytes are not currently available, or it can be 0 (zero) if the end of the stream has been reached. - method enables you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in applications where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#. +The method enables you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in applications where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#. -Use the property to determine whether the current instance supports reading. +Use the property to determine whether the current instance supports reading. -If the operation is canceled before it completes, the returned task contains the value for the property. +If the operation is canceled before it completes, the returned task contains the value for the property. ]]> @@ -1711,7 +1711,7 @@ If the operation is canceled before it completes, the returned task contains the Cannot access a closed pipe. The pipe hasn't been connected yet. --or- +-or- The pipe is in a disconnected state. @@ -1763,7 +1763,7 @@ The pipe handle has not been set. (Did your property contains the total number of bytes read into the buffer. The result value can be less than the number of bytes requested if the number of bytes currently available is less than the requested number, or it can be 0 (zero) if the end of the stream has been reached. - Reads a byte from a pipe. The byte, cast to , or -1 indicates the end of the stream (the pipe has been closed). - property to determine whether the current object supports read operations. - + property to determine whether the current object supports read operations. + ]]> The pipe is closed. @@ -1898,21 +1898,21 @@ The pipe handle has not been set. (Did your object. One of the values that indicates how the object reads from the pipe. - mode message transmission. + mode message transmission. To avoid an accessing `ReadMode`, can be used to verify the pipe is connected. - + ]]> The supplied value is not a valid value. The supplied value is not a supported value for this pipe stream. - The handle has not been set. - - -or- - + The handle has not been set. + + -or- + The pipe is waiting to connect with a named client. The pipe is broken or an I/O error occurred with a named client. @@ -2009,11 +2009,11 @@ The pipe handle has not been set. (Did your method is not supported in pipes and raises a when it is called. - + method is not supported in pipes and raises a when it is called. + ]]> @@ -2047,17 +2047,17 @@ The pipe handle has not been set. (Did your + A object that specifies an access control list (ACL) entry to apply to the current pipe. Applies the access control list (ACL) entries specified by a object to the pipe specified by the current object. - The pipe is closed. @@ -2109,11 +2109,11 @@ The pipe handle has not been set. (Did your The new length of the stream. Sets the length of the current stream to the specified value. - class does not support the method. - + class does not support the method. + ]]> @@ -2162,18 +2162,18 @@ The pipe handle has not been set. (Did your values that indicates the transmission mode supported by the current pipe. - mode message transmission. - + mode message transmission. + ]]> The pipe is closed. - The handle has not been set. - - -or- - + The handle has not been set. + + -or- + The pipe is waiting to connect in an anonymous client/server operation or with a named client. The pipe is broken or another I/O error occurred. @@ -2226,11 +2226,11 @@ The pipe handle has not been set. (Did your method blocks until the other end of the pipe has read all sent bytes. - + method blocks until the other end of the pipe has read all sent bytes. + ]]> The pipe is closed. @@ -2276,13 +2276,13 @@ The pipe handle has not been set. (Did your A region of memory. This method copies the contents of this region to the current stream. Writes a sequence of bytes to the current stream and advances the current position within this stream by the number of bytes written. - property to determine whether the current instance supports writing. Use the method to write asynchronously to the current stream. +Use the property to determine whether the current instance supports writing. Use the method to write asynchronously to the current stream. -If the write operation is successful, the position within the stream advances by the number of bytes written. If an exception occurs, the position within the stream remains unchanged. +If the write operation is successful, the position within the stream advances by the number of bytes written. If an exception occurs, the position within the stream remains unchanged. ]]> @@ -2352,22 +2352,22 @@ The pipe handle has not been set. (Did your The maximum number of bytes to write to the current stream. Writes a block of bytes to the current stream using data from a buffer. - property to determine whether the current object supports write operations. - - For asynchronous write operations, see and . - + property to determine whether the current object supports write operations. + + For asynchronous write operations, see and . + ]]> is . - is less than 0. - - -or- - + is less than 0. + + -or- + is less than 0. is greater than the number of bytes available in . @@ -2416,7 +2416,7 @@ The pipe handle has not been set. (Did your Asynchronously writes a specified number of bytes from a byte array starting at a specified position, advances the current position within this stream by the number of bytes written, and monitors cancellation requests. A task that represents the asynchronous write operation. - method enables you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in applications where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#. @@ -2572,11 +2572,11 @@ The pipe handle has not been set. (Did your The byte to write to the stream. Writes a byte to the current stream. - property to determine whether the current object supports write operations. - + property to determine whether the current object supports write operations. + ]]> The pipe is closed. diff --git a/xml/System.IO/Directory.xml b/xml/System.IO/Directory.xml index 360d2ae2536..0627b6713ac 100644 --- a/xml/System.IO/Directory.xml +++ b/xml/System.IO/Directory.xml @@ -360,8 +360,8 @@ Directory::CreateDirectory("c:\\Users\\User1\\Public\\Html"); System.IO.DirectoryInfo - - + + The directory to create. @@ -2009,7 +2009,7 @@ The returned collection is not cached. Each call to the System.Security.AccessControl.DirectorySecurity - + The path to a directory containing a object that describes the file's access control list (ACL) information. @@ -2077,8 +2077,8 @@ The returned collection is not cached. Each call to the System.Security.AccessControl.DirectorySecurity - - + + The path to a directory containing a object that describes the file's access control list (ACL) information. @@ -4383,8 +4383,8 @@ There are too many levels of symbolic links. System.Void - - + + A directory to add or remove access control list (ACL) entries from. diff --git a/xml/System.IO/DirectoryInfo.xml b/xml/System.IO/DirectoryInfo.xml index 8e6b7bdd4d9..7d38be32b8b 100644 --- a/xml/System.IO/DirectoryInfo.xml +++ b/xml/System.IO/DirectoryInfo.xml @@ -71,46 +71,46 @@ Exposes instance methods for creating, moving, and enumerating through directories and subdirectories. This class cannot be inherited. - class for typical operations such as copying, moving, renaming, creating, and deleting directories. - - If you are going to reuse an object several times, consider using the instance method of instead of the corresponding static methods of the class, because a security check will not always be necessary. - + class for typical operations such as copying, moving, renaming, creating, and deleting directories. + + If you are going to reuse an object several times, consider using the instance method of instead of the corresponding static methods of the class, because a security check will not always be necessary. + > [!NOTE] -> In members that accept a path as an input string, that path must be well-formed or an exception is raised. For example, if a path is fully qualified but begins with a space, the path is not trimmed in methods of the class. Therefore, the path is malformed and an exception is raised. Similarly, a path or a combination of paths cannot be fully qualified twice. For example, "c:\temp c:\windows" also raises an exception in most cases. Ensure that your paths are well-formed when using methods that accept a path string. - - In members that accept a path, the path can refer to a file or just a directory. The specified path can also refer to a relative path or a Universal Naming Convention (UNC) path for a server and share name. For example, all the following are acceptable paths: - -- "c:\\\MyDir\\\MyFile.txt" in C#, or "c:\MyDir\MyFile.txt" in Visual Basic. - -- "c:\\\MyDir" in C#, or "c:\MyDir" in Visual Basic. - -- "MyDir\\\MySubdir" in C#, or "MyDir\MySubDir" in Visual Basic. - -- "\\\\\\\MyServer\\\MyShare" in C#, or "\\\MyServer\MyShare" in Visual Basic. - - By default, full read/write access to new directories is granted to all users. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following example demonstrates some of the main members of the `DirectoryInfo` class. - +> In members that accept a path as an input string, that path must be well-formed or an exception is raised. For example, if a path is fully qualified but begins with a space, the path is not trimmed in methods of the class. Therefore, the path is malformed and an exception is raised. Similarly, a path or a combination of paths cannot be fully qualified twice. For example, "c:\temp c:\windows" also raises an exception in most cases. Ensure that your paths are well-formed when using methods that accept a path string. + + In members that accept a path, the path can refer to a file or just a directory. The specified path can also refer to a relative path or a Universal Naming Convention (UNC) path for a server and share name. For example, all the following are acceptable paths: + +- "c:\\\MyDir\\\MyFile.txt" in C#, or "c:\MyDir\MyFile.txt" in Visual Basic. + +- "c:\\\MyDir" in C#, or "c:\MyDir" in Visual Basic. + +- "MyDir\\\MySubdir" in C#, or "MyDir\MySubDir" in Visual Basic. + +- "\\\\\\\MyServer\\\MyShare" in C#, or "\\\MyServer\MyShare" in Visual Basic. + + By default, full read/write access to new directories is granted to all users. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following example demonstrates some of the main members of the `DirectoryInfo` class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/DirInfo Class Example/CPP/dirinfo class example.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.IO/DirectoryInfo/Overview/dirinfo class example.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/DirectoryInfo/Overview/dirinfo class example.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/DirInfo Class Example/VB/dirinfo class example.vb" id="Snippet1"::: - - The following example demonstrates how to copy a directory and its contents. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/DirInfo Class Example/VB/dirinfo class example.vb" id="Snippet1"::: + + The following example demonstrates how to copy a directory and its contents. + :::code language="csharp" source="~/snippets/csharp/System.IO/DirectoryInfo/Overview/copydir.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/DirectoryInfo/Overview/copydir.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/IO.DirectoryInfo-CopyDir/vb/CopyDir.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/IO.DirectoryInfo-CopyDir/vb/CopyDir.vb" id="Snippet1"::: + ]]> @@ -173,26 +173,26 @@ A string specifying the path on which to create the . Initializes a new instance of the class on the specified path. - [!CAUTION] -> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. - +> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - -## Examples - The following example uses this constructor to create the specified directory and subdirectory, and demonstrates that a directory that contains subdirectories cannot be deleted. - + +## Examples + The following example uses this constructor to create the specified directory and subdirectory, and demonstrates that a directory that contains subdirectories cannot be deleted. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/DirInfo Ctor/CPP/dirinfo ctor.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.IO/DirectoryInfo/.ctor/dirinfo ctor.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/DirectoryInfo/.ctor/dirinfo ctor.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/DirInfo Ctor/VB/dirinfo ctor.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/DirInfo Ctor/VB/dirinfo ctor.vb" id="Snippet1"::: + ]]> @@ -259,22 +259,22 @@ Creates a directory. - The directory cannot be created. @@ -309,21 +309,21 @@ System.Void - + The access control to apply to the directory. Creates a directory using a object. - [!IMPORTANT] > This method was ported to .NET Core 3.1 as an extension method of the `FileSystemAclExtensions` class as part of the `System.Security.AccessControl` assembly: . @@ -427,23 +427,23 @@ namespace ConsoleApp Creates a subdirectory or subdirectories on the specified path. The specified path can be relative to this instance of the class. The last directory specified in . - @@ -451,16 +451,16 @@ namespace ConsoleApp is . The specified path is invalid, such as being on an unmapped drive. - The subdirectory cannot be created. - - -or- - + The subdirectory cannot be created. + + -or- + A file already has the name specified by . The specified path, file name, or both exceed the system-defined maximum length. - The caller does not have code access permission to create the directory. - - -or- - + The caller does not have code access permission to create the directory. + + -or- + The caller does not have code access permission to read the directory described by the returned object. This can occur when the parameter describes an existing directory. contains a colon character (:) that is not part of a drive label ("C:\\"). @@ -501,8 +501,8 @@ namespace ConsoleApp System.IO.DirectoryInfo - - + + The specified path. This cannot be a different disk volume or Universal Naming Convention (UNC) name. @@ -510,13 +510,13 @@ namespace ConsoleApp Creates a subdirectory or subdirectories on the specified path with the specified security. The specified path can be relative to this instance of the class. The last directory specified in . - @@ -524,16 +524,16 @@ namespace ConsoleApp is . The specified path is invalid, such as being on an unmapped drive. - The subdirectory cannot be created. - - -or- - + The subdirectory cannot be created. + + -or- + A file or directory already has the name specified by . The specified path, file name, or both exceed the system-defined maximum length. - The caller does not have code access permission to create the directory. - - -or- - + The caller does not have code access permission to create the directory. + + -or- + The caller does not have code access permission to read the directory described by the returned object. This can occur when the parameter describes an existing directory. contains a colon character (:) that is not part of a drive label ("C:\\"). @@ -598,33 +598,33 @@ namespace ConsoleApp Deletes this if it is empty. - The directory contains a read-only file. The directory described by this object does not exist or could not be found. - The directory is not empty. - - -or- - - The directory is the application's current working directory. - - -or- - + The directory is not empty. + + -or- + + The directory is the application's current working directory. + + -or- + There is an open handle on the directory, and the operating system is Windows XP or earlier. This open handle can result from enumerating directories. For more information, see [How to: Enumerate Directories and Files](/dotnet/standard/io/how-to-enumerate-directories-and-files). The caller does not have the required permission. File and Stream I/O @@ -685,39 +685,39 @@ namespace ConsoleApp to delete this directory, its subdirectories, and all files; otherwise, . Deletes this instance of a , specifying whether to delete subdirectories and files. - . - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following example demonstrates deleting a directory. Because the directory is removed, first comment out the `Delete` line to test that the directory exists. Then uncomment the same line of code to test that the directory was removed successfully. - + . + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following example demonstrates deleting a directory. Because the directory is removed, first comment out the `Delete` line to test that the directory exists. Then uncomment the same line of code to test that the directory was removed successfully. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/directoryinfodelete/CPP/directoryinfodelete.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.IO/DirectoryInfo/Delete/directoryinfodelete.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/DirectoryInfo/Delete/directoryinfodelete.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/directoryinfodelete/VB/directoryinfodelete.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/directoryinfodelete/VB/directoryinfodelete.vb" id="Snippet1"::: + ]]> The directory contains a read-only file. The directory described by this object does not exist or could not be found. - The directory is read-only. - - -or- - - The directory contains one or more files or subdirectories and is . - - -or- - - The directory is the application's current working directory. - - -or- - + The directory is read-only. + + -or- + + The directory contains one or more files or subdirectories and is . + + -or- + + The directory is the application's current working directory. + + -or- + There is an open handle on the directory or on one of its files, and the operating system is Windows XP or earlier. This open handle can result from enumerating directories and files. For more information, see [How to: Enumerate Directories and Files](/dotnet/standard/io/how-to-enumerate-directories-and-files). The caller does not have the required permission. File and Stream I/O @@ -783,46 +783,46 @@ namespace ConsoleApp Returns an enumerable collection of directory information in the current directory. An enumerable collection of directories in the current directory. - and methods differ as follows: - -- When you use , you can start enumerating the collection of objects before the whole collection is returned. - -- When you use , you must wait for the whole array of objects to be returned before you can access the array. - - Therefore, when you are working with many files and directories, can be more efficient. - - This method pre-populates the values of the following properties: - -- - -- - -- - -- - -- - -- - -- - - The returned collection is not cached; each call to the method on the collection will start a new enumeration. - - - -## Examples - The following example enumerates the subdirectories under the C:\Program Files directory and uses a LINQ query to return the names of all directories that were created before 2009 by checking the value of the property. - - If you only need the names of the subdirectories, use the static class for better performance. For an example, see the method. - + and methods differ as follows: + +- When you use , you can start enumerating the collection of objects before the whole collection is returned. + +- When you use , you must wait for the whole array of objects to be returned before you can access the array. + + Therefore, when you are working with many files and directories, can be more efficient. + + This method pre-populates the values of the following properties: + +- + +- + +- + +- + +- + +- + +- + + The returned collection is not cached; each call to the method on the collection will start a new enumeration. + + + +## Examples + The following example enumerates the subdirectories under the C:\Program Files directory and uses a LINQ query to return the names of all directories that were created before 2009 by checking the value of the property. + + If you only need the names of the subdirectories, use the static class for better performance. For an example, see the method. + :::code language="csharp" source="~/snippets/csharp/System.IO/DirectoryInfo/EnumerateDirectories/program.cs"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/DirectoryInfo/EnumerateDirectories/program.fs"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.io.directoryinfo.enumdirs/vb/module1.vb"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.io.directoryinfo.enumdirs/vb/module1.vb"::: + ]]> The path encapsulated in the object is invalid (for example, it is on an unmapped drive). @@ -880,44 +880,44 @@ namespace ConsoleApp Returns an enumerable collection of directory information that matches a specified search pattern. An enumerable collection of directories that matches . - and methods differ as follows: - -- When you use , you can start enumerating the collection of objects before the whole collection is returned. - -- When you use , you must wait for the whole array of objects to be returned before you can access the array. - - Therefore, when you are working with many files and directories, can be more efficient. - - This method pre-populates the values of the following properties: - -- - -- - -- - -- - -- - -- - -- - - The returned collection is not cached; each call to the method on the collection will start a new enumeration. - + and methods differ as follows: + +- When you use , you can start enumerating the collection of objects before the whole collection is returned. + +- When you use , you must wait for the whole array of objects to be returned before you can access the array. + + Therefore, when you are working with many files and directories, can be more efficient. + + This method pre-populates the values of the following properties: + +- + +- + +- + +- + +- + +- + +- + + The returned collection is not cached; each call to the method on the collection will start a new enumeration. + ]]> @@ -967,44 +967,44 @@ namespace ConsoleApp Returns an enumerable collection of directory information that matches the specified search pattern and enumeration options. An enumerable collection of directories that matches and . - and methods differ as follows: - -- When you use , you can start enumerating the collection of objects before the whole collection is returned. - -- When you use , you must wait for the whole array of objects to be returned before you can access the array. - - Therefore, when you are working with many files and directories, can be more efficient. - - This method pre-populates the values of the following properties: - -- - -- - -- - -- - -- - -- - -- - - The returned collection is not cached; each call to the method on the collection will start a new enumeration. - + and methods differ as follows: + +- When you use , you can start enumerating the collection of objects before the whole collection is returned. + +- When you use , you must wait for the whole array of objects to be returned before you can access the array. + + Therefore, when you are working with many files and directories, can be more efficient. + + This method pre-populates the values of the following properties: + +- + +- + +- + +- + +- + +- + +- + + The returned collection is not cached; each call to the method on the collection will start a new enumeration. + ]]> @@ -1066,53 +1066,53 @@ namespace ConsoleApp Returns an enumerable collection of directory information that matches a specified search pattern and search subdirectory option. An enumerable collection of directories that matches and . - and methods differ as follows: - -- When you use , you can start enumerating the collection of objects before the whole collection is returned. - -- When you use , you must wait for the whole array of objects to be returned before you can access the array. - - Therefore, when you are working with many files and directories, can be more efficient. - - This method pre-populates the values of the following properties: - -- - -- - -- - -- - -- - -- - -- - - The returned collection is not cached; each call to the method on the collection will start a new enumeration. - - - -## Examples - The following example uses this method and the method to enumerate the files and directories within the start directory and display the name and size of any files over 10 MB. - + and methods differ as follows: + +- When you use , you can start enumerating the collection of objects before the whole collection is returned. + +- When you use , you must wait for the whole array of objects to be returned before you can access the array. + + Therefore, when you are working with many files and directories, can be more efficient. + + This method pre-populates the values of the following properties: + +- + +- + +- + +- + +- + +- + +- + + The returned collection is not cached; each call to the method on the collection will start a new enumeration. + + + +## Examples + The following example uses this method and the method to enumerate the files and directories within the start directory and display the name and size of any files over 10 MB. + :::code language="csharp" source="~/snippets/csharp/System.IO/DirectoryInfo/EnumerateDirectories/program1.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/DirectoryInfo/EnumerateDirectories/program1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.io.directoryinfo.enumeratedirectories/vb/program.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.io.directoryinfo.enumeratedirectories/vb/program.vb" id="Snippet1"::: + ]]> @@ -1181,54 +1181,54 @@ namespace ConsoleApp Returns an enumerable collection of file information in the current directory. An enumerable collection of the files in the current directory. - and methods differ as follows: - -- When you use , you can start enumerating the collection of objects before the whole collection is returned. - -- When you use , you must wait for the whole array of objects to be returned before you can access the array. - - Therefore, when you are working with many files and directories, can be more efficient. - - This method pre-populates the values of the following properties: - -- - -- - -- - -- - -- - -- - -- - -- - - The returned collection is not cached; each call to the method on the collection will start a new enumeration. - - - -## Examples - The following example enumerates the files under a specified directory and uses a LINQ query to return the names of all files that were created before 2009 by checking the value of the property. - - If you only need the names of the files, use the static class for better performance. For an example, see the method. - + and methods differ as follows: + +- When you use , you can start enumerating the collection of objects before the whole collection is returned. + +- When you use , you must wait for the whole array of objects to be returned before you can access the array. + + Therefore, when you are working with many files and directories, can be more efficient. + + This method pre-populates the values of the following properties: + +- + +- + +- + +- + +- + +- + +- + +- + + The returned collection is not cached; each call to the method on the collection will start a new enumeration. + + + +## Examples + The following example enumerates the files under a specified directory and uses a LINQ query to return the names of all files that were created before 2009 by checking the value of the property. + + If you only need the names of the files, use the static class for better performance. For an example, see the method. + :::code language="csharp" source="~/snippets/csharp/System.IO/DirectoryInfo/EnumerateFiles/program.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/DirectoryInfo/EnumerateFiles/program.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.io.directoryinfo.enumfiles/vb/module1.vb" id="Snippet1"::: - - The following example shows how to enumerate files in a directory by using different search options. The example assumes a directory that has files named log1.txt, log2.txt, test1.txt, test2.txt, test3.txt, and a subdirectory that has a file named SubFile.txt. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.io.directoryinfo.enumfiles/vb/module1.vb" id="Snippet1"::: + + The following example shows how to enumerate files in a directory by using different search options. The example assumes a directory that has files named log1.txt, log2.txt, test1.txt, test2.txt, test3.txt, and a subdirectory that has a file named SubFile.txt. + :::code language="csharp" source="~/snippets/csharp/System.IO/DirectoryInfo/EnumerateFiles/program2.cs" id="Snippet2"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/DirectoryInfo/EnumerateFiles/program2.fs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.io.directoryinfo.enumfiles/vb/module2.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.io.directoryinfo.enumfiles/vb/module2.vb" id="Snippet2"::: + ]]> The path encapsulated in the object is invalid (for example, it is on an unmapped drive). @@ -1286,55 +1286,55 @@ namespace ConsoleApp Returns an enumerable collection of file information that matches a search pattern. An enumerable collection of files that matches . - and methods differ as follows: - -- When you use , you can start enumerating the collection of objects before the whole collection is returned. - -- When you use , you must wait for the whole array of objects to be returned before you can access the array. - - Therefore, when you are working with many files and directories, can be more efficient. - - This method pre-populates the values of the following properties: - -- - -- - -- - -- - -- - -- - -- - -- - - The returned collection is not cached; each call to the method on the collection will start a new enumeration. - - - -## Examples - The following example shows how to enumerate files in a directory by using different search options. The example assumes a directory that has files named log1.txt, log2.txt, test1.txt, test2.txt, test3.txt, and a subdirectory that has a file named SubFile.txt. - + and methods differ as follows: + +- When you use , you can start enumerating the collection of objects before the whole collection is returned. + +- When you use , you must wait for the whole array of objects to be returned before you can access the array. + + Therefore, when you are working with many files and directories, can be more efficient. + + This method pre-populates the values of the following properties: + +- + +- + +- + +- + +- + +- + +- + +- + + The returned collection is not cached; each call to the method on the collection will start a new enumeration. + + + +## Examples + The following example shows how to enumerate files in a directory by using different search options. The example assumes a directory that has files named log1.txt, log2.txt, test1.txt, test2.txt, test3.txt, and a subdirectory that has a file named SubFile.txt. + :::code language="csharp" source="~/snippets/csharp/System.IO/DirectoryInfo/EnumerateFiles/program2.cs" id="Snippet2"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/DirectoryInfo/EnumerateFiles/program2.fs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.io.directoryinfo.enumfiles/vb/module2.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.io.directoryinfo.enumfiles/vb/module2.vb" id="Snippet2"::: + ]]> @@ -1384,60 +1384,60 @@ namespace ConsoleApp Returns an enumerable collection of file information that matches the specified search pattern and enumeration options. An enumerable collection of files that matches and . - and methods differ as follows: - -- When you use , you can start enumerating the collection of objects before the whole collection is returned. - -- When you use , you must wait for the whole array of objects to be returned before you can access the array. - - Therefore, when you are working with many files and directories, can be more efficient. - - This method pre-populates the values of the following properties: - -- - -- - -- - -- - -- - -- - -- - -- - - The returned collection is not cached; each call to the method on the collection will start a new enumeration. + - - - is . - The path encapsulated in the object is invalid, (for example, it is on an unmapped drive). - The caller does not have the required permission. - - - - - - - - +## Remarks + `searchPattern` can be a combination of literal and wildcard characters, but it doesn't support regular expressions. The following wildcard specifiers are permitted in `searchPattern`. + +|Wildcard specifier|Matches| +|------------------------|-------------| +|\* (asterisk)|Zero or more characters in that position.| +|? (question mark)|Zero or one character in that position.| + + Characters other than the wildcard are literal characters. For example, the string "\*t" searches for all names in ending with the letter "t". ". The `searchPattern` string "s\*" searches for all names in `path` beginning with the letter "s". + + The and methods differ as follows: + +- When you use , you can start enumerating the collection of objects before the whole collection is returned. + +- When you use , you must wait for the whole array of objects to be returned before you can access the array. + + Therefore, when you are working with many files and directories, can be more efficient. + + This method pre-populates the values of the following properties: + +- + +- + +- + +- + +- + +- + +- + +- + + The returned collection is not cached; each call to the method on the collection will start a new enumeration. + + ]]> + + + is . + The path encapsulated in the object is invalid, (for example, it is on an unmapped drive). + The caller does not have the required permission. + + + + + + + + Method @@ -1485,55 +1485,55 @@ namespace ConsoleApp Returns an enumerable collection of file information that matches a specified search pattern and search subdirectory option. An enumerable collection of files that matches and . - and methods differ as follows: - -- When you use , you can start enumerating the collection of objects before the whole collection is returned. - -- When you use , you must wait for the whole array of objects to be returned before you can access the array. - - Therefore, when you are working with many files and directories, can be more efficient. - - This method pre-populates the values of the following properties: - -- - -- - -- - -- - -- - -- - -- - -- - - The returned collection is not cached; each call to the method on the collection will start a new enumeration. - - - -## Examples - The following example shows how to enumerate files in a directory by using different search options. The example assumes a directory that has files named log1.txt, log2.txt, test1.txt, test2.txt, test3.txt, and a subdirectory that has a file named SubFile.txt. - + and methods differ as follows: + +- When you use , you can start enumerating the collection of objects before the whole collection is returned. + +- When you use , you must wait for the whole array of objects to be returned before you can access the array. + + Therefore, when you are working with many files and directories, can be more efficient. + + This method pre-populates the values of the following properties: + +- + +- + +- + +- + +- + +- + +- + +- + + The returned collection is not cached; each call to the method on the collection will start a new enumeration. + + + +## Examples + The following example shows how to enumerate files in a directory by using different search options. The example assumes a directory that has files named log1.txt, log2.txt, test1.txt, test2.txt, test3.txt, and a subdirectory that has a file named SubFile.txt. + :::code language="csharp" source="~/snippets/csharp/System.IO/DirectoryInfo/EnumerateFiles/program2.cs" id="Snippet2"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/DirectoryInfo/EnumerateFiles/program2.fs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.io.directoryinfo.enumfiles/vb/module2.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.io.directoryinfo.enumfiles/vb/module2.vb" id="Snippet2"::: + ]]> @@ -1602,35 +1602,35 @@ namespace ConsoleApp Returns an enumerable collection of file system information in the current directory. An enumerable collection of file system information in the current directory. - and methods differ as follows: - -- When you use , you can start enumerating the collection of objects before the whole collection is returned. - -- When you use , you must wait for the whole array of objects to be returned before you can access the array. - - Therefore, when you are working with many files and directories, can be more efficient. - - This method pre-populates the values of the following properties: - -- - -- - -- - -- - -- - -- - -- - - The returned collection is not cached; each call to the method on the collection will start a new enumeration. - + and methods differ as follows: + +- When you use , you can start enumerating the collection of objects before the whole collection is returned. + +- When you use , you must wait for the whole array of objects to be returned before you can access the array. + + Therefore, when you are working with many files and directories, can be more efficient. + + This method pre-populates the values of the following properties: + +- + +- + +- + +- + +- + +- + +- + + The returned collection is not cached; each call to the method on the collection will start a new enumeration. + ]]> The path encapsulated in the object is invalid (for example, it is on an unmapped drive). @@ -1689,44 +1689,44 @@ namespace ConsoleApp Returns an enumerable collection of file system information that matches a specified search pattern. An enumerable collection of file system information objects that matches . - and methods differ as follows: - -- When you use , you can start enumerating the collection of objects before the whole collection is returned. - -- When you use , you must wait for the whole array of objects to be returned before you can access the array. - - Therefore, when you are working with many files and directories, can be more efficient. - - This method pre-populates the values of the following properties: - -- - -- - -- - -- - -- - -- - -- - - The returned collection is not cached; each call to the method on the collection will start a new enumeration. - + and methods differ as follows: + +- When you use , you can start enumerating the collection of objects before the whole collection is returned. + +- When you use , you must wait for the whole array of objects to be returned before you can access the array. + + Therefore, when you are working with many files and directories, can be more efficient. + + This method pre-populates the values of the following properties: + +- + +- + +- + +- + +- + +- + +- + + The returned collection is not cached; each call to the method on the collection will start a new enumeration. + ]]> @@ -1777,44 +1777,44 @@ namespace ConsoleApp Returns an enumerable collection of file system information that matches the specified search pattern and enumeration options. An enumerable collection of file system information objects that matches and . - and methods differ as follows: - -- When you use , you can start enumerating the collection of objects before the whole collection is returned. - -- When you use , you must wait for the whole array of objects to be returned before you can access the array. - - Therefore, when you are working with many files and directories, can be more efficient. - - This method pre-populates the values of the following properties: - -- - -- - -- - -- - -- - -- - -- - - The returned collection is not cached; each call to the method on the collection will start a new enumeration. - + and methods differ as follows: + +- When you use , you can start enumerating the collection of objects before the whole collection is returned. + +- When you use , you must wait for the whole array of objects to be returned before you can access the array. + + Therefore, when you are working with many files and directories, can be more efficient. + + This method pre-populates the values of the following properties: + +- + +- + +- + +- + +- + +- + +- + + The returned collection is not cached; each call to the method on the collection will start a new enumeration. + ]]> @@ -1876,44 +1876,44 @@ namespace ConsoleApp Returns an enumerable collection of file system information that matches a specified search pattern and search subdirectory option. An enumerable collection of file system information objects that matches and . - and methods differ as follows: - -- When you use , you can start enumerating the collection of objects before the whole collection is returned. - -- When you use , you must wait for the whole array of objects to be returned before you can access the array. - - Therefore, when you are working with many files and directories, can be more efficient. - - This method pre-populates the values of the following properties: - -- - -- - -- - -- - -- - -- - -- - - The returned collection is not cached; each call to the method on the collection will start a new enumeration. - + and methods differ as follows: + +- When you use , you can start enumerating the collection of objects before the whole collection is returned. + +- When you use , you must wait for the whole array of objects to be returned before you can access the array. + + Therefore, when you are working with many files and directories, can be more efficient. + + This method pre-populates the values of the following properties: + +- + +- + +- + +- + +- + +- + +- + + The returned collection is not cached; each call to the method on the collection will start a new enumeration. + ]]> @@ -1975,21 +1975,21 @@ namespace ConsoleApp if the directory exists; otherwise, . - property returns `false` if any error occurs while trying to determine if the specified file exists. This can occur in situations that raise exceptions such as passing a file name with invalid characters or too many characters, a failing or missing disk, or if the caller does not have permission to read the file. - - - -## Examples - The following example demonstrates a use of the `Exists` property in the context of copying a source directory to a target directory. - + property returns `false` if any error occurs while trying to determine if the specified file exists. This can occur in situations that raise exceptions such as passing a file name with invalid characters or too many characters, a failing or missing disk, or if the caller does not have permission to read the file. + + + +## Examples + The following example demonstrates a use of the `Exists` property in the context of copying a source directory to a target directory. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/DirectoryInfo Usage Example/CPP/copydirectory.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.IO/DirectoryInfo/Exists/copydirectory.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/DirectoryInfo/Exists/copydirectory.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/DirectoryInfo Usage Example/VB/copydirectory.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/DirectoryInfo Usage Example/VB/copydirectory.vb" id="Snippet1"::: + ]]> File and Stream I/O @@ -2042,13 +2042,13 @@ namespace ConsoleApp Gets the access control list (ACL) entries for the current directory. - methods to retrieve the access control list (ACL) entries for the current file. - - For more information, see [How to: Add or Remove Access Control List Entries](/dotnet/standard/io/how-to-add-or-remove-access-control-list-entries). - + methods to retrieve the access control list (ACL) entries for the current file. + + For more information, see [How to: Add or Remove Access Control List Entries](/dotnet/standard/io/how-to-add-or-remove-access-control-list-entries). + ]]> @@ -2083,34 +2083,34 @@ namespace ConsoleApp Gets a object that encapsulates the access control list (ACL) entries for the directory described by the current object. A object that encapsulates the access control rules for the directory. - method overload and specifying the access control sections | | ( `Or` `Or` in Visual Basic). - - Use the method to retrieve the access control list (ACL) entries for the current file. - + method overload and specifying the access control sections | | ( `Or` `Or` in Visual Basic). + + Use the method to retrieve the access control list (ACL) entries for the current file. + An ACL describes individuals and/or groups who have, or do not have, rights to specific actions on the given file or directory. For more information, see [How to: Add or Remove Access Control List Entries](/dotnet/standard/io/how-to-add-or-remove-access-control-list-entries). - -## Examples - The following example uses the and methods to add and then remove an access control list (ACL) entry from a directory. - + +## Examples + The following example uses the and methods to add and then remove an access control list (ACL) entry from a directory. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/IO.DiretoryInfo.GetAccessControl-SetAccessControl/cpp/sample.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.IO/Directory/GetAccessControl/sample.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/Directory/GetAccessControl/sample.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/IO.DiretoryInfo.GetAccessControl-SetAccessControl/VB/sample.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/IO.DiretoryInfo.GetAccessControl-SetAccessControl/VB/sample.vb" id="Snippet1"::: + ]]> The directory could not be found or modified. - The directory is read-only. - - -or- - - This operation is not supported on the current platform. - - -or- - + The directory is read-only. + + -or- + + This operation is not supported on the current platform. + + -or- + The caller does not have the required permission. An I/O error occurred while opening the directory. @@ -2141,20 +2141,20 @@ namespace ConsoleApp System.Security.AccessControl.DirectorySecurity - + One of the values that specifies the type of access control list (ACL) information to receive. Gets a object that encapsulates the specified type of access control list (ACL) entries for the directory described by the current object. A object that encapsulates the access control rules for the file described by the parameter. - method to retrieve the access control list (ACL) entries for the current file. - - An ACL describes individuals and/or groups who have, or do not have, rights to specific actions on the given file or directory. For more information, see [How to: Add or Remove Access Control List Entries](/dotnet/standard/io/how-to-add-or-remove-access-control-list-entries). - + method to retrieve the access control list (ACL) entries for the current file. + + An ACL describes individuals and/or groups who have, or do not have, rights to specific actions on the given file or directory. For more information, see [How to: Add or Remove Access Control List Entries](/dotnet/standard/io/how-to-add-or-remove-access-control-list-entries). + ]]> The directory could not be found or modified. @@ -2223,37 +2223,37 @@ namespace ConsoleApp Returns the subdirectories of the current directory. An array of objects. - properties: - -- - -- - -- - -- - -- - -- - -- - - - -## Examples - The following example retrieves all the directories in the root directory and displays the directory names. - + properties: + +- + +- + +- + +- + +- + +- + +- + + + +## Examples + The following example retrieves all the directories in the root directory and displays the directory names. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/directoryinfogetdirectories/CPP/directoryinfogetdirectories.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.IO/DirectoryInfo/GetDirectories/directoryinfogetdirectories.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/DirectoryInfo/GetDirectories/directoryinfogetdirectories.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/directoryinfogetdirectories/VB/directoryinfogetdirectories.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/directoryinfogetdirectories/VB/directoryinfogetdirectories.vb" id="Snippet1"::: + ]]> The path encapsulated in the object is invalid, such as being on an unmapped drive. @@ -2317,42 +2317,42 @@ namespace ConsoleApp Returns an array of directories in the current matching the given search criteria. An array of type matching . - properties: - -- - -- - -- - -- - -- - -- - + properties: + +- + +- + +- + +- + +- + +- + - - -## Examples - The following example counts the directories in a path that contain the specified letter. - + +## Examples + The following example counts the directories in a path that contain the specified letter. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/DirInfo GetDirs2/CPP/dirinfo getdirs2.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.IO/DirectoryInfo/GetDirectories/dirinfo getdirs2.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/DirectoryInfo/GetDirectories/dirinfo getdirs2.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/DirInfo GetDirs2/VB/dirinfo getdirs2.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/DirInfo GetDirs2/VB/dirinfo getdirs2.vb" id="Snippet1"::: + ]]> .NET Framework and .NET Core versions older than 2.1: contains one or more invalid characters defined by the method. @@ -2406,33 +2406,33 @@ namespace ConsoleApp Returns an array of directories in the current matching the specified search pattern and enumeration options. An array of type matching and . - properties: - -- - -- - -- - -- - -- - -- - -- + properties: + +- + +- + +- + +- + +- + +- + +- ]]> @@ -2497,46 +2497,46 @@ namespace ConsoleApp Returns an array of directories in the current matching the given search criteria and using a value to determine whether to search subdirectories. An array of type matching . - properties: - -- - -- - -- - -- - -- - -- - -- - - - -## Examples - The following example lists all of the directories and files that begin with the letter "c" in "c:\\". - + properties: + +- + +- + +- + +- + +- + +- + +- + + + +## Examples + The following example lists all of the directories and files that begin with the letter "c" in "c:\\". + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.DirectoryInfo_SearchOptions/cpp/searchoption.cpp" id="Snippet00"::: :::code language="csharp" source="~/snippets/csharp/System.IO/DirectoryInfo/GetDirectories/searchoption.cs" id="Snippet00"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/DirectoryInfo/GetDirectories/searchoption.fs" id="Snippet00"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.DirectoryInfo_SearchOptions/vb/searchoption.vb" id="Snippet00"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.DirectoryInfo_SearchOptions/vb/searchoption.vb" id="Snippet00"::: + ]]> .NET Framework and .NET Core versions older than 2.1: contains one or more invalid characters defined by the method. @@ -2611,48 +2611,48 @@ namespace ConsoleApp Returns a file list from the current directory. An array of type . - and methods differ as follows: - -- When you use , you can start enumerating the collection of objects before the whole collection is returned. - -- When you use , you must wait for the whole array of objects to be returned before you can access the array. - - Therefore, when you are working with many files and directories, can be more efficient. - - If there are no files in the , this method returns an empty array. - - The order of the returned file names is not guaranteed; use the method if a specific sort order is required. - - This method pre-populates the values of the following properties: - -- - -- - -- - -- - -- - -- - -- - -- - - - -## Examples - The following example shows how to get a list of files from a directory by using different search options. The example assumes a directory that has files named log1.txt, log2.txt, test1.txt, test2.txt, test3.txt, and a subdirectory that has a file named SubFile.txt. - + and methods differ as follows: + +- When you use , you can start enumerating the collection of objects before the whole collection is returned. + +- When you use , you must wait for the whole array of objects to be returned before you can access the array. + + Therefore, when you are working with many files and directories, can be more efficient. + + If there are no files in the , this method returns an empty array. + + The order of the returned file names is not guaranteed; use the method if a specific sort order is required. + + This method pre-populates the values of the following properties: + +- + +- + +- + +- + +- + +- + +- + +- + + + +## Examples + The following example shows how to get a list of files from a directory by using different search options. The example assumes a directory that has files named log1.txt, log2.txt, test1.txt, test2.txt, test3.txt, and a subdirectory that has a file named SubFile.txt. + :::code language="csharp" source="~/snippets/csharp/System.IO/DirectoryInfo/GetFiles/directoryinfogetfiles2.cs" id="Snippet2"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/DirectoryInfo/GetFiles/directoryinfogetfiles2.fs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/directoryinfogetfiles/VB/directoryinfogetfiles2.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/directoryinfogetfiles/VB/directoryinfogetfiles2.vb" id="Snippet2"::: + ]]> The path is invalid, such as being on an unmapped drive. @@ -2714,72 +2714,72 @@ namespace ConsoleApp Returns a file list from the current directory matching the given search pattern. An array of type . - and methods differ as follows: - -- When you use , you can start enumerating the collection of objects before the whole collection is returned. - -- When you use , you must wait for the whole array of objects to be returned before you can access the array. - - Therefore, when you are working with many files and directories, can be more efficient. - - If there are no files in the , this method returns an empty array. - - The following wildcard specifiers are permitted in the `searchPattern` parameter. - -|Wildcard character|Description| -|------------------------|-----------------| -|*|Zero or more characters.| -|?|Exactly zero or one character.| - - The order of the returned file names is not guaranteed; use the method if a specific sort order is required. - - Wildcards are permitted. For example, the `searchPattern` string "*.txt" searches for all file names having an extension of "txt". The `searchPattern` string "s\*" searches for all file names beginning with the letter "s". If there are no files, or no files that match the `searchPattern` string in the , this method returns an empty array. - + and methods differ as follows: + +- When you use , you can start enumerating the collection of objects before the whole collection is returned. + +- When you use , you must wait for the whole array of objects to be returned before you can access the array. + + Therefore, when you are working with many files and directories, can be more efficient. + + If there are no files in the , this method returns an empty array. + + The following wildcard specifiers are permitted in the `searchPattern` parameter. + +|Wildcard character|Description| +|------------------------|-----------------| +|*|Zero or more characters.| +|?|Exactly zero or one character.| + + The order of the returned file names is not guaranteed; use the method if a specific sort order is required. + + Wildcards are permitted. For example, the `searchPattern` string "*.txt" searches for all file names having an extension of "txt". The `searchPattern` string "s\*" searches for all file names beginning with the letter "s". If there are no files, or no files that match the `searchPattern` string in the , this method returns an empty array. + > [!NOTE] -> When using the asterisk wildcard character in a `searchPattern` (for example, "*.txt"), the matching behavior varies depending on the length of the specified file extension. A `searchPattern` with a file extension of exactly three characters returns files with an extension of three or more characters, where the first three characters match the file extension specified in the `searchPattern`. A `searchPattern` with a file extension of one, two, or more than three characters returns only files with extensions of exactly that length that match the file extension specified in the `searchPattern`. When using the question mark wildcard character, this method returns only files that match the specified file extension. For example, given two files in a directory, "file1.txt" and "file1.txtother", a search pattern of "file?.txt" returns only the first file, while a search pattern of "file\*.txt" returns both files. - +> When using the asterisk wildcard character in a `searchPattern` (for example, "*.txt"), the matching behavior varies depending on the length of the specified file extension. A `searchPattern` with a file extension of exactly three characters returns files with an extension of three or more characters, where the first three characters match the file extension specified in the `searchPattern`. A `searchPattern` with a file extension of one, two, or more than three characters returns only files with extensions of exactly that length that match the file extension specified in the `searchPattern`. When using the question mark wildcard character, this method returns only files that match the specified file extension. For example, given two files in a directory, "file1.txt" and "file1.txtother", a search pattern of "file?.txt" returns only the first file, while a search pattern of "file\*.txt" returns both files. + > [!NOTE] -> Because this method checks against file names with both the 8.3 file name format and the long file name format, a search pattern similar to "*1\*.txt" may return unexpected file names. For example, using a search pattern of "\*1\*.txt" will return "longfilename.txt" because the equivalent 8.3 file name format would be "longf~1.txt". - - This method pre-populates the values of the following properties: - -- - -- - -- - -- - -- - -- - -- - -- - - - -## Examples - The following example shows how to get a list of files from a directory by using different search options. The example assumes a directory that has files named log1.txt, log2.txt, test1.txt, test2.txt, test3.txt, and a subdirectory that has a file named SubFile.txt. - +> Because this method checks against file names with both the 8.3 file name format and the long file name format, a search pattern similar to "*1\*.txt" may return unexpected file names. For example, using a search pattern of "\*1\*.txt" will return "longfilename.txt" because the equivalent 8.3 file name format would be "longf~1.txt". + + This method pre-populates the values of the following properties: + +- + +- + +- + +- + +- + +- + +- + +- + + + +## Examples + The following example shows how to get a list of files from a directory by using different search options. The example assumes a directory that has files named log1.txt, log2.txt, test1.txt, test2.txt, test3.txt, and a subdirectory that has a file named SubFile.txt. + :::code language="csharp" source="~/snippets/csharp/System.IO/DirectoryInfo/GetFiles/directoryinfogetfiles2.cs" id="Snippet2"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/DirectoryInfo/GetFiles/directoryinfogetfiles2.fs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/directoryinfogetfiles/VB/directoryinfogetfiles2.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/directoryinfogetfiles/VB/directoryinfogetfiles2.vb" id="Snippet2"::: + ]]> .NET Framework and .NET Core versions older than 2.1: contains one or more invalid characters defined by the method. @@ -2833,62 +2833,62 @@ namespace ConsoleApp Returns a file list from the current directory matching the specified search pattern and enumeration options. An array of strongly typed objects that match and . - and methods differ as follows: - -- When you use , you can start enumerating the collection of objects before the whole collection is returned. - -- When you use , you must wait for the whole array of objects to be returned before you can access the array. - - Therefore, when you are working with many files and directories, can be more efficient. - - If there are no files in the , this method returns an empty array. - - The following wildcard specifiers are permitted in the `searchPattern` parameter. - -|Wildcard character|Description| -|------------------------|-----------------| -|*|Zero or more characters.| -|?|Exactly zero or one character.| - - The order of the returned file names is not guaranteed; use the method if a specific sort order is required. - - Wildcards are permitted. For example, the `searchPattern` string "*.txt" searches for all file names having an extension of "txt". The `searchPattern` string "s\*" searches for all file names beginning with the letter "s". If there are no files, or no files that match the `searchPattern` string in the , this method returns an empty array. - + and methods differ as follows: + +- When you use , you can start enumerating the collection of objects before the whole collection is returned. + +- When you use , you must wait for the whole array of objects to be returned before you can access the array. + + Therefore, when you are working with many files and directories, can be more efficient. + + If there are no files in the , this method returns an empty array. + + The following wildcard specifiers are permitted in the `searchPattern` parameter. + +|Wildcard character|Description| +|------------------------|-----------------| +|*|Zero or more characters.| +|?|Exactly zero or one character.| + + The order of the returned file names is not guaranteed; use the method if a specific sort order is required. + + Wildcards are permitted. For example, the `searchPattern` string "*.txt" searches for all file names having an extension of "txt". The `searchPattern` string "s\*" searches for all file names beginning with the letter "s". If there are no files, or no files that match the `searchPattern` string in the , this method returns an empty array. + > [!NOTE] -> When using the asterisk wildcard character in a `searchPattern` (for example, "*.txt"), the matching behavior varies depending on the length of the specified file extension. A `searchPattern` with a file extension of exactly three characters returns files with an extension of three or more characters, where the first three characters match the file extension specified in the `searchPattern`. A `searchPattern` with a file extension of one, two, or more than three characters returns only files with extensions of exactly that length that match the file extension specified in the `searchPattern`. When using the question mark wildcard character, this method returns only files that match the specified file extension. For example, given two files in a directory, "file1.txt" and "file1.txtother", a search pattern of "file?.txt" returns only the first file, while a search pattern of "file\*.txt" returns both files. - +> When using the asterisk wildcard character in a `searchPattern` (for example, "*.txt"), the matching behavior varies depending on the length of the specified file extension. A `searchPattern` with a file extension of exactly three characters returns files with an extension of three or more characters, where the first three characters match the file extension specified in the `searchPattern`. A `searchPattern` with a file extension of one, two, or more than three characters returns only files with extensions of exactly that length that match the file extension specified in the `searchPattern`. When using the question mark wildcard character, this method returns only files that match the specified file extension. For example, given two files in a directory, "file1.txt" and "file1.txtother", a search pattern of "file?.txt" returns only the first file, while a search pattern of "file\*.txt" returns both files. + > [!NOTE] -> Because this method checks against file names with both the 8.3 file name format and the long file name format, a search pattern similar to "*1\*.txt" may return unexpected file names. For example, using a search pattern of "\*1\*.txt" will return "longfilename.txt" because the equivalent 8.3 file name format would be "longf~1.txt". - - This method pre-populates the values of the following properties: - -- - -- - -- - -- - -- - -- - -- - -- +> Because this method checks against file names with both the 8.3 file name format and the long file name format, a search pattern similar to "*1\*.txt" may return unexpected file names. For example, using a search pattern of "\*1\*.txt" will return "longfilename.txt" because the equivalent 8.3 file name format would be "longf~1.txt". + + This method pre-populates the values of the following properties: + +- + +- + +- + +- + +- + +- + +- + +- ]]> @@ -2953,73 +2953,73 @@ namespace ConsoleApp Returns a file list from the current directory matching the given search pattern and using a value to determine whether to search subdirectories. An array of type . - and methods differ as follows: - -- When you use , you can start enumerating the collection of objects before the whole collection is returned. - -- When you use , you must wait for the whole array of objects to be returned before you can access the array. - - Therefore, when you are working with many files and directories, can be more efficient. - - If there are no files in the , this method returns an empty array. - - The following wildcard specifiers are permitted in `searchPattern`. - -|Wildcard character|Description| -|------------------------|-----------------| -|\* (asterisk)|Zero or more characters.| -|? (question mark)|Exactly zero or one character.| - - The order of the returned file names is not guaranteed; use the method if a specific sort order is required. - - Wildcards are permitted. For example, the `searchPattern` string "*.txt" searches for all file names having an extension of "txt". The `searchPattern` string "s\*" searches for all file names beginning with the letter "s". If there are no files, or no files that match the `searchPattern` string in the , this method returns an empty array. - + and methods differ as follows: + +- When you use , you can start enumerating the collection of objects before the whole collection is returned. + +- When you use , you must wait for the whole array of objects to be returned before you can access the array. + + Therefore, when you are working with many files and directories, can be more efficient. + + If there are no files in the , this method returns an empty array. + + The following wildcard specifiers are permitted in `searchPattern`. + +|Wildcard character|Description| +|------------------------|-----------------| +|\* (asterisk)|Zero or more characters.| +|? (question mark)|Exactly zero or one character.| + + The order of the returned file names is not guaranteed; use the method if a specific sort order is required. + + Wildcards are permitted. For example, the `searchPattern` string "*.txt" searches for all file names having an extension of "txt". The `searchPattern` string "s\*" searches for all file names beginning with the letter "s". If there are no files, or no files that match the `searchPattern` string in the , this method returns an empty array. + > [!NOTE] -> When using the asterisk wildcard character in a `searchPattern` (for example, "*.txt"), the matching behavior varies depending on the length of the specified file extension. A `searchPattern` with a file extension of exactly three characters returns files with an extension of three or more characters, where the first three characters match the file extension specified in the `searchPattern`. A `searchPattern` with a file extension of one, two, or more than three characters returns only files with extensions of exactly that length that match the file extension specified in the `searchPattern`. When using the question mark wildcard character, this method returns only files that match the specified file extension. For example, given two files in a directory, "file1.txt" and "file1.txtother", a search pattern of "file?.txt" returns only the first file, while a search pattern of "file\*.txt" returns both files. - - The following list shows the behavior of different lengths for the `searchPattern` parameter: - -- "*.abc" returns files having an extension of .abc, .abcd, .abcde, .abcdef, and so on. - -- "*.abcd" returns only files having an extension of .abcd. - -- "*.abcde" returns only files having an extension of .abcde. - -- "*.abcdef" returns only files having an extension of .abcdef. - +> When using the asterisk wildcard character in a `searchPattern` (for example, "*.txt"), the matching behavior varies depending on the length of the specified file extension. A `searchPattern` with a file extension of exactly three characters returns files with an extension of three or more characters, where the first three characters match the file extension specified in the `searchPattern`. A `searchPattern` with a file extension of one, two, or more than three characters returns only files with extensions of exactly that length that match the file extension specified in the `searchPattern`. When using the question mark wildcard character, this method returns only files that match the specified file extension. For example, given two files in a directory, "file1.txt" and "file1.txtother", a search pattern of "file?.txt" returns only the first file, while a search pattern of "file\*.txt" returns both files. + + The following list shows the behavior of different lengths for the `searchPattern` parameter: + +- "*.abc" returns files having an extension of .abc, .abcd, .abcde, .abcdef, and so on. + +- "*.abcd" returns only files having an extension of .abcd. + +- "*.abcde" returns only files having an extension of .abcde. + +- "*.abcdef" returns only files having an extension of .abcdef. + > [!NOTE] -> Because this method checks against file names with both the 8.3 file name format and the long file name format, a search pattern similar to "*1\*.txt" may return unexpected file names. For example, using a search pattern of "\*1\*.txt" will return "longfilename.txt" because the equivalent 8.3 file name format would be "longf~1.txt". - - This method pre-populates the values of the following properties: - -1. - -2. - -3. - -4. - -5. - -6. - -7. - -8. - - - -## Examples - The following example shows how to get a list of files from a directory by using different search options. The example assumes a directory that has files named log1.txt, log2.txt, test1.txt, test2.txt, test3.txt, and a subdirectory that has a file named SubFile.txt. - +> Because this method checks against file names with both the 8.3 file name format and the long file name format, a search pattern similar to "*1\*.txt" may return unexpected file names. For example, using a search pattern of "\*1\*.txt" will return "longfilename.txt" because the equivalent 8.3 file name format would be "longf~1.txt". + + This method pre-populates the values of the following properties: + +1. + +2. + +3. + +4. + +5. + +6. + +7. + +8. + + + +## Examples + The following example shows how to get a list of files from a directory by using different search options. The example assumes a directory that has files named log1.txt, log2.txt, test1.txt, test2.txt, test3.txt, and a subdirectory that has a file named SubFile.txt. + :::code language="csharp" source="~/snippets/csharp/System.IO/DirectoryInfo/GetFiles/directoryinfogetfiles2.cs" id="Snippet2"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/DirectoryInfo/GetFiles/directoryinfogetfiles2.fs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/directoryinfogetfiles/VB/directoryinfogetfiles2.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/directoryinfogetfiles/VB/directoryinfogetfiles2.vb" id="Snippet2"::: + ]]> .NET Framework and .NET Core versions older than 2.1: contains one or more invalid characters defined by the method. @@ -3094,38 +3094,38 @@ namespace ConsoleApp Returns an array of strongly typed entries representing all the files and subdirectories in a directory. An array of strongly typed entries. - , this method returns an empty array. This method is not recursive. - - For subdirectories, the objects returned by this method can be cast to the derived class . Use the value returned by the property to determine whether the represents a file or a directory. - - This method pre-populates the values of the following properties: - -- - -- - -- - -- - -- - -- - -- - - - -## Examples - The following example counts the files and directories under the specified directory. - + , this method returns an empty array. This method is not recursive. + + For subdirectories, the objects returned by this method can be cast to the derived class . Use the value returned by the property to determine whether the represents a file or a directory. + + This method pre-populates the values of the following properties: + +- + +- + +- + +- + +- + +- + +- + + + +## Examples + The following example counts the files and directories under the specified directory. + :::code language="csharp" source="~/snippets/csharp/System.IO/DirectoryInfo/GetFileSystemInfos/fsizesort.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/DirectoryInfo/GetFileSystemInfos/fsizesort.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/FSizeSort/VB/fsizesort.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/FSizeSort/VB/fsizesort.vb" id="Snippet1"::: + ]]> The path is invalid (for example, it is on an unmapped drive). @@ -3189,51 +3189,51 @@ namespace ConsoleApp Retrieves an array of strongly typed objects representing the files and subdirectories that match the specified search criteria. An array of strongly typed objects matching the search criteria. - objects returned by this method can be cast to the derived class . Use the value returned by the property to determine whether the represents a file or a directory. - - Wild cards are permitted. For example, the `searchPattern` string "\*t" searches for all directory names in `path` ending with the letter "t". The `searchPattern` string "s\*" searches for all directory names in `path` beginning with the letter "s". - - The string ".." can only be used in `searchPattern` if it is specified as a part of a valid directory name, such as in the directory name "a..b". It cannot be used to move up the directory hierarchy. If there are no files or directories, or no files or directories that match the `searchPattern` string in the , this method returns an empty array. - - This method pre-populates the values of the following properties: - -- - -- - -- - -- - -- - -- - -- - - - -## Examples - The following example counts the files and directories that match the specified search pattern. - + objects returned by this method can be cast to the derived class . Use the value returned by the property to determine whether the represents a file or a directory. + + Wild cards are permitted. For example, the `searchPattern` string "\*t" searches for all directory names in `path` ending with the letter "t". The `searchPattern` string "s\*" searches for all directory names in `path` beginning with the letter "s". + + The string ".." can only be used in `searchPattern` if it is specified as a part of a valid directory name, such as in the directory name "a..b". It cannot be used to move up the directory hierarchy. If there are no files or directories, or no files or directories that match the `searchPattern` string in the , this method returns an empty array. + + This method pre-populates the values of the following properties: + +- + +- + +- + +- + +- + +- + +- + + + +## Examples + The following example counts the files and directories that match the specified search pattern. + :::code language="csharp" source="~/snippets/csharp/System.IO/DirectoryInfo/GetFileSystemInfos/dirinfo getfilesysinfos2.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/DirectoryInfo/GetFileSystemInfos/dirinfo getfilesysinfos2.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/DirInfo GetFileSysInfos2/VB/dirinfo getfilesysinfos2.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/DirInfo GetFileSysInfos2/VB/dirinfo getfilesysinfos2.vb" id="Snippet1"::: + ]]> .NET Framework and .NET Core versions older than 2.1: contains one or more invalid characters defined by the method. @@ -3289,41 +3289,41 @@ namespace ConsoleApp Retrieves an array of strongly typed objects representing the files and subdirectories that match the specified search pattern and enumeration options. An array of strongly typed objects matching and . - objects returned by this method can be cast to the derived class . Use the value returned by the property to determine whether the represents a file or a directory. - - Wild cards are permitted. For example, the `searchPattern` string "\*t" searches for all directory names in `path` ending with the letter "t". The `searchPattern` string "s\*" searches for all directory names in `path` beginning with the letter "s". - - The string ".." can only be used in `searchPattern` if it is specified as a part of a valid directory name, such as in the directory name "a..b". It cannot be used to move up the directory hierarchy. If there are no files or directories, or no files or directories that match the `searchPattern` string in the , this method returns an empty array. - - This method pre-populates the values of the following properties: - -- - -- - -- - -- - -- - -- - -- + objects returned by this method can be cast to the derived class . Use the value returned by the property to determine whether the represents a file or a directory. + + Wild cards are permitted. For example, the `searchPattern` string "\*t" searches for all directory names in `path` ending with the letter "t". The `searchPattern` string "s\*" searches for all directory names in `path` beginning with the letter "s". + + The string ".." can only be used in `searchPattern` if it is specified as a part of a valid directory name, such as in the directory name "a..b". It cannot be used to move up the directory hierarchy. If there are no files or directories, or no files or directories that match the `searchPattern` string in the , this method returns an empty array. + + This method pre-populates the values of the following properties: + +- + +- + +- + +- + +- + +- + +- ]]> @@ -3387,36 +3387,36 @@ namespace ConsoleApp Retrieves an array of objects that represent the files and subdirectories matching the specified search criteria. An array of file system entries that match the search criteria. - objects returned by this method can be cast to the derived class . Use the value returned by the property to determine whether the represents a file or a directory. - - This method pre-populates the values of the following properties: - -- - -- - -- - -- - -- - -- - -- - + objects returned by this method can be cast to the derived class . Use the value returned by the property to determine whether the represents a file or a directory. + + This method pre-populates the values of the following properties: + +- + +- + +- + +- + +- + +- + +- + ]]> .NET Framework and .NET Core versions older than 2.1: contains one or more invalid characters defined by the method. @@ -3481,43 +3481,43 @@ namespace ConsoleApp The name and path to which to move this directory. The destination cannot be another disk volume or a directory with the identical name. It can be an existing directory to which you want to add this directory as a subdirectory. Moves a instance and its contents to a new path. - if, for example, you try to move c:\mydir to c:\public, and c:\public already exists. You must specify "c:\\\public\\\mydir" as the `destDirName` parameter, or specify a new directory name such as "c:\\\newdir". - - This method permits moving a directory to a read-only directory. The read/write attribute of neither directory is affected. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following example demonstrates moving a directory. - + if, for example, you try to move c:\mydir to c:\public, and c:\public already exists. You must specify "c:\\\public\\\mydir" as the `destDirName` parameter, or specify a new directory name such as "c:\\\newdir". + + This method permits moving a directory to a read-only directory. The read/write attribute of neither directory is affected. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following example demonstrates moving a directory. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/directoryinfomoveto/CPP/directoryinfomoveto.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.IO/DirectoryInfo/MoveTo/directoryinfomoveto.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/DirectoryInfo/MoveTo/directoryinfomoveto.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/directoryinfomoveto/VB/directoryinfomoveto.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/directoryinfomoveto/VB/directoryinfomoveto.vb" id="Snippet1"::: + ]]> is . is an empty string (''"). - An attempt was made to move a directory to a different volume. - - -or- - - already exists. - - -or- - - You are not authorized to access this path. - - -or- - + An attempt was made to move a directory to a different volume. + + -or- + + already exists. + + -or- + + You are not authorized to access this path. + + -or- + The directory being moved and the destination directory have the same name. The caller does not have the required permission. The destination directory cannot be found. @@ -3569,25 +3569,25 @@ namespace ConsoleApp Gets the name of this instance. The directory name. - property returns only the name of the directory, such as "Bin". To get the full path, such as "c:\public\Bin", use the property. - - The property of a requires no permission (beyond the read permission to the directory necessary to construct the ) but can give out the directory name. If it is necessary to hand out a to a protected directory with a cryptographically secure name, create a dummy directory for the untrusted code's use. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following example displays the name of the current `DirectoryInfo` instance only. - + property returns only the name of the directory, such as "Bin". To get the full path, such as "c:\public\Bin", use the property. + + The property of a requires no permission (beyond the read permission to the directory necessary to construct the ) but can give out the directory name. If it is necessary to hand out a to a protected directory with a cryptographically secure name, create a dummy directory for the untrusted code's use. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following example displays the name of the current `DirectoryInfo` instance only. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic DirectoryInfo.Name Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.IO/DirectoryInfo/Name/source.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/DirectoryInfo/Name/source.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic DirectoryInfo.Name Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic DirectoryInfo.Name Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -3664,7 +3664,7 @@ namespace ConsoleApp To ensure consistent behavior across versions and to make your intent explicit, retrieve the value of one of the following properties on the instance returned by `Parent`. - , which returns the simple name of the directory (such as `bin`). -- , which returns the absolute path of the directory. +- , which returns the absolute path of the directory. For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -3736,15 +3736,15 @@ The following example refers to the parent directory of a specified directory. Gets the root portion of the directory. An object that represents the root of the directory. - The caller does not have the required permission. @@ -3785,46 +3785,46 @@ The following example refers to the parent directory of a specified directory. System.Void - + An object that describes an ACL entry to apply to the directory described by the parameter. Applies access control list (ACL) entries described by a object to the directory described by the current object. - method applies ACL entries to a file that represents the noninherited ACL list. - + method applies ACL entries to a file that represents the noninherited ACL list. + > [!CAUTION] -> The ACL specified for `directorySecurity` replaces the existing ACL for the directory. To add permissions for a new user, use the method to obtain the existing ACL, and modify it. - - The method persists only objects that have been modified after object creation. If a object has not been modified, it will not be persisted to a file. Therefore, it is not possible to retrieve a object from one file and reapply the same object to another file. - - To copy ACL information from one file to another: - -1. Use the method to retrieve the object from the source file. - -2. Create a new object for the destination file. - -3. Use the or method of the source object to retrieve the ACL information. - -4. Use the or method to copy the information retrieved in step 3 to the destination object. - -5. Set the destination object to the destination file using the method. - - - -## Examples - The following example uses the and methods to add and then remove an access control list (ACL) entry from a directory. - +> The ACL specified for `directorySecurity` replaces the existing ACL for the directory. To add permissions for a new user, use the method to obtain the existing ACL, and modify it. + + The method persists only objects that have been modified after object creation. If a object has not been modified, it will not be persisted to a file. Therefore, it is not possible to retrieve a object from one file and reapply the same object to another file. + + To copy ACL information from one file to another: + +1. Use the method to retrieve the object from the source file. + +2. Create a new object for the destination file. + +3. Use the or method of the source object to retrieve the ACL information. + +4. Use the or method to copy the information retrieved in step 3 to the destination object. + +5. Set the destination object to the destination file using the method. + + + +## Examples + The following example uses the and methods to add and then remove an access control list (ACL) entry from a directory. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/IO.DiretoryInfo.GetAccessControl-SetAccessControl/cpp/sample.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.IO/Directory/GetAccessControl/sample.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.IO/Directory/GetAccessControl/sample.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/IO.DiretoryInfo.GetAccessControl-SetAccessControl/VB/sample.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/IO.DiretoryInfo.GetAccessControl-SetAccessControl/VB/sample.vb" id="Snippet1"::: + ]]> The parameter is . diff --git a/xml/System.IO/DirectoryNotFoundException.xml b/xml/System.IO/DirectoryNotFoundException.xml index b37704278ce..782d01e6001 100644 --- a/xml/System.IO/DirectoryNotFoundException.xml +++ b/xml/System.IO/DirectoryNotFoundException.xml @@ -64,17 +64,17 @@ The exception that is thrown when part of a file or directory cannot be found. - . - + . + :::code language="csharp" source="~/snippets/csharp/System.IO/DirectoryNotFoundException/Overview/program.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/DirectoryNotFoundException/VB/DirectoryNotFoundexception.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/DirectoryNotFoundException/VB/DirectoryNotFoundexception.vb" id="Snippet1"::: + ]]> @@ -131,21 +131,21 @@ Initializes a new instance of the class with its message string set to a system-supplied message and its HRESULT set to COR_E_DIRECTORYNOTFOUND. - property of the new instance to a system-supplied message that describes the error, such as "Could not find the specified directory." This message takes into account the current system culture. - - The property of the new instance is initialized to `null`. - - - -## Examples - The following code example demonstrates how to call the constructor. - + property of the new instance to a system-supplied message that describes the error, such as "Could not find the specified directory." This message takes into account the current system culture. + + The property of the new instance is initialized to `null`. + + + +## Examples + The following code example demonstrates how to call the constructor. + :::code language="csharp" source="~/snippets/csharp/System.IO/DirectoryNotFoundException/Overview/program.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/DirectoryNotFoundException/VB/DirectoryNotFoundexception.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/DirectoryNotFoundException/VB/DirectoryNotFoundexception.vb" id="Snippet1"::: + ]]> File and Stream I/O @@ -194,13 +194,13 @@ A that describes the error. The content of is intended to be understood by humans. The caller of this constructor is required to ensure that this string has been localized for the current system culture. Initializes a new instance of the class with its message string set to and its HRESULT set to COR_E_DIRECTORYNOTFOUND. - property of the new instance using `message`. - - The property of the new instance is initialized to `null`. - + property of the new instance using `message`. + + The property of the new instance is initialized to `null`. + ]]> File and Stream I/O @@ -258,8 +258,8 @@ - - + + The that holds the serialized object data about the exception being thrown. @@ -314,18 +314,18 @@ The exception that is the cause of the current exception. If the parameter is not , the current exception is raised in a block that handles the inner exception. Initializes a new instance of the class with a specified error message and a reference to the inner exception that is the cause of this exception. - property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||The inner exception reference.| -||The error message string.| - + property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||The inner exception reference.| +||The error message string.| + ]]> diff --git a/xml/System.IO/EndOfStreamException.xml b/xml/System.IO/EndOfStreamException.xml index 5caf397bf09..8ca3bf0d9de 100644 --- a/xml/System.IO/EndOfStreamException.xml +++ b/xml/System.IO/EndOfStreamException.xml @@ -84,20 +84,20 @@ The exception that is thrown when reading is attempted past the end of a stream. - and classes on top of the class. - + and classes on top of the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.BinaryReaderWriter.RWDouble/CPP/rwdouble.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.IO/BinaryReader/BaseStream/rwdouble.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.BinaryReaderWriter.RWDouble/VB/rwdouble.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.BinaryReaderWriter.RWDouble/VB/rwdouble.vb" id="Snippet1"::: + ]]> @@ -275,8 +275,8 @@ - - + + The that holds the serialized object data about the exception being thrown. @@ -338,18 +338,18 @@ The exception that is the cause of the current exception. If the parameter is not , the current exception is raised in a block that handles the inner exception. Initializes a new instance of the class with a specified error message and a reference to the inner exception that is the cause of this exception. - property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||The inner exception reference.| -||The error message string.| - + property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||The inner exception reference.| +||The error message string.| + ]]> diff --git a/xml/System.IO/File.xml b/xml/System.IO/File.xml index fc1c0501b6b..03d6d964be2 100644 --- a/xml/System.IO/File.xml +++ b/xml/System.IO/File.xml @@ -1463,10 +1463,10 @@ System.IO.FileStream - - - - + + + + The path and name of the file to create. @@ -1708,7 +1708,7 @@ An I/O error occurred. System.Void - + A path that describes a file to decrypt. @@ -1916,7 +1916,7 @@ An I/O error occurred. System.Void - + A path that describes a file to encrypt. @@ -2118,7 +2118,7 @@ An I/O error occurred. System.Security.AccessControl.FileSecurity - + The path to a file containing a object that describes the file's access control list (ACL) information. @@ -2190,8 +2190,8 @@ An I/O error occurred. System.Security.AccessControl.FileSecurity - - + + The path to a file containing a object that describes the file's access control list (ACL) information. @@ -3393,7 +3393,7 @@ The following example moves a file. or is . .NET Framework and .NET Core versions older than 2.1: or is a zero-length string, contains only white space, or contains invalid characters. You can query for invalid characters by using the method. The caller does not have the required permission. - + -or- The Operating System has failed to acquire an exclusive access to the destination file. @@ -5226,9 +5226,9 @@ The following example moves a file. System.Void - - - + + + [System.Runtime.CompilerServices.Nullable(2)] @@ -5347,9 +5347,9 @@ The caller does not have the required permission. System.Void - - - + + + [System.Runtime.CompilerServices.Nullable(2)] @@ -5357,7 +5357,7 @@ The caller does not have the required permission. - + The name of a file that replaces the file specified by . @@ -5516,8 +5516,8 @@ There are too many levels of symbolic links. System.Void - - + + A file to add or remove access control list (ACL) entries from. @@ -6868,8 +6868,8 @@ It is not possible to change the compression status of a o System.Void - - + + The file to write to. @@ -7064,9 +7064,9 @@ It is not possible to change the compression status of a o System.Void - - - + + + The file to write to. diff --git a/xml/System.IO/FileInfo.xml b/xml/System.IO/FileInfo.xml index cd790025fe8..8cee1177d6e 100644 --- a/xml/System.IO/FileInfo.xml +++ b/xml/System.IO/FileInfo.xml @@ -71,73 +71,73 @@ Provides properties and instance methods for the creation, copying, deletion, moving, and opening of files, and aids in the creation of objects. This class cannot be inherited. - class for typical operations such as copying, moving, renaming, creating, opening, deleting, and appending to files. - - If you are performing multiple operations on the same file, it can be more efficient to use instance methods instead of the corresponding static methods of the class, because a security check will not always be necessary. - - Many of the methods return other I/O types when you create or open files. You can use these other types to further manipulate a file. For more information, see specific members such as , , , , or . - - By default, full read/write access to new files is granted to all users. - - The following table describes the enumerations that are used to customize the behavior of various methods. - -|Enumeration|Description| -|-----------------|-----------------| -||Specifies read and write access to a file.| -||Specifies the level of access permitted for a file that is already in use.| -||Specifies whether the contents of an existing file are preserved or overwritten, and whether requests to create an existing file cause an exception.| - + class for typical operations such as copying, moving, renaming, creating, opening, deleting, and appending to files. + + If you are performing multiple operations on the same file, it can be more efficient to use instance methods instead of the corresponding static methods of the class, because a security check will not always be necessary. + + Many of the methods return other I/O types when you create or open files. You can use these other types to further manipulate a file. For more information, see specific members such as , , , , or . + + By default, full read/write access to new files is granted to all users. + + The following table describes the enumerations that are used to customize the behavior of various methods. + +|Enumeration|Description| +|-----------------|-----------------| +||Specifies read and write access to a file.| +||Specifies the level of access permitted for a file that is already in use.| +||Specifies whether the contents of an existing file are preserved or overwritten, and whether requests to create an existing file cause an exception.| + > [!NOTE] -> In members that accept a path as an input string, that path must be well-formed or an exception is raised. For example, if a path is fully qualified but begins with a space, the path is not trimmed in methods of the class. Therefore, the path is malformed and an exception is raised. Similarly, a path or a combination of paths cannot be fully qualified twice. For example, "c:\temp c:\windows" also raises an exception in most cases. Ensure that your paths are well-formed when using methods that accept a path string. - - In members that accept a path, the path can refer to a file or just a directory. The specified path can also refer to a relative path or a Universal Naming Convention (UNC) path for a server and share name. For example, all the following are acceptable paths: - -- "c:\\\MyDir\\\MyFile.txt" in C#, or "c:\MyDir\MyFile.txt" in Visual Basic. - -- "c:\\\MyDir" in C#, or "c:\MyDir" in Visual Basic. - -- "MyDir\\\MySubdir" in C#, or "MyDir\MySubDir" in Visual Basic. - -- "\\\\\\\MyServer\\\MyShare" in C#, or "\\\MyServer\MyShare" in Visual Basic. - - The class provides the following properties that enable you to retrieve information about a file. For an example of how to use each property, see the property pages. - -- The property retrieves an object that represents the parent directory of a file. - -- The property retrieves the full path of the parent directory of a file. - -- The property checks for the presence of a file before operating on it. - -- The property retrieves or sets a value that specifies whether a file can be modified. - -- The retrieves the size of a file. - -- The retrieves the name of a file. - - - -## Examples - The following example demonstrates some of the main members of the `FileInfo` class. - - When the properties are first retrieved, calls the method and caches information about the file. On subsequent calls, you must call to get the latest copy of the information. - +> In members that accept a path as an input string, that path must be well-formed or an exception is raised. For example, if a path is fully qualified but begins with a space, the path is not trimmed in methods of the class. Therefore, the path is malformed and an exception is raised. Similarly, a path or a combination of paths cannot be fully qualified twice. For example, "c:\temp c:\windows" also raises an exception in most cases. Ensure that your paths are well-formed when using methods that accept a path string. + + In members that accept a path, the path can refer to a file or just a directory. The specified path can also refer to a relative path or a Universal Naming Convention (UNC) path for a server and share name. For example, all the following are acceptable paths: + +- "c:\\\MyDir\\\MyFile.txt" in C#, or "c:\MyDir\MyFile.txt" in Visual Basic. + +- "c:\\\MyDir" in C#, or "c:\MyDir" in Visual Basic. + +- "MyDir\\\MySubdir" in C#, or "MyDir\MySubDir" in Visual Basic. + +- "\\\\\\\MyServer\\\MyShare" in C#, or "\\\MyServer\MyShare" in Visual Basic. + + The class provides the following properties that enable you to retrieve information about a file. For an example of how to use each property, see the property pages. + +- The property retrieves an object that represents the parent directory of a file. + +- The property retrieves the full path of the parent directory of a file. + +- The property checks for the presence of a file before operating on it. + +- The property retrieves or sets a value that specifies whether a file can be modified. + +- The retrieves the size of a file. + +- The retrieves the name of a file. + + + +## Examples + The following example demonstrates some of the main members of the `FileInfo` class. + + When the properties are first retrieved, calls the method and caches information about the file. On subsequent calls, you must call to get the latest copy of the information. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/FInfo Class/CPP/finfo class.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.IO/FileInfo/Overview/finfo class.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/FInfo Class/VB/finfo class.vb" id="Snippet1"::: - - This example produces output similar to the following. - -``` -Hello -And -Welcome -C:\Users\userName\AppData\Local\Temp\tmp70AB.tmp was copied to C:\Users\userName\AppData\Local\Temp\tmp70CB.tmp. -C:\Users\userName\AppData\Local\Temp\tmp70CB.tmp was successfully deleted. -``` - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/FInfo Class/VB/finfo class.vb" id="Snippet1"::: + + This example produces output similar to the following. + +``` +Hello +And +Welcome +C:\Users\userName\AppData\Local\Temp\tmp70AB.tmp was copied to C:\Users\userName\AppData\Local\Temp\tmp70CB.tmp. +C:\Users\userName\AppData\Local\Temp\tmp70CB.tmp was successfully deleted. +``` + ]]> @@ -197,24 +197,24 @@ C:\Users\userName\AppData\Local\Temp\tmp70CB.tmp was successfully deleted. The fully qualified name of the new file, or the relative file name. Do not end the path with the directory separator character. Initializes a new instance of the class, which acts as a wrapper for a file path. - @@ -280,21 +280,21 @@ C:\Users\userName\AppData\Local\Temp\tmp70CB.tmp was successfully deleted. Creates a that appends text to the file represented by this instance of the . A new . - @@ -361,29 +361,29 @@ C:\Users\userName\AppData\Local\Temp\tmp70CB.tmp was successfully deleted. Copies an existing file to a new file, disallowing the overwriting of an existing file. A new file with a fully qualified path. - method to allow overwriting of an existing file. - + method to allow overwriting of an existing file. + > [!CAUTION] -> Whenever possible, avoid using short file names (such as XXXXXX~1.XXX) with this method. If two files have equivalent short file names then this method may fail and raise an exception and/or result in undesirable behavior - - - -## Examples - The following example demonstrates both overloads of the `CopyTo` method. - +> Whenever possible, avoid using short file names (such as XXXXXX~1.XXX) with this method. If two files have equivalent short file names then this method may fail and raise an exception and/or result in undesirable behavior + + + +## Examples + The following example demonstrates both overloads of the `CopyTo` method. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/FInfo CopyTo2/CPP/finfo copyto2.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.IO/FileInfo/CopyTo/program.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/FInfo CopyTo2/VB/program.vb" id="Snippet1"::: - - The following example demonstrates copying one file to another file, throwing an exception if the destination file already exists. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/FInfo CopyTo2/VB/program.vb" id="Snippet1"::: + + The following example demonstrates copying one file to another file, throwing an exception if the destination file already exists. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/FileInfoCopyTo1/CPP/fileinfocopyto1.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.IO/FileInfo/CopyTo/fileinfocopyto1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/FileInfoCopyTo1/VB/fileinfocopyto1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/FileInfoCopyTo1/VB/fileinfocopyto1.vb" id="Snippet1"::: + ]]> .NET Framework and .NET Core versions older than 2.1: is empty, contains only white spaces, or contains invalid characters. @@ -452,29 +452,29 @@ C:\Users\userName\AppData\Local\Temp\tmp70CB.tmp was successfully deleted. Copies an existing file to a new file, allowing the overwriting of an existing file. A new file, or an overwrite of an existing file if is . If the file exists and is , an is thrown. - method to prevent overwriting of an existing file by default. - + method to prevent overwriting of an existing file by default. + > [!CAUTION] -> Whenever possible, avoid using short file names (such as XXXXXX~1.XXX) with this method. If two files have equivalent short file names then this method may fail and raise an exception and/or result in undesirable behavior - - - -## Examples - The following example demonstrates both overloads of the `CopyTo` method. - +> Whenever possible, avoid using short file names (such as XXXXXX~1.XXX) with this method. If two files have equivalent short file names then this method may fail and raise an exception and/or result in undesirable behavior + + + +## Examples + The following example demonstrates both overloads of the `CopyTo` method. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/FInfo CopyTo2/CPP/finfo copyto2.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.IO/FileInfo/CopyTo/program.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/FInfo CopyTo2/VB/program.vb" id="Snippet1"::: - - The following example demonstrates copying one file to another file, specifying whether to overwrite a file that already exists. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/FInfo CopyTo2/VB/program.vb" id="Snippet1"::: + + The following example demonstrates copying one file to another file, specifying whether to overwrite a file that already exists. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/fileinfocopyto/CPP/fileinfocopyto.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.IO/FileInfo/CopyTo/fileinfocopyto.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/fileinfocopyto/VB/fileinfocopyto.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/fileinfocopyto/VB/fileinfocopyto.vb" id="Snippet1"::: + ]]> .NET Framework and .NET Core versions older than 2.1: is empty, contains only white spaces, or contains invalid characters. @@ -543,28 +543,28 @@ C:\Users\userName\AppData\Local\Temp\tmp70CB.tmp was successfully deleted. Creates a file. A new file. - . - - - -## Examples - The following example creates a reference to a file, and then creates the file on disk using `FileInfo.Create()`. - + . + + + +## Examples + The following example creates a reference to a file, and then creates the file on disk using `FileInfo.Create()`. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/fileinfodelete/CPP/fileinfodelete.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.IO/FileInfo/Create/fileinfodelete.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/fileinfodelete/VB/fileinfodelete.vb" id="Snippet1"::: - - The following example creates a file, adds some text to it, and reads from the file. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/fileinfodelete/VB/fileinfodelete.vb" id="Snippet1"::: + + The following example creates a file, adds some text to it, and reads from the file. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/FInfo Create/CPP/finfo create.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.IO/FileInfo/Create/finfo create.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/FInfo Create/VB/finfo create.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/FInfo Create/VB/finfo create.vb" id="Snippet1"::: + ]]> File and Stream I/O @@ -623,20 +623,20 @@ C:\Users\userName\AppData\Local\Temp\tmp70CB.tmp was successfully deleted. Creates a that writes a new text file. A new . - The file name is a directory. @@ -699,24 +699,24 @@ C:\Users\userName\AppData\Local\Temp\tmp70CB.tmp was successfully deleted. Decrypts a file that was encrypted by the current account using the method. - method allows you to decrypt a file that was encrypted using the method. The method can decrypt only files that were encrypted using the current user account. - - Both the method and the method use the cryptographic service provider (CSP) installed on the computer and the file encryption keys of the process calling the method. - - The current file system must be formatted as NTFS and the current operating system must be Microsoft Windows NT or later. - - - -## Examples - The following code example uses the method and the method to encrypt and then decrypt a file. - + method allows you to decrypt a file that was encrypted using the method. The method can decrypt only files that were encrypted using the current user account. + + Both the method and the method use the cryptographic service provider (CSP) installed on the computer and the file encryption keys of the process calling the method. + + The current file system must be formatted as NTFS and the current operating system must be Microsoft Windows NT or later. + + + +## Examples + The following code example uses the method and the method to encrypt and then decrypt a file. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/IO.FileInfo.Encrypt-Decrypt/cpp/sample.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.IO/FileInfo/Decrypt/sample.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/IO.FileInfo.Encrypt-Decrypt/VB/sample.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/IO.FileInfo.Encrypt-Decrypt/VB/sample.vb" id="Snippet1"::: + ]]> An invalid drive was specified. @@ -724,14 +724,14 @@ C:\Users\userName\AppData\Local\Temp\tmp70CB.tmp was successfully deleted. An I/O error occurred while opening the file. The file system is not NTFS. The current operating system is not Microsoft Windows NT or later. - The file described by the current object is read-only. - - -or- - - This operation is not supported on the current platform. - - -or- - + The file described by the current object is read-only. + + -or- + + This operation is not supported on the current platform. + + -or- + The caller does not have the required permission. @@ -784,32 +784,32 @@ C:\Users\userName\AppData\Local\Temp\tmp70CB.tmp was successfully deleted. Permanently deletes a file. - - The target file is open or memory-mapped on a computer running Microsoft Windows NT. - - -or- - + The target file is open or memory-mapped on a computer running Microsoft Windows NT. + + -or- + There is an open handle on the file, and the operating system is Windows XP or earlier. This open handle can result from enumerating directories and files. For more information, see [How to: Enumerate Directories and Files](/dotnet/standard/io/how-to-enumerate-directories-and-files). The caller does not have the required permission. The path is a directory. @@ -876,20 +876,20 @@ C:\Users\userName\AppData\Local\Temp\tmp70CB.tmp was successfully deleted. Gets an instance of the parent directory. A object representing the parent directory of this file. - property. - - - -## Examples - The following example opens or creates a file, determines its full path, and determines and displays the full contents of the directory. - + property. + + + +## Examples + The following example opens or creates a file, determines its full path, and determines and displays the full contents of the directory. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/fileinfodirectory/CPP/fileinfodirectory.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.IO/FileInfo/Directory/fileinfodirectory.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/fileinfodirectory/VB/fileinfodirectory.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/fileinfodirectory/VB/fileinfodirectory.vb" id="Snippet1"::: + ]]> The specified path is invalid, such as being on an unmapped drive. @@ -957,18 +957,18 @@ C:\Users\userName\AppData\Local\Temp\tmp70CB.tmp was successfully deleted. Gets a string representing the directory's full path. A string representing the directory's full path. - object, use the property. - - When first called, calls and caches information about the file. On subsequent calls, you must call to get the latest copy of the information. - -## Examples - The following example retrieves the full path of the specified file. - + object, use the property. + + When first called, calls and caches information about the file. On subsequent calls, you must call to get the latest copy of the information. + +## Examples + The following example retrieves the full path of the specified file. + :::code language="csharp" source="~/snippets/csharp/System.IO/FileInfo/DirectoryName/fileinfomembers.cs" id="Snippet3"::: - + ]]> @@ -1030,24 +1030,24 @@ C:\Users\userName\AppData\Local\Temp\tmp70CB.tmp was successfully deleted. Encrypts a file so that only the account used to encrypt the file can decrypt it. - method allows you to encrypt a file so that only the account used to call this method can decrypt it. Use the method to decrypt a file encrypted by the method. - - Both the method and the method use the cryptographic service provider (CSP) installed on the computer and the file encryption keys of the process calling the method. - - The current file system must be formatted as NTFS and the current operating system must be Microsoft Windows NT or later. - - - -## Examples - The following code example uses the method and the method to encrypt a file and then decrypt it. - + method allows you to encrypt a file so that only the account used to call this method can decrypt it. Use the method to decrypt a file encrypted by the method. + + Both the method and the method use the cryptographic service provider (CSP) installed on the computer and the file encryption keys of the process calling the method. + + The current file system must be formatted as NTFS and the current operating system must be Microsoft Windows NT or later. + + + +## Examples + The following code example uses the method and the method to encrypt a file and then decrypt it. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/IO.FileInfo.Encrypt-Decrypt/cpp/sample.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.IO/FileInfo/Decrypt/sample.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/IO.FileInfo.Encrypt-Decrypt/VB/sample.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/IO.FileInfo.Encrypt-Decrypt/VB/sample.vb" id="Snippet1"::: + ]]> An invalid drive was specified. @@ -1055,14 +1055,14 @@ C:\Users\userName\AppData\Local\Temp\tmp70CB.tmp was successfully deleted. An I/O error occurred while opening the file. The file system is not NTFS. The current operating system is not Microsoft Windows NT or later. - The file described by the current object is read-only. - - -or- - - This operation is not supported on the current platform. - - -or- - + The file described by the current object is read-only. + + -or- + + This operation is not supported on the current platform. + + -or- + The caller does not have the required permission. @@ -1116,22 +1116,22 @@ C:\Users\userName\AppData\Local\Temp\tmp70CB.tmp was successfully deleted. if the file exists; if the file does not exist or if the file is a directory. - calls and caches information about the file. On subsequent calls, you must call to get the latest copy of the information. - - The property returns `false` if any error occurs while trying to determine if the specified file exists. This can occur in situations that raise exceptions such as passing a file name with invalid characters or too many characters, a failing or missing disk, or if the caller does not have permission to read the file. - - - -## Examples - The following code example uses the property ensure a file exists before opening it. You can use this technique to throw a custom exception when the file is not found. - + calls and caches information about the file. On subsequent calls, you must call to get the latest copy of the information. + + The property returns `false` if any error occurs while trying to determine if the specified file exists. This can occur in situations that raise exceptions such as passing a file name with invalid characters or too many characters, a failing or missing disk, or if the caller does not have permission to read the file. + + + +## Examples + The following code example uses the property ensure a file exists before opening it. You can use this technique to throw a custom exception when the file is not found. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/IO.FileInfo.Exists/cpp/sample.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.IO/FileInfo/Exists/sample.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/IO.FileInfo.Exists/vb/sample.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/IO.FileInfo.Exists/vb/sample.vb" id="Snippet1"::: + ]]> File and Stream I/O @@ -1148,11 +1148,11 @@ C:\Users\userName\AppData\Local\Temp\tmp70CB.tmp was successfully deleted. Gets a object that encapsulates the access control list (ACL) entries for the file described by the current object. - methods to retrieve the access control list (ACL) entries for the current file. - + methods to retrieve the access control list (ACL) entries for the current file. + ]]> @@ -1187,31 +1187,31 @@ C:\Users\userName\AppData\Local\Temp\tmp70CB.tmp was successfully deleted. Gets a object that encapsulates the access control list (ACL) entries for the file described by the current object. A object that encapsulates the access control rules for the current file. - method to retrieve the access control list (ACL) entries for the current file. - - An ACL describes individuals and/or groups who have, or do not have, rights to specific actions on the given file. For more information, see [How to: Add or Remove Access Control List Entries](/dotnet/standard/io/how-to-add-or-remove-access-control-list-entries). - - - -## Examples - The following code example uses the method and the method to add and then remove an access control list (ACL) entry from a file. You must supply a valid user or group account to run this example. - + method to retrieve the access control list (ACL) entries for the current file. + + An ACL describes individuals and/or groups who have, or do not have, rights to specific actions on the given file. For more information, see [How to: Add or Remove Access Control List Entries](/dotnet/standard/io/how-to-add-or-remove-access-control-list-entries). + + + +## Examples + The following code example uses the method and the method to add and then remove an access control list (ACL) entry from a file. You must supply a valid user or group account to run this example. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/IO.FileInfo.GetAccessControl-SetAccessControl/cpp/sample.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.IO/FileInfo/GetAccessControl/sample.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/IO.FileInfo.GetAccessControl-SetAccessControl/VB/sample.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/IO.FileInfo.GetAccessControl-SetAccessControl/VB/sample.vb" id="Snippet1"::: + ]]> An I/O error occurred while opening the file. The current system account does not have administrative privileges. The file could not be found. - This operation is not supported on the current platform. - - -or- - + This operation is not supported on the current platform. + + -or- + The caller does not have the required permission. @@ -1241,29 +1241,29 @@ C:\Users\userName\AppData\Local\Temp\tmp70CB.tmp was successfully deleted. System.Security.AccessControl.FileSecurity - + One of the values that specifies which group of access control entries to retrieve. Gets a object that encapsulates the specified type of access control list (ACL) entries for the file described by the current object. A object that encapsulates the access control rules for the current file. - method to retrieve the access control list (ACL) entries for the current file. - - An ACL describes individuals and/or groups who have, or do not have, rights to specific actions on the given file. For more information, see [How to: Add or Remove Access Control List Entries](/dotnet/standard/io/how-to-add-or-remove-access-control-list-entries). - + method to retrieve the access control list (ACL) entries for the current file. + + An ACL describes individuals and/or groups who have, or do not have, rights to specific actions on the given file. For more information, see [How to: Add or Remove Access Control List Entries](/dotnet/standard/io/how-to-add-or-remove-access-control-list-entries). + ]]> An I/O error occurred while opening the file. The current system account does not have administrative privileges. The file could not be found. - This operation is not supported on the current platform. - - -or- - + This operation is not supported on the current platform. + + -or- + The caller does not have the required permission. @@ -1320,32 +1320,32 @@ C:\Users\userName\AppData\Local\Temp\tmp70CB.tmp was successfully deleted. if the current file is read only or could not be found; otherwise, . - property to quickly determine or change whether the current file is read only. - + property to quickly determine or change whether the current file is read only. + If the current file does not exist, getting this property will always return `true`, but attempts to set will throw a . - When first called, calls and caches information about the file. On subsequent calls, you must call to get the latest copy of the information. - - - -## Examples - The following example creates a temporary file, uses the property to first check and then set its read-only status, and finally marks it as read-write in order to delete it. - + When first called, calls and caches information about the file. On subsequent calls, you must call to get the latest copy of the information. + + + +## Examples + The following example creates a temporary file, uses the property to first check and then set its read-only status, and finally marks it as read-write in order to delete it. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/IO.FileInfo.isReadOnly/cpp/sample.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.IO/FileInfo/IsReadOnly/sample.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/IO.FileInfo.isReadOnly/VB/sample.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/IO.FileInfo.isReadOnly/VB/sample.vb" id="Snippet1"::: + ]]> The file described by the current object could not be found when trying to set the IsReadOnly property. (Note that getting this property for a nonexistent file will not throw an exception, but rather returns .) An I/O error occurred while opening the file. - This operation is not supported on the current platform. - - -or- - + This operation is not supported on the current platform. + + -or- + The caller does not have the required permission. The user does not have write permission, but attempted to set this property to . @@ -1399,42 +1399,42 @@ C:\Users\userName\AppData\Local\Temp\tmp70CB.tmp was successfully deleted. Gets the size, in bytes, of the current file. The size of the current file in bytes. - property is pre-cached if the current instance of the object was returned from any of the following methods: - -- - -- - -- - -- - -- - -- - - To get the latest value, call the method. - - - -## Examples - The following example displays the size of the specified files. - + property is pre-cached if the current instance of the object was returned from any of the following methods: + +- + +- + +- + +- + +- + +- + + To get the latest value, call the method. + + + +## Examples + The following example displays the size of the specified files. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/FileLength/CPP/filelength.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.IO/FileInfo/Length/filelength.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/FileLength/VB/filelength.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/FileLength/VB/filelength.vb" id="Snippet1"::: + ]]> cannot update the state of the file or directory. - The file does not exist. - - -or- - + The file does not exist. + + -or- + The property is called for a directory. File and Stream I/O How to: Read Text from a File @@ -1642,22 +1642,22 @@ The following example demonstrates moving a file to a different location and ren Gets the name of the file. The name of the file. - calls and caches information about the file. On subsequent calls, you must call to get the latest copy of the information. - - The name of the file includes the file extension. - - - -## Examples - The following example uses the `Name` property to display the names of files in the current directory. - + calls and caches information about the file. On subsequent calls, you must call to get the latest copy of the information. + + The name of the file includes the file extension. + + + +## Examples + The following example uses the `Name` property to display the names of files in the current directory. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/fileinfoname/CPP/fileinfoname.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.IO/FileInfo/Name/fileinfoname.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/fileinfoname/VB/fileinfoname.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/fileinfoname/VB/fileinfoname.vb" id="Snippet1"::: + ]]> File and Stream I/O @@ -1728,15 +1728,15 @@ The following example demonstrates moving a file to a different location and ren Opens a file in the specified mode. A file opened in the specified mode, with read/write access and unshared. - The file is not found. @@ -1848,15 +1848,15 @@ The following example demonstrates moving a file to a different location and ren Opens a file in the specified mode with read, write, or read/write access. A object opened in the specified mode and access, and unshared. - The caller does not have the required permission. @@ -1930,15 +1930,15 @@ The following example demonstrates moving a file to a different location and ren Opens a file in the specified mode with read, write, or read/write access and the specified sharing option. A object opened with the specified mode, access, and sharing options. - The caller does not have the required permission. @@ -2005,20 +2005,20 @@ The following example demonstrates moving a file to a different location and ren Creates a read-only . A new read-only object. - object with the mode set to . - - - -## Examples - The following example opens a file as read-only and reads from it. - + object with the mode set to . + + + +## Examples + The following example opens a file as read-only and reads from it. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/FInfo OpenRead/CPP/finfo openread.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.IO/FileInfo/OpenRead/finfo openread.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/FInfo OpenRead/VB/finfo openread.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/FInfo OpenRead/VB/finfo openread.vb" id="Snippet1"::: + ]]> @@ -2081,15 +2081,15 @@ The following example demonstrates moving a file to a different location and ren Creates a with UTF8 encoding that reads from an existing text file. A new with UTF8 encoding. - The caller does not have the required permission. @@ -2155,20 +2155,20 @@ The following example demonstrates moving a file to a different location and ren Creates a write-only . A write-only unshared object for a new or existing file. - method opens a file if one already exists for the file path, or creates a new file if one does not exist. For an existing file, it does not append the new text to the existing text. Instead, it overwrites the existing characters with the new characters. If you overwrite a longer string (such as "This is a test of the OpenWrite method") with a shorter string (like "Second run"), the file will contain a mix of the strings ("Second runtest of the OpenWrite method"). - - - -## Examples - The following example opens a file for writing and then reads from the file. - + method opens a file if one already exists for the file path, or creates a new file if one does not exist. For an existing file, it does not append the new text to the existing text. Instead, it overwrites the existing characters with the new characters. If you overwrite a longer string (such as "This is a test of the OpenWrite method") with a shorter string (like "Second run"), the file will contain a mix of the strings ("Second runtest of the OpenWrite method"). + + + +## Examples + The following example opens a file for writing and then reads from the file. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/FInfo OpenWrite/CPP/file openwrite.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.IO/FileInfo/OpenWrite/file openwrite.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/FInfo OpenWrite/VB/file openwrite.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/FInfo OpenWrite/VB/file openwrite.vb" id="Snippet1"::: + ]]> The path specified when creating an instance of the object is read-only or is a directory. @@ -2184,11 +2184,11 @@ The following example demonstrates moving a file to a different location and ren Replaces the contents of a specified file with the file described by the current object, deleting the original file, and creating a backup of the replaced file. - methods when you need to quickly replace a file with the contents of the file described by the current object. - + methods when you need to quickly replace a file with the contents of the file described by the current object. + ]]> @@ -2241,8 +2241,8 @@ The following example demonstrates moving a file to a different location and ren System.IO.FileInfo - - + + [System.Runtime.CompilerServices.Nullable(2)] @@ -2257,34 +2257,34 @@ The following example demonstrates moving a file to a different location and ren Replaces the contents of a specified file with the file described by the current object, deleting the original file, and creating a backup of the replaced file. A object that encapsulates information about the file described by the parameter. - method replaces the contents of a specified file with the contents of the file described by the current object. It also creates a backup of the file that was replaced. Finally, it returns a new object that describes the overwritten file. - - Pass `null` to the `destBackupFileName` parameter if you do not want to create a backup of the file being replaced. - - - -## Examples - The following example uses the method to replace a file with another file and create a backup of the replaced file. - + method replaces the contents of a specified file with the contents of the file described by the current object. It also creates a backup of the file that was replaced. Finally, it returns a new object that describes the overwritten file. + + Pass `null` to the `destBackupFileName` parameter if you do not want to create a backup of the file being replaced. + + + +## Examples + The following example uses the method to replace a file with another file and create a backup of the replaced file. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/IO.FileInfo.Replace/cpp/sample.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.IO/FileInfo/Replace/sample.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/IO.FileInfo.Replace/VB/sample.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/IO.FileInfo.Replace/VB/sample.vb" id="Snippet1"::: + ]]> - The path described by the parameter was not of a legal form. - - -or- - + The path described by the parameter was not of a legal form. + + -or- + The path described by the parameter was not of a legal form. The parameter is . - The file described by the current object could not be found. - - -or- - + The file described by the current object could not be found. + + -or- + The file described by the parameter could not be found. The current operating system is not Microsoft Windows NT or later. @@ -2337,8 +2337,8 @@ The following example demonstrates moving a file to a different location and ren System.IO.FileInfo - - + + [System.Runtime.CompilerServices.Nullable(2)] @@ -2346,7 +2346,7 @@ The following example demonstrates moving a file to a different location and ren - + The name of a file to replace with the current file. @@ -2356,34 +2356,34 @@ The following example demonstrates moving a file to a different location and ren Replaces the contents of a specified file with the file described by the current object, deleting the original file, and creating a backup of the replaced file. Also specifies whether to ignore merge errors. A object that encapsulates information about the file described by the parameter. - method replaces the contents of a specified file with the contents of the file described by the current object. It also creates a backup of the file that was replaced. Finally, it returns a new object that describes the overwritten file. - - Pass `null` to the `destBackupFileName` parameter if you do not want to create a backup of the file being replaced. - - - -## Examples - The following example uses the method to replace a file with another file and create a backup of the replaced file. - + method replaces the contents of a specified file with the contents of the file described by the current object. It also creates a backup of the file that was replaced. Finally, it returns a new object that describes the overwritten file. + + Pass `null` to the `destBackupFileName` parameter if you do not want to create a backup of the file being replaced. + + + +## Examples + The following example uses the method to replace a file with another file and create a backup of the replaced file. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/IO.FileInfo.Replace/cpp/sample.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.IO/FileInfo/Replace/sample.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/IO.FileInfo.Replace/VB/sample.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/IO.FileInfo.Replace/VB/sample.vb" id="Snippet1"::: + ]]> - The path described by the parameter was not of a legal form. - - -or- - + The path described by the parameter was not of a legal form. + + -or- + The path described by the parameter was not of a legal form. The parameter is . - The file described by the current object could not be found. - - -or- - + The file described by the current object could not be found. + + -or- + The file described by the parameter could not be found. The current operating system is not Microsoft Windows NT or later. @@ -2420,47 +2420,47 @@ The following example demonstrates moving a file to a different location and ren System.Void - + A object that describes an access control list (ACL) entry to apply to the current file. Applies access control list (ACL) entries described by a object to the file described by the current object. - method applies access control list (ACL) entries to the current file that represents the noninherited ACL list. - - Use the method whenever you need to add or remove ACL entries from a file. - + method applies access control list (ACL) entries to the current file that represents the noninherited ACL list. + + Use the method whenever you need to add or remove ACL entries from a file. + > [!CAUTION] -> The ACL specified for the `fileSecurity` parameter replaces the existing ACL for the file. To add permissions for a new user, use the method to obtain the existing ACL, modify it, and then use to apply it back to the file. - - An ACL describes individuals and/or groups who have, or do not have, rights to specific actions on the given file. For more information, see [How to: Add or Remove Access Control List Entries](/dotnet/standard/io/how-to-add-or-remove-access-control-list-entries). - - The method persists only objects that have been modified after object creation. If a object has not been modified, it will not be persisted to a file. Therefore, it is not possible to retrieve a object from one file and reapply the same object to another file. - - To copy ACL information from one file to another: - -1. Use the method to retrieve the object from the source file. - -2. Create a new object for the destination file. - -3. Use the or method of the source object to retrieve the ACL information. - -4. Use the or method to copy the information retrieved in step 3 to the destination object. - -5. Set the destination object to the destination file using the method. - - - -## Examples - The following code example uses the method and the method to add and then remove an ACL entry from a file. You must supply a valid user or group account to run this example. - +> The ACL specified for the `fileSecurity` parameter replaces the existing ACL for the file. To add permissions for a new user, use the method to obtain the existing ACL, modify it, and then use to apply it back to the file. + + An ACL describes individuals and/or groups who have, or do not have, rights to specific actions on the given file. For more information, see [How to: Add or Remove Access Control List Entries](/dotnet/standard/io/how-to-add-or-remove-access-control-list-entries). + + The method persists only objects that have been modified after object creation. If a object has not been modified, it will not be persisted to a file. Therefore, it is not possible to retrieve a object from one file and reapply the same object to another file. + + To copy ACL information from one file to another: + +1. Use the method to retrieve the object from the source file. + +2. Create a new object for the destination file. + +3. Use the or method of the source object to retrieve the ACL information. + +4. Use the or method to copy the information retrieved in step 3 to the destination object. + +5. Set the destination object to the destination file using the method. + + + +## Examples + The following code example uses the method and the method to add and then remove an ACL entry from a file. You must supply a valid user or group account to run this example. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/IO.FileInfo.GetAccessControl-SetAccessControl/cpp/sample.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.IO/FileInfo/GetAccessControl/sample.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/IO.FileInfo.GetAccessControl-SetAccessControl/VB/sample.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/IO.FileInfo.GetAccessControl-SetAccessControl/VB/sample.vb" id="Snippet1"::: + ]]> The parameter is . @@ -2509,15 +2509,15 @@ The following example demonstrates moving a file to a different location and ren Returns the original path that was passed to the constructor. Use the or property for the full path or file name. A string representing the path. - [!IMPORTANT] > The string returned by the method represents the path that was passed to the constructor. Instead of calling the `ToString` method, you should retrieve the value of either of the following properties, depending on your intent: > - , to get the name of the file, without any parent path information. > - [FullName](xref:System.IO.FileSystemInfo.FullName), to get the fully qualified path of the file. - + ]]> File and Stream I/O diff --git a/xml/System.IO/FileLoadException.xml b/xml/System.IO/FileLoadException.xml index 41c8740c591..6377c7fcaaa 100644 --- a/xml/System.IO/FileLoadException.xml +++ b/xml/System.IO/FileLoadException.xml @@ -64,34 +64,34 @@ The exception that is thrown when a managed assembly is found but cannot be loaded. - file is found but cannot be loaded. - - The exception is thrown when the file fails to load because it cannot be located. If the file is located, but cannot be loaded due to insufficient permissions, a is thrown. - - `FileLoadException` has the default HRESULT of COR_E_FILELOAD, which has the value 0x80131621, but this is not the only possible HRESULT. - + file is found but cannot be loaded. + + The exception is thrown when the file fails to load because it cannot be located. If the file is located, but cannot be loaded due to insufficient permissions, a is thrown. + + `FileLoadException` has the default HRESULT of COR_E_FILELOAD, which has the value 0x80131621, but this is not the only possible HRESULT. + The exact timing of when static assembly references are loaded is unspecified. This exception may be thrown before the method that statically references the assembly that failed to load starts executing. - + > [!NOTE] -> This exception is not included in the [.NET for Windows Store apps](https://go.microsoft.com/fwlink/?LinkID=247912) or the [Portable Class Library](/dotnet/standard/cross-platform/cross-platform-development-with-the-portable-class-library), but it is thrown by some members that are. To catch the exception in that case, write a `catch` statement for instead. - - **Associated Tips** - - **Make sure that the file is a valid .NET assembly.** - This exception is thrown if the file is not a valid .NET assembly. For more information, see . - - **Check to make sure an assembly or module was not loaded twice with two different evidences.** - Evidence is the set of information that constitutes input to security policy decisions, such as what permissions can be granted to code. For more information, see and - - **If using the or methods, check to make sure the assembly name is not longer than the system-defined maximum length.** - The assembly name's length cannot exceed the system-defined maximum. For more information, see . - - **If loading a satellite assembly, make sure the specified CultureInfo matches the file's CultureInfo.** - Satellite assemblies contain localized resources which contain non-localizable executable code and resources for a single culture that serve as the default or neutral culture. For more information, see . - +> This exception is not included in the [.NET for Windows Store apps](https://go.microsoft.com/fwlink/?LinkID=247912) or the [Portable Class Library](/dotnet/standard/cross-platform/cross-platform-development-with-the-portable-class-library), but it is thrown by some members that are. To catch the exception in that case, write a `catch` statement for instead. + + **Associated Tips** + + **Make sure that the file is a valid .NET assembly.** + This exception is thrown if the file is not a valid .NET assembly. For more information, see . + + **Check to make sure an assembly or module was not loaded twice with two different evidences.** + Evidence is the set of information that constitutes input to security policy decisions, such as what permissions can be granted to code. For more information, see and + + **If using the or methods, check to make sure the assembly name is not longer than the system-defined maximum length.** + The assembly name's length cannot exceed the system-defined maximum. For more information, see . + + **If loading a satellite assembly, make sure the specified CultureInfo matches the file's CultureInfo.** + Satellite assemblies contain localized resources which contain non-localizable executable code and resources for a single culture that serve as the default or neutral culture. For more information, see . + ]]> @@ -148,11 +148,11 @@ The exact timing of when static assembly references are loaded is unspecified. T Initializes a new instance of the class, setting the property of the new instance to a system-supplied message that describes the error, such as "Could not load the specified file." This message takes into account the current system culture. - property and property of the new instance are initialized to `null`. - + property and property of the new instance are initialized to `null`. + ]]> File and Stream I/O @@ -201,11 +201,11 @@ The exact timing of when static assembly references are loaded is unspecified. T A that describes the error. The content of is intended to be understood by humans. The caller of this constructor is required to ensure that this string has been localized for the current system culture. Initializes a new instance of the class with the specified error message. - property of the new instance using `message`. The property and property of the new instance are initialized to `null`. - + property of the new instance using `message`. The property and property of the new instance are initialized to `null`. + ]]> File and Stream I/O @@ -263,8 +263,8 @@ The exact timing of when static assembly references are loaded is unspecified. T - - + + The that holds the serialized object data about the exception being thrown. @@ -319,20 +319,20 @@ The exact timing of when static assembly references are loaded is unspecified. T The exception that is the cause of the current exception. If the parameter is not , the current exception is raised in a block that handles the inner exception. Initializes a new instance of the class with a specified error message and a reference to the inner exception that is the cause of this exception. - property. The `InnerException` property returns the same value that is passed into the constructor, or `null` if the `InnerException` property does not supply the inner exception value to the constructor. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||The inner exception reference.| -||The error message string.| - - For more information on inner exceptions, see . - + property. The `InnerException` property returns the same value that is passed into the constructor, or `null` if the `InnerException` property does not supply the inner exception value to the constructor. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||The inner exception reference.| +||The error message string.| + + For more information on inner exceptions, see . + ]]> @@ -385,13 +385,13 @@ The exact timing of when static assembly references are loaded is unspecified. T A containing the name of the file that was not loaded. Initializes a new instance of the class with a specified error message and the name of the file that could not be loaded. - property of the new instance using `message` and the property using `fileName`. The property of the new instance is initialized to `null`. - - is not required to be a file stored on disk; it can be any part of a system that supports access to streams. For example, depending on the system, this class might be able to access a physical device. - + property of the new instance using `message` and the property using `fileName`. The property of the new instance is initialized to `null`. + + is not required to be a file stored on disk; it can be any part of a system that supports access to streams. For example, depending on the system, this class might be able to access a physical device. + ]]> File and Stream I/O @@ -444,22 +444,22 @@ The exact timing of when static assembly references are loaded is unspecified. T The exception that is the cause of the current exception. If the parameter is not , the current exception is raised in a block that handles the inner exception. Initializes a new instance of the class with a specified error message, the name of the file that could not be loaded, and a reference to the inner exception that is the cause of this exception. - property. The `InnerException` property returns the same value that is passed into the constructor, or `null` if the `InnerException` property does not supply the inner exception value to the constructor. - - is not required to be a file stored on disk; it can be any part of a system that supports access to streams. For example, depending on the system, this class might be able to access a physical device. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||The inner exception reference.| -||The error message string.| - - For more information on inner exceptions, see . - + property. The `InnerException` property returns the same value that is passed into the constructor, or `null` if the `InnerException` property does not supply the inner exception value to the constructor. + + is not required to be a file stored on disk; it can be any part of a system that supports access to streams. For example, depending on the system, this class might be able to access a physical device. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||The inner exception reference.| +||The error message string.| + + For more information on inner exceptions, see . + ]]> @@ -510,13 +510,13 @@ The exact timing of when static assembly references are loaded is unspecified. T Gets the name of the file that causes this exception. A containing the name of the file with the invalid image, or a null reference if no file name was passed to the constructor for the current instance. - File and Stream I/O @@ -629,8 +629,8 @@ The exact timing of when static assembly references are loaded is unspecified. T System.Void - - + + The that holds the serialized object data about the exception being thrown. @@ -693,15 +693,15 @@ The exact timing of when static assembly references are loaded is unspecified. T Gets the error message and the name of the file that caused this exception. A string containing the error message and the name of the file that caused this exception. - . - - If no message was supplied to the constructor for the current exception, this property returns a system-supplied error message. If the property is not a null reference, the message includes the file name, for example, "Unable to load file a `FileName`." (a `FileName` represents the value returned by .) If is `null`, this is indicated in the system-supplied message as "(null)". The system-supplied message takes into account the current system culture. - - This property is read-only. - + . + + If no message was supplied to the constructor for the current exception, this property returns a system-supplied error message. If the property is not a null reference, the message includes the file name, for example, "Unable to load file a `FileName`." (a `FileName` represents the value returned by .) If is `null`, this is indicated in the system-supplied message as "(null)". The system-supplied message takes into account the current system culture. + + This property is read-only. + ]]> File and Stream I/O @@ -760,13 +760,13 @@ The exact timing of when static assembly references are loaded is unspecified. T Returns the fully qualified name of the current exception, and possibly the error message, the name of the inner exception, and the stack trace. A string containing the fully qualified name of this exception, and possibly the error message, the name of the inner exception, and the stack trace, depending on which constructor is used. - . - - The string representation returned by this method includes the name of the exception, the value of the the value of the property, and the result of calling . If any of these members is a null reference, its value is not included in the returned string. - + . + + The string representation returned by this method includes the name of the exception, the value of the the value of the property, and the result of calling . If any of these members is a null reference, its value is not included in the returned string. + ]]> File and Stream I/O diff --git a/xml/System.IO/FileNotFoundException.xml b/xml/System.IO/FileNotFoundException.xml index 6f975d0e1c8..e5ef81bd9ef 100644 --- a/xml/System.IO/FileNotFoundException.xml +++ b/xml/System.IO/FileNotFoundException.xml @@ -78,11 +78,11 @@ The exception that is thrown when an attempt to access a file that does not exist on disk fails. - @@ -143,11 +143,11 @@ Initializes a new instance of the class with its message string set to a system-supplied message. - property of the new instance to a system-supplied message that describes the error, such as "Could not find the specified file." This message takes into account the current system culture. - + property of the new instance to a system-supplied message that describes the error, such as "Could not find the specified file." This message takes into account the current system culture. + ]]> File and Stream I/O @@ -200,11 +200,11 @@ A description of the error. The content of is intended to be understood by humans. The caller of this constructor is required to ensure that this string has been localized for the current system culture. Initializes a new instance of the class with a specified error message. - property of the new instance using `message`. - + property of the new instance using `message`. + ]]> File and Stream I/O @@ -265,8 +265,8 @@ - - + + An object that holds the serialized object data about the exception being thrown. @@ -325,20 +325,20 @@ The exception that is the cause of the current exception. If the parameter is not , the current exception is raised in a block that handles the inner exception. Initializes a new instance of the class with a specified error message and a reference to the inner exception that is the cause of this exception. - property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||The inner exception reference.| -||The error message string.| - - For more information on inner exceptions, see . - + property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||The inner exception reference.| +||The error message string.| + + For more information on inner exceptions, see . + ]]> @@ -395,11 +395,11 @@ The full name of the file with the invalid image. Initializes a new instance of the class with a specified error message, and the file name that cannot be found. - property of the new instance using `message` and the property using `fileName`. - + property of the new instance using `message` and the property using `fileName`. + ]]> File and Stream I/O @@ -456,20 +456,20 @@ The exception that is the cause of the current exception. If the parameter is not , the current exception is raised in a block that handles the inner exception. Initializes a new instance of the class with a specified error message, the file name that cannot be found, and a reference to the inner exception that is the cause of this exception. - property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||The inner exception reference.| -||The error message string.| - - For more information on inner exceptions, see . - + property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||The inner exception reference.| +||The error message string.| + + For more information on inner exceptions, see . + ]]> @@ -524,11 +524,11 @@ Gets the name of the file that cannot be found. The name of the file, or if no file name was passed to the constructor for this instance. - File and Stream I/O @@ -646,8 +646,8 @@ System.Void - - + + The object that holds the serialized object data about the exception being thrown. @@ -713,13 +713,13 @@ Gets the error message that explains the reason for the exception. The error message. - property is not `null`, the message includes the file name. - - This property is read-only. - + property is not `null`, the message includes the file name. + + This property is read-only. + ]]> File and Stream I/O @@ -782,13 +782,13 @@ Returns the fully qualified name of this exception and possibly the error message, the name of the inner exception, and the stack trace. The fully qualified name of this exception and possibly the error message, the name of the inner exception, and the stack trace. - . - - The string representation returned by this method includes the name of the exception, the value of the property, the result of calling ToString on the inner exception, the value of the property, and the result of calling . If any of these members is a null reference, its value is not included in the returned string. - + . + + The string representation returned by this method includes the name of the exception, the value of the property, the result of calling ToString on the inner exception, the value of the property, and the result of calling . If any of these members is a null reference, its value is not included in the returned string. + ]]> File and Stream I/O diff --git a/xml/System.IO/FileStream.xml b/xml/System.IO/FileStream.xml index 9e93b0ded49..fe4a7551555 100644 --- a/xml/System.IO/FileStream.xml +++ b/xml/System.IO/FileStream.xml @@ -241,8 +241,8 @@ - - + + A file handle for the file that the current object will encapsulate. @@ -613,9 +613,9 @@ The file was too large (when - - + + + A file handle for the file that the current object will encapsulate. @@ -902,10 +902,10 @@ The file was too large (when - - - + + + + A file handle for the file that this object will encapsulate. @@ -1114,11 +1114,11 @@ The file was too large (when - - - - + + + + + A file handle for the file that this object will encapsulate. @@ -1538,12 +1538,12 @@ The file was too large (when - - - - - + + + + + + A relative or absolute path for the file that the current object will encapsulate. @@ -1641,13 +1641,13 @@ The file was too large (when - - - - - - + + + + + + + A relative or absolute path for the file that the current object will encapsulate. @@ -1785,10 +1785,10 @@ The file was too large (when + - - + + @@ -1798,7 +1798,7 @@ The file was too large (when + @@ -1807,7 +1807,7 @@ The file was too large (when + The buffer to read data into. @@ -1887,10 +1887,10 @@ The file was too large (when + - - + + @@ -1900,7 +1900,7 @@ The file was too large (when + @@ -1909,7 +1909,7 @@ The file was too large (when + The buffer containing data to write to the current stream. @@ -2451,7 +2451,7 @@ Calling `DisposeAsync` allows the resources used by the System.Int32 - + The reference to the pending asynchronous request to wait for. @@ -2537,7 +2537,7 @@ Calling `DisposeAsync` allows the resources used by the System.Void - + The pending asynchronous I/O request. @@ -3198,8 +3198,8 @@ Calling `DisposeAsync` allows the resources used by the System.Void - - + + The beginning of the range to lock. The value of this parameter must be equal to or greater than zero (0). @@ -3984,7 +3984,7 @@ The following example shows how to read from a file asynchronously. System.Void - + An object that describes an ACL entry to apply to the current file. @@ -4146,8 +4146,8 @@ The following example shows how to read from a file asynchronously. System.Void - - + + The beginning of the range to unlock. diff --git a/xml/System.IO/FileSystemInfo.xml b/xml/System.IO/FileSystemInfo.xml index 279a1cdf5f4..654d96eaa23 100644 --- a/xml/System.IO/FileSystemInfo.xml +++ b/xml/System.IO/FileSystemInfo.xml @@ -81,34 +81,34 @@ Provides the base class for both and objects. - class contains methods that are common to file and directory manipulation. A object can represent either a file or a directory, thus serving as the basis for or objects. Use this base class when parsing a lot of files and directories. - - A derived class can inherit from only if the derived class has the AllAccess permission from the enumeration. - - In members that accept a path, the path can refer to a file or just a directory. The specified path can also refer to a relative path or a Universal Naming Convention (UNC) path for a server and share name. For example, all the following are acceptable paths: - -- "c:\\\MyDir\\\MyFile.txt" in C#, or "c:\MyDir\MyFile.txt" in Visual Basic. - -- "c:\\\MyDir" in C#, or "c:\MyDir" in Visual Basic. - -- "MyDir\\\MySubdir" in C#, or "MyDir\MySubDir" in Visual Basic. - -- "\\\\\\\MyServer\\\MyShare" in C#, or "\\\MyServer\MyShare" in Visual Basic. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following example shows how to loop through all the files and directories, querying some information about each entry. - + class contains methods that are common to file and directory manipulation. A object can represent either a file or a directory, thus serving as the basis for or objects. Use this base class when parsing a lot of files and directories. + + A derived class can inherit from only if the derived class has the AllAccess permission from the enumeration. + + In members that accept a path, the path can refer to a file or just a directory. The specified path can also refer to a relative path or a Universal Naming Convention (UNC) path for a server and share name. For example, all the following are acceptable paths: + +- "c:\\\MyDir\\\MyFile.txt" in C#, or "c:\MyDir\MyFile.txt" in Visual Basic. + +- "c:\\\MyDir" in C#, or "c:\MyDir" in Visual Basic. + +- "MyDir\\\MySubdir" in C#, or "MyDir\MySubDir" in Visual Basic. + +- "\\\\\\\MyServer\\\MyShare" in C#, or "\\\MyServer\MyShare" in Visual Basic. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following example shows how to loop through all the files and directories, querying some information about each entry. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/FileSystemInfo/cpp/program.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.IO/FileSystemInfo/Overview/program.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/FileSystemInfo/VB/FileSystemInfo.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/FileSystemInfo/VB/FileSystemInfo.vb" id="Snippet1"::: + ]]> @@ -168,11 +168,11 @@ Initializes a new instance of the class. - @@ -226,19 +226,19 @@ - - + + The that holds the serialized object data about the exception being thrown. The that contains contextual information about the source or destination. Initializes a new instance of the class with serialized data. - The specified is null. @@ -302,42 +302,42 @@ of the current . - property is pre-cached if the current instance of the object was returned from any of the following methods: - -- - -- - -- - -- - -- - -- - + property is pre-cached if the current instance of the object was returned from any of the following methods: + +- + +- + +- + +- + +- + +- + The value may be cached when either the value itself or other properties are accessed. To get the latest value, call the method. If the path doesn't exist as of the last cached state, the return value is `(FileAttributes)(-1)`. or can only be thrown when setting the value. - - The value of this property is a combination of the archive, compressed, directory, hidden, offline, read-only, system, and temporary file attribute flags. - - When you set this value, use the bitwise OR operator (`|` in C# or `Or` in Visual Basic) to apply more than one value. To retain any existing values in the property, include the value of the property in your assignment. For example: - - `exampleFile.Attributes = exampleFile.Attributes | FileAttributes.ReadOnly;` - - - -## Examples - The following example demonstrates the property. This code example is part of a larger example provided for the class. - + + The value of this property is a combination of the archive, compressed, directory, hidden, offline, read-only, system, and temporary file attribute flags. + + When you set this value, use the bitwise OR operator (`|` in C# or `Or` in Visual Basic) to apply more than one value. To retain any existing values in the property, include the value of the property in your assignment. For example: + + `exampleFile.Attributes = exampleFile.Attributes | FileAttributes.ReadOnly;` + + + +## Examples + The following example demonstrates the property. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/FileSystemInfo/cpp/program.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.IO/FileSystemInfo/Overview/program.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/FileSystemInfo/VB/FileSystemInfo.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/FileSystemInfo/VB/FileSystemInfo.vb" id="Snippet2"::: + ]]> The specified file doesn't exist. Only thrown when setting the property value. @@ -345,10 +345,10 @@ The caller doesn't have the required permission. .NET Core and .NET 5+ only: The user attempts to set an attribute value but doesn't have write permission. The specified path, file name, or both exceed the system-defined maximum length. - The caller attempts to set an invalid file attribute. - - -or- - + The caller attempts to set an invalid file attribute. + + -or- + .NET Framework only: The user attempts to set an attribute value but doesn't have write permission. cannot initialize the data. @@ -458,42 +458,42 @@ An I/O error occurred. Gets or sets the creation time of the current file or directory. The creation date and time of the current object. - [!NOTE] -> This method may return an inaccurate value because it uses native functions whose values may not be continuously updated by the operating system. - - The value of the property is pre-cached if the current instance of the object was returned from any of the following methods: - -- - -- - -- - -- - -- - -- - - To get the latest value, call the method. - - If the file described in the object does not exist, this property returns 12:00 midnight, January 1, 1601 A.D. (C.E.) Coordinated Universal Time (UTC), adjusted to local time. +> This method may return an inaccurate value because it uses native functions whose values may not be continuously updated by the operating system. + + The value of the property is pre-cached if the current instance of the object was returned from any of the following methods: + +- + +- + +- + +- + +- + +- + + To get the latest value, call the method. + + If the file described in the object does not exist, this property returns 12:00 midnight, January 1, 1601 A.D. (C.E.) Coordinated Universal Time (UTC), adjusted to local time. On Unix platforms that do not support creation or birth time, this property returns the older of the time of the last status change and the time of the last modification. On other platforms, it returns 12:00 midnight, January 1, 1601 A.D. (C.E.) Coordinated Universal Time (UTC), adjusted to local time. - NTFS-formatted drives may cache file meta-info, such as file creation time, for a short period of time. This process is known as file tunneling. As a result, it may be necessary to explicitly set the creation time of a file if you are overwriting or replacing an existing file. - -## Examples - The following example demonstrates the property. This code example is part of a larger example provided for the class. - + NTFS-formatted drives may cache file meta-info, such as file creation time, for a short period of time. This process is known as file tunneling. As a result, it may be necessary to explicitly set the creation time of a file if you are overwriting or replacing an existing file. + +## Examples + The following example demonstrates the property. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/FileSystemInfo/cpp/program.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.IO/FileSystemInfo/Overview/program.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/FileSystemInfo/VB/FileSystemInfo.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/FileSystemInfo/VB/FileSystemInfo.vb" id="Snippet2"::: + ]]> @@ -560,35 +560,35 @@ On Unix platforms that do not support creation or birth time, this property retu Gets or sets the creation time, in coordinated universal time (UTC), of the current file or directory. The creation date and time in UTC format of the current object. - [!NOTE] -> This method may return an inaccurate value because it uses native functions whose values may not be continuously updated by the operating system. - - The value of the property is pre-cached if the current instance of the object was returned from any of the following methods: - -- - -- - -- - -- - -- - -- - - To get the latest value, call the method. - - If the file described in the object does not exist, this property returns 12:00 midnight, January 1, 1601 A.D. (C.E.) Coordinated Universal Time (UTC). +> This method may return an inaccurate value because it uses native functions whose values may not be continuously updated by the operating system. + + The value of the property is pre-cached if the current instance of the object was returned from any of the following methods: + +- + +- + +- + +- + +- + +- + + To get the latest value, call the method. + + If the file described in the object does not exist, this property returns 12:00 midnight, January 1, 1601 A.D. (C.E.) Coordinated Universal Time (UTC). On Unix platforms that do not support creation or birth time, this property returns the older of the time of the last status change and the time of the last modification. On other platforms, it returns 12:00 midnight, January 1, 1601 A.D. (C.E.) Coordinated Universal Time (UTC), adjusted to local time. - NTFS-formatted drives may cache file meta-info, such as file creation time, for a short period of time. This process is known as file tunneling. As a result, it may be necessary to explicitly set the creation time of a file if you are overwriting or replacing an existing file. - + NTFS-formatted drives may cache file meta-info, such as file creation time, for a short period of time. This process is known as file tunneling. As a result, it may be necessary to explicitly set the creation time of a file if you are overwriting or replacing an existing file. + ]]> @@ -697,11 +697,11 @@ On Unix platforms that do not support creation or birth time, this property retu if the file or directory exists; otherwise, . - @@ -753,29 +753,29 @@ On Unix platforms that do not support creation or birth time, this property retu Gets the extension part of the file name, including the leading dot . even if it is the entire file name, or an empty string if no extension is present. A string containing the extension. - extension, which starts at, and includes, the last dot (`.`) in the file's full name. For example: - + * For a file `c:\NewFile.txt`, this property returns `".txt"`. * For a file `c:\.gitignore`, this property returns `".gitignore"`. * For a file `c:\noextension`, this property returns an empty string `""`. * For a file `c:\a.b.c`, this property returns `".c"`. * When the `FileInfo` is constructed from a file path with a trailing dot, then that trailing dot is trimmed, so `new FileInfo("foo.bar.").Extension` returns `".bar"`. - - The following table lists examples of other typical or related I/O tasks. - -|To do this...|See the example in this topic...| -|-------------------|--------------------------------------| -|Create a text file.|[How to: Write Text to a File](/dotnet/standard/io/how-to-write-text-to-a-file)| -|Write to a text file.|[How to: Write Text to a File](/dotnet/standard/io/how-to-write-text-to-a-file)| -|Read from a text file.|[How to: Read Text from a File](/dotnet/standard/io/how-to-read-text-from-a-file)| -|Retrieve the fully qualified path of a file.|| -|Retrieve only the file name a path.|| -|Retrieve only the directory name from a path.|| -|Change the extension of a file.|| - + + The following table lists examples of other typical or related I/O tasks. + +|To do this...|See the example in this topic...| +|-------------------|--------------------------------------| +|Create a text file.|[How to: Write Text to a File](/dotnet/standard/io/how-to-write-text-to-a-file)| +|Write to a text file.|[How to: Write Text to a File](/dotnet/standard/io/how-to-write-text-to-a-file)| +|Read from a text file.|[How to: Read Text from a File](/dotnet/standard/io/how-to-read-text-from-a-file)| +|Retrieve the fully qualified path of a file.|| +|Retrieve only the file name a path.|| +|Retrieve only the directory name from a path.|| +|Change the extension of a file.|| + ]]> @@ -833,22 +833,22 @@ The `Extension` property returns the extension, Gets the full path of the directory or file. A string containing the full path. - property. This code example is part of a larger example provided for the class. - + property. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/FileSystemInfo/cpp/program.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.IO/FileSystemInfo/Overview/program.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/FileSystemInfo/VB/FileSystemInfo.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/FileSystemInfo/VB/FileSystemInfo.vb" id="Snippet2"::: + ]]> The fully qualified path and file name exceed the system-defined maximum length. @@ -903,8 +903,8 @@ The `Extension` property returns the extension, To be added. The fully qualified path exceeds the system-defined maximum length. - Classes derived from can use the field to determine the full path of the object being manipulated. - + Classes derived from can use the field to determine the full path of the object being manipulated. + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -972,19 +972,19 @@ The `Extension` property returns the extension, System.Void - - + + The that holds the serialized object data about the exception being thrown. The that contains contextual information about the source or destination. Sets the object with the file name and additional exception information. - @@ -1042,39 +1042,39 @@ The `Extension` property returns the extension, Gets or sets the time the current file or directory was last accessed. The time that the current file or directory was last accessed. - [!NOTE] -> This method may return an inaccurate value because it uses native functions whose values may not be continuously updated by the operating system. - - If the file described in the object does not exist, this property returns 12:00 midnight, January 1, 1601 A.D. (C.E.) Coordinated Universal Time (UTC), adjusted to local time. - - The value of the property is pre-cached if the current instance of the object was returned from any of the following methods: - -- - -- - -- - -- - -- - -- - - To get the latest value, call the method. - - - -## Examples - The following code example demonstrates the updating of the property through a "touch" operation. In this example, the file is "touched", updating the , and properties to the current date and time. - +> This method may return an inaccurate value because it uses native functions whose values may not be continuously updated by the operating system. + + If the file described in the object does not exist, this property returns 12:00 midnight, January 1, 1601 A.D. (C.E.) Coordinated Universal Time (UTC), adjusted to local time. + + The value of the property is pre-cached if the current instance of the object was returned from any of the following methods: + +- + +- + +- + +- + +- + +- + + To get the latest value, call the method. + + + +## Examples + The following code example demonstrates the updating of the property through a "touch" operation. In this example, the file is "touched", updating the , and properties to the current date and time. + :::code language="csharp" source="~/snippets/csharp/System.IO/FileSystemInfo/LastAccessTime/touch.cs" id="Snippet00"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.FileSystemInfo_touch/vb/touch.vb" id="Snippet00"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.FileSystemInfo_touch/vb/touch.vb" id="Snippet00"::: + ]]> @@ -1140,33 +1140,33 @@ The `Extension` property returns the extension, Gets or sets the time, in coordinated universal time (UTC), that the current file or directory was last accessed. The UTC time that the current file or directory was last accessed. - [!NOTE] -> This method may return an inaccurate value because it uses native functions whose values may not be continuously updated by the operating system. - - The value of the property is pre-cached if the current instance of the object was returned from any of the following methods: - -- - -- - -- - -- - -- - -- - - To get the latest value, call the method. - - If the file described in the object does not exist, this property returns 12:00 midnight, January 1, 1601 A.D. (C.E.) Coordinated Universal Time (UTC). - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - +> This method may return an inaccurate value because it uses native functions whose values may not be continuously updated by the operating system. + + The value of the property is pre-cached if the current instance of the object was returned from any of the following methods: + +- + +- + +- + +- + +- + +- + + To get the latest value, call the method. + + If the file described in the object does not exist, this property returns 12:00 midnight, January 1, 1601 A.D. (C.E.) Coordinated Universal Time (UTC). + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + ]]> @@ -1228,37 +1228,37 @@ The `Extension` property returns the extension, Gets or sets the time when the current file or directory was last written to. The time the current file was last written. - [!NOTE] -> This method may return an inaccurate value because it uses native functions whose values may not be continuously updated by the operating system. - - The value of the property is pre-cached if the current instance of the object was returned from any of the following methods: - -- - -- - -- - -- - -- - -- - - To get the latest value, call the method. - - If the file or directory described in the object does not exist, or if the file system that contains this file or directory does not support this information, this property returns 12:00 midnight, January 1, 1601 A.D. (C.E.) Coordinated Universal Time (UTC), adjusted to local time. - -## Examples - The following code example demonstrates the updating of the property through a "touch" operation. In this example, the file is "touched", updating the , and properties to the current date and time. - +> This method may return an inaccurate value because it uses native functions whose values may not be continuously updated by the operating system. + + The value of the property is pre-cached if the current instance of the object was returned from any of the following methods: + +- + +- + +- + +- + +- + +- + + To get the latest value, call the method. + + If the file or directory described in the object does not exist, or if the file system that contains this file or directory does not support this information, this property returns 12:00 midnight, January 1, 1601 A.D. (C.E.) Coordinated Universal Time (UTC), adjusted to local time. + +## Examples + The following code example demonstrates the updating of the property through a "touch" operation. In this example, the file is "touched", updating the , and properties to the current date and time. + :::code language="csharp" source="~/snippets/csharp/System.IO/FileSystemInfo/LastAccessTime/touch.cs" id="Snippet00"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.FileSystemInfo_touch/vb/touch.vb" id="Snippet00"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.FileSystemInfo_touch/vb/touch.vb" id="Snippet00"::: + ]]> @@ -1324,30 +1324,30 @@ The `Extension` property returns the extension, Gets or sets the time, in coordinated universal time (UTC), when the current file or directory was last written to. The UTC time when the current file was last written to. - [!NOTE] -> This method may return an inaccurate value because it uses native functions whose values may not be continuously updated by the operating system. - - The value of the property is pre-cached if the current instance of the object was returned from any of the following methods: - -- - -- - -- - -- - -- - -- - - To get the latest value, call the method. - - If the file or directory described in the object does not exist, or if the file system that contains this file or directory does not support this information, this property returns 12:00 midnight, January 1, 1601 A.D. (C.E.) Coordinated Universal Time (UTC). +> This method may return an inaccurate value because it uses native functions whose values may not be continuously updated by the operating system. + + The value of the property is pre-cached if the current instance of the object was returned from any of the following methods: + +- + +- + +- + +- + +- + +- + + To get the latest value, call the method. + + If the file or directory described in the object does not exist, or if the file system that contains this file or directory does not support this information, this property returns 12:00 midnight, January 1, 1601 A.D. (C.E.) Coordinated Universal Time (UTC). ]]> @@ -1449,13 +1449,13 @@ The `Extension` property returns the extension, For files, gets the name of the file. For directories, gets the name of the last directory in the hierarchy if a hierarchy exists. Otherwise, the property gets the name of the directory. A string that is the name of the parent directory, the name of the last directory in the hierarchy, or the name of a file, including the file name extension. - @@ -1506,11 +1506,11 @@ The `Extension` property returns the extension, The path originally specified by the user, whether relative or absolute. - @@ -1568,8 +1568,8 @@ The `Extension` property returns the extension, Refreshes the state of the object. - ## Remarks The value may be cached when either the value itself or other properties are accessed. To get the latest value, call the method. - + If the path doesn't exist as of the last cached state, the return value is `(UnixFileMode)(-1)`. or can only be thrown when setting the value. ]]> diff --git a/xml/System.IO/IOException.xml b/xml/System.IO/IOException.xml index 3182f05f9ef..40f5a96887e 100644 --- a/xml/System.IO/IOException.xml +++ b/xml/System.IO/IOException.xml @@ -84,36 +84,36 @@ The exception that is thrown when an I/O error occurs. - is the base class for exceptions thrown while accessing information using streams, files and directories. - - The Base Class Library includes the following types, each of which is a derived class of `IOException` : - -- - -- - -- - -- - -- - - Where appropriate, use these types instead of IOException. - - uses the HRESULT COR_E_IO which has the value 0x80131620. - - - -## Examples - This code example is part of a larger example provided for the method. - + is the base class for exceptions thrown while accessing information using streams, files and directories. + + The Base Class Library includes the following types, each of which is a derived class of `IOException` : + +- + +- + +- + +- + +- + + Where appropriate, use these types instead of IOException. + + uses the HRESULT COR_E_IO which has the value 0x80131620. + + + +## Examples + This code example is part of a larger example provided for the method. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.FileStream3/CPP/fstreamlock.cpp" id="Snippet6"::: :::code language="csharp" source="~/snippets/csharp/System.IO/FileStream/.ctor/fstreamlock.cs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.FileStream3/VB/fstreamlock.vb" id="Snippet6"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.FileStream3/VB/fstreamlock.vb" id="Snippet6"::: + ]]> @@ -174,11 +174,11 @@ Initializes a new instance of the class with its message string set to the empty string (""), its HRESULT set to COR_E_IO, and its inner exception set to a null reference. - property of the new instance to a system-supplied message that describes the error, such as "An I/O error occurred while performing the requested operation." This message takes into account the current system culture. - + property of the new instance to a system-supplied message that describes the error, such as "An I/O error occurred while performing the requested operation." This message takes into account the current system culture. + ]]> File and Stream I/O @@ -231,11 +231,11 @@ A that describes the error. The content of is intended to be understood by humans. The caller of this constructor is required to ensure that this string has been localized for the current system culture. Initializes a new instance of the class with its message string set to , its HRESULT set to COR_E_IO, and its inner exception set to . - property of the new instance using `message`. - + property of the new instance using `message`. + ]]> File and Stream I/O @@ -296,8 +296,8 @@ - - + + The data for serializing or deserializing the object. @@ -356,20 +356,20 @@ The exception that is the cause of the current exception. If the parameter is not , the current exception is raised in a block that handles the inner exception. Initializes a new instance of the class with a specified error message and a reference to the inner exception that is the cause of this exception. - property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||The inner exception reference.| -||The error message string.| - - For more information on inner exceptions, see . - + property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||The inner exception reference.| +||The error message string.| + + For more information on inner exceptions, see . + ]]> diff --git a/xml/System.IO/Path.xml b/xml/System.IO/Path.xml index 9d5eab7f94b..34accf4bc51 100644 --- a/xml/System.IO/Path.xml +++ b/xml/System.IO/Path.xml @@ -612,10 +612,10 @@ If any element in `paths` but the last one is not a drive and does not end with System.String - - - - + + + + The first path to combine. diff --git a/xml/System.IO/PathTooLongException.xml b/xml/System.IO/PathTooLongException.xml index 4bba8dcd9c0..d838243a166 100644 --- a/xml/System.IO/PathTooLongException.xml +++ b/xml/System.IO/PathTooLongException.xml @@ -64,38 +64,38 @@ The exception that is thrown when a path or fully qualified file name is longer than the system-defined maximum length. - . For more information about this restriction, see the entry [Long Paths in .NET](https://go.microsoft.com/fwlink/?LinkID=163666) in the BCL Team blog. - + . For more information about this restriction, see the entry [Long Paths in .NET](https://go.microsoft.com/fwlink/?LinkID=163666) in the BCL Team blog. + > [!NOTE] -> This exception is not included in [.NET for Windows Store apps](https://go.microsoft.com/fwlink/?LinkID=247912) or the [Portable Class Library](/dotnet/standard/cross-platform/cross-platform-development-with-the-portable-class-library), but it is thrown by some members that are. To catch the exception in that case, write a `catch` statement that handles an instead. - - Starting with apps running under the .NET Framework 4.6.2, the .NET Framework supports long paths in excess of 260 (or `MAX_PATH`) characters. The conditions under which a exception are thrown depend on the version of the .NET Framework that an app targets: - - **Apps that target the .NET Framework 4.6.2 and later versions** - Long paths are supported by default. The runtime throws a under the following conditions: - -- The operating system returns `COR_E_PATHTOOLONG` or its equivalent. - -- The length of the path exceeds (32,767) characters. - - **Apps that target the .NET Framework 4.6.1 and earlier versions** - Long paths are disabled by default, and the legacy behavior is maintained. The runtime throws a whenever a path exceeds 260 characters. - - If this is undesirable, apps that target the .NET Framework 4.6.1 and earlier but run under the .NET Framework 4.6.2 can enable long path support by including the following setting in the [\](/dotnet/framework/configure-apps/file-schema/runtime/runtime-element) element of the application configuration file: - -```xml - - - - - -``` - - uses the HRESULT `COR_E_PATHTOOLONG`, which has the value 0x800700CE. - +> This exception is not included in [.NET for Windows Store apps](https://go.microsoft.com/fwlink/?LinkID=247912) or the [Portable Class Library](/dotnet/standard/cross-platform/cross-platform-development-with-the-portable-class-library), but it is thrown by some members that are. To catch the exception in that case, write a `catch` statement that handles an instead. + + Starting with apps running under the .NET Framework 4.6.2, the .NET Framework supports long paths in excess of 260 (or `MAX_PATH`) characters. The conditions under which a exception are thrown depend on the version of the .NET Framework that an app targets: + + **Apps that target the .NET Framework 4.6.2 and later versions** + Long paths are supported by default. The runtime throws a under the following conditions: + +- The operating system returns `COR_E_PATHTOOLONG` or its equivalent. + +- The length of the path exceeds (32,767) characters. + + **Apps that target the .NET Framework 4.6.1 and earlier versions** + Long paths are disabled by default, and the legacy behavior is maintained. The runtime throws a whenever a path exceeds 260 characters. + + If this is undesirable, apps that target the .NET Framework 4.6.1 and earlier but run under the .NET Framework 4.6.2 can enable long path support by including the following setting in the [\](/dotnet/framework/configure-apps/file-schema/runtime/runtime-element) element of the application configuration file: + +```xml + + + + + +``` + + uses the HRESULT `COR_E_PATHTOOLONG`, which has the value 0x800700CE. + ]]> @@ -152,11 +152,11 @@ Initializes a new instance of the class with its HRESULT set to COR_E_PATHTOOLONG. - property of the new instance to a system-supplied message that describes the error, such as "The supplied path is too long." This message takes into account the current system culture. - + property of the new instance to a system-supplied message that describes the error, such as "The supplied path is too long." This message takes into account the current system culture. + ]]> File and Stream I/O @@ -205,11 +205,11 @@ A that describes the error. The content of is intended to be understood by humans. The caller of this constructor is required to ensure that this string has been localized for the current system culture. Initializes a new instance of the class with its message string set to and its HRESULT set to COR_E_PATHTOOLONG. - property of the new instance using `message`. - + property of the new instance using `message`. + ]]> File and Stream I/O @@ -267,8 +267,8 @@ - - + + The that holds the serialized object data about the exception being thrown. @@ -323,20 +323,20 @@ The exception that is the cause of the current exception. If the parameter is not , the current exception is raised in a block that handles the inner exception. Initializes a new instance of the class with a specified error message and a reference to the inner exception that is the cause of this exception. - property. The `InnerException` property returns the same value that is passed into the constructor, or `null` if the `InnerException` property does not supply the inner exception value to the constructor. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||The inner exception reference.| -||The error message string.| - - For more information on inner exceptions, see . - + property. The `InnerException` property returns the same value that is passed into the constructor, or `null` if the `InnerException` property does not supply the inner exception value to the constructor. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||The inner exception reference.| +||The error message string.| + + For more information on inner exceptions, see . + ]]> diff --git a/xml/System.IO/Stream.xml b/xml/System.IO/Stream.xml index 2aaa3ee7e4c..e06a792ad1d 100644 --- a/xml/System.IO/Stream.xml +++ b/xml/System.IO/Stream.xml @@ -94,50 +94,50 @@ Provides a generic view of a sequence of bytes. This is an abstract class. - is the abstract base class of all streams. A stream is an abstraction of a sequence of bytes, such as a file, an input/output device, an inter-process communication pipe, or a TCP/IP socket. The class and its derived classes provide a generic view of these different types of input and output, and isolate the programmer from the specific details of the operating system and the underlying devices. - - Streams involve three fundamental operations: - -- You can read from streams. Reading is the transfer of data from a stream into a data structure, such as an array of bytes. - -- You can write to streams. Writing is the transfer of data from a data structure into a stream. - -- Streams can support seeking. Seeking refers to querying and modifying the current position within a stream. Seek capability depends on the kind of backing store a stream has. For example, network streams have no unified concept of a current position, and therefore typically do not support seeking. - - Some of the more commonly used streams that inherit from are , and . - - Depending on the underlying data source or repository, streams might support only some of these capabilities. You can query a stream for its capabilities by using the , , and properties of the class. - - The and methods read and write data in a variety of formats. For streams that support seeking, use the and methods and the and properties to query and modify the current position and length of a stream. - - 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. - - Disposing a object flushes any buffered data, and essentially calls the method for you. also releases operating system resources such as file handles, network connections, or memory used for any internal buffering. The class provides the capability of wrapping a buffered stream around another stream in order to improve read and write performance. - - Starting with the .NET Framework 4.5, the class includes async methods to simplify asynchronous operations. An async method contains `Async` in its name, such as , , , and . These methods enable you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in a Windows 8.x Store app or desktop app where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#. - - When used in a Windows 8.x Store app, includes two extension methods: and . These methods convert a object to a stream in the Windows Runtime. You can also convert a stream in the Windows Runtime to a object by using the and methods. For more information, see [How to: Convert Between .NET Framework Streams and Windows Runtime Streams](/dotnet/standard/io/how-to-convert-between-dotnet-streams-and-winrt-streams) - - Some stream implementations perform local buffering of the underlying data to improve performance. For such streams, you can use the or method to clear any internal buffers and ensure that all data has been written to the underlying data source or repository. - - If you need a stream with no backing store (also known as a bit bucket), use the field to retrieve an instance of a stream that is designed for this purpose. - - - -## Examples - The following example demonstrates how to use two objects to asynchronously copy the files from one directory to another directory. The class derives from the class. Notice that the event handler for the control is marked with the `async` modifier because it calls an asynchronous method. - + is the abstract base class of all streams. A stream is an abstraction of a sequence of bytes, such as a file, an input/output device, an inter-process communication pipe, or a TCP/IP socket. The class and its derived classes provide a generic view of these different types of input and output, and isolate the programmer from the specific details of the operating system and the underlying devices. + + Streams involve three fundamental operations: + +- You can read from streams. Reading is the transfer of data from a stream into a data structure, such as an array of bytes. + +- You can write to streams. Writing is the transfer of data from a data structure into a stream. + +- Streams can support seeking. Seeking refers to querying and modifying the current position within a stream. Seek capability depends on the kind of backing store a stream has. For example, network streams have no unified concept of a current position, and therefore typically do not support seeking. + + Some of the more commonly used streams that inherit from are , and . + + Depending on the underlying data source or repository, streams might support only some of these capabilities. You can query a stream for its capabilities by using the , , and properties of the class. + + The and methods read and write data in a variety of formats. For streams that support seeking, use the and methods and the and properties to query and modify the current position and length of a stream. + + 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. + + Disposing a object flushes any buffered data, and essentially calls the method for you. also releases operating system resources such as file handles, network connections, or memory used for any internal buffering. The class provides the capability of wrapping a buffered stream around another stream in order to improve read and write performance. + + Starting with the .NET Framework 4.5, the class includes async methods to simplify asynchronous operations. An async method contains `Async` in its name, such as , , , and . These methods enable you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in a Windows 8.x Store app or desktop app where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#. + + When used in a Windows 8.x Store app, includes two extension methods: and . These methods convert a object to a stream in the Windows Runtime. You can also convert a stream in the Windows Runtime to a object by using the and methods. For more information, see [How to: Convert Between .NET Framework Streams and Windows Runtime Streams](/dotnet/standard/io/how-to-convert-between-dotnet-streams-and-winrt-streams) + + Some stream implementations perform local buffering of the underlying data to improve performance. For such streams, you can use the or method to clear any internal buffers and ensure that all data has been written to the underlying data source or repository. + + If you need a stream with no backing store (also known as a bit bucket), use the field to retrieve an instance of a stream that is designed for this purpose. + + + +## Examples + The following example demonstrates how to use two objects to asynchronously copy the files from one directory to another directory. The class derives from the class. Notice that the event handler for the control is marked with the `async` modifier because it calls an asynchronous method. + :::code language="csharp" source="~/snippets/csharp/System.IO/FileStream/Overview/example.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Asynchronous_File_IO_async/vb/example.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Asynchronous_File_IO_async/vb/example.vb" id="Snippet1"::: + ]]> - When you implement a derived class of , you must provide implementations for the and methods. The asynchronous methods , , and use the synchronous methods and in their implementations. Therefore, your implementations of and will work correctly with the asynchronous methods. The default implementations of and create a new single-element byte array, and then call your implementations of and . When you derive from , we recommend that you override these methods to access your internal buffer, if you have one, for substantially better performance. You must also provide implementations of , , , , , , , and . - + When you implement a derived class of , you must provide implementations for the and methods. The asynchronous methods , , and use the synchronous methods and in their implementations. Therefore, your implementations of and will work correctly with the asynchronous methods. The default implementations of and create a new single-element byte array, and then call your implementations of and . When you derive from , we recommend that you override these methods to access your internal buffer, if you have one, for substantially better performance. You must also provide implementations of , , , , , , , and . + Do not override the method, instead, put all the cleanup logic in the method. For more information, see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). @@ -187,13 +187,13 @@ Initializes a new instance of the class. - is the abstract base class of all streams. - - Some of the more commonly used streams that inherit from are , and . - + is the abstract base class of all streams. + + Some of the more commonly used streams that inherit from are , and . + ]]> @@ -238,10 +238,10 @@ System.IAsyncResult - - - - + + + + [System.Runtime.CompilerServices.Nullable(2)] @@ -249,7 +249,7 @@ - + [System.Runtime.CompilerServices.Nullable(2)] @@ -267,23 +267,23 @@ Begins an asynchronous read operation. (Consider using instead.) An that represents the asynchronous read, which could still be pending. - and to implement asynchronous I/O operations. These methods are still available in the .NET Framework 4.5 to support legacy code; however, the new async methods, such as , , , and , help you implement asynchronous I/O operations more easily. - - The default implementation of `BeginRead` on a stream calls the method synchronously, which means that `Read` might block on some streams. However, instances of classes such as `FileStream` and `NetworkStream` fully support asynchronous operations if the instances have been opened asynchronously. Therefore, calls to `BeginRead` will not block on those streams. You can override `BeginRead` (by using async delegates, for example) to provide asynchronous behavior. - - Pass the `IAsyncResult` return value to the method of the stream to determine how many bytes were read and to release operating system resources used for reading. must be called once for every call to . You can do this either by using the same code that called `BeginRead` or in a callback passed to `BeginRead`. - - The current position in the stream is updated when the asynchronous read or write is issued, not when the I/O operation completes. - - Multiple simultaneous asynchronous requests render the request completion order uncertain. - - Use the property to determine whether the current instance supports reading. - - If a stream is closed or you pass an invalid argument, exceptions are thrown immediately from `BeginRead`. Errors that occur during an asynchronous read request, such as a disk failure during the I/O request, occur on the thread pool thread and throw exceptions when calling `EndRead`. - + and to implement asynchronous I/O operations. These methods are still available in the .NET Framework 4.5 to support legacy code; however, the new async methods, such as , , , and , help you implement asynchronous I/O operations more easily. + + The default implementation of `BeginRead` on a stream calls the method synchronously, which means that `Read` might block on some streams. However, instances of classes such as `FileStream` and `NetworkStream` fully support asynchronous operations if the instances have been opened asynchronously. Therefore, calls to `BeginRead` will not block on those streams. You can override `BeginRead` (by using async delegates, for example) to provide asynchronous behavior. + + Pass the `IAsyncResult` return value to the method of the stream to determine how many bytes were read and to release operating system resources used for reading. must be called once for every call to . You can do this either by using the same code that called `BeginRead` or in a callback passed to `BeginRead`. + + The current position in the stream is updated when the asynchronous read or write is issued, not when the I/O operation completes. + + Multiple simultaneous asynchronous requests render the request completion order uncertain. + + Use the property to determine whether the current instance supports reading. + + If a stream is closed or you pass an invalid argument, exceptions are thrown immediately from `BeginRead`. Errors that occur during an asynchronous read request, such as a disk failure during the I/O request, occur on the thread pool thread and throw exceptions when calling `EndRead`. + ]]> Attempted an asynchronous read past the end of the stream, or a disk error occurs. @@ -336,10 +336,10 @@ System.IAsyncResult - - - - + + + + [System.Runtime.CompilerServices.Nullable(2)] @@ -347,7 +347,7 @@ - + [System.Runtime.CompilerServices.Nullable(2)] @@ -365,23 +365,23 @@ Begins an asynchronous write operation. (Consider using instead.) An that represents the asynchronous write, which could still be pending. - and to implement asynchronous I/O operations. These methods are still available in the .NET Framework 4.5 to support legacy code; however, the new async methods, such as , , , and , help you implement asynchronous I/O operations more easily. - - The default implementation of `BeginWrite` on a stream calls the method synchronously, which means that `Write` might block on some streams. However, instances of classes such as `FileStream` and `NetworkStream` fully support asynchronous operations if the instances have been opened asynchronously. Therefore, calls to `BeginWrite` will not block on those streams. You can override `BeginWrite` (by using async delegates, for example) to provide asynchronous behavior. - - Pass the `IAsyncResult` returned by the current method to to ensure that the write completes and frees resources appropriately. must be called once for every call to . You can do this either by using the same code that called `BeginWrite` or in a callback passed to `BeginWrite`. If an error occurs during an asynchronous write, an exception will not be thrown until `EndWrite` is called with the `IAsyncResult` returned by this method. - - If a stream is writable, writing at the end of the stream expands the stream. - - The current position in the stream is updated when you issue the asynchronous read or write, not when the I/O operation completes. Multiple simultaneous asynchronous requests render the request completion order uncertain. - - Use the property to determine whether the current instance supports writing. - - If a stream is closed or you pass an invalid argument, exceptions are thrown immediately from `BeginWrite`. Errors that occur during an asynchronous write request, such as a disk failure during the I/O request, occur on the thread pool thread and throw exceptions when calling `EndWrite`. - + and to implement asynchronous I/O operations. These methods are still available in the .NET Framework 4.5 to support legacy code; however, the new async methods, such as , , , and , help you implement asynchronous I/O operations more easily. + + The default implementation of `BeginWrite` on a stream calls the method synchronously, which means that `Write` might block on some streams. However, instances of classes such as `FileStream` and `NetworkStream` fully support asynchronous operations if the instances have been opened asynchronously. Therefore, calls to `BeginWrite` will not block on those streams. You can override `BeginWrite` (by using async delegates, for example) to provide asynchronous behavior. + + Pass the `IAsyncResult` returned by the current method to to ensure that the write completes and frees resources appropriately. must be called once for every call to . You can do this either by using the same code that called `BeginWrite` or in a callback passed to `BeginWrite`. If an error occurs during an asynchronous write, an exception will not be thrown until `EndWrite` is called with the `IAsyncResult` returned by this method. + + If a stream is writable, writing at the end of the stream expands the stream. + + The current position in the stream is updated when you issue the asynchronous read or write, not when the I/O operation completes. Multiple simultaneous asynchronous requests render the request completion order uncertain. + + Use the property to determine whether the current instance supports writing. + + If a stream is closed or you pass an invalid argument, exceptions are thrown immediately from `BeginWrite`. Errors that occur during an asynchronous write request, such as a disk failure during the I/O request, occur on the thread pool thread and throw exceptions when calling `EndWrite`. + ]]> Attempted an asynchronous write past the end of the stream, or a disk error occurs. @@ -441,20 +441,20 @@ if the stream supports reading; otherwise, . - does not support reading, calls to the , , and methods throw a . - - - -## Examples - The following is an example of using the `CanRead` property. - + does not support reading, calls to the , , and methods throw a . + + + +## Examples + The following is an example of using the `CanRead` property. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic FileStream.CanRead Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.IO/FileStream/CanRead/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic FileStream.CanRead Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic FileStream.CanRead Example/VB/source.vb" id="Snippet1"::: + ]]> File and Stream I/O @@ -507,11 +507,11 @@ if the stream supports seeking; otherwise, . - does not support seeking, calls to , , , and may throw a . - + does not support seeking, calls to , , , and may throw a . + ]]> File and Stream I/O @@ -568,11 +568,11 @@ Gets a value that determines whether the current stream can time out. A value that determines whether the current stream can time out. - property always returns `false`. Some stream implementations require different behavior, such as , which times out if network connectivity is interrupted or lost. If you are implementing a stream that must be able to time out, this property should be overridden to return `true`. - + property always returns `false`. Some stream implementations require different behavior, such as , which times out if network connectivity is interrupted or lost. If you are implementing a stream that must be able to time out, this property should be overridden to return `true`. + ]]> @@ -624,20 +624,20 @@ if the stream supports writing; otherwise, . - does not support writing, a call to , , or throws a . In such cases, is typically implemented as an empty method to ensure full compatibility with other types since it's valid to flush a read-only stream. - - - -## Examples - The following is an example of using the `CanWrite` property. - + + + +## Examples + The following is an example of using the `CanWrite` property. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Stream.CanWrite Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.IO/Stream/CanWrite/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Stream.CanWrite Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Stream.CanWrite Example/VB/source.vb" id="Snippet1"::: + ]]> File and Stream I/O @@ -686,15 +686,15 @@ Closes the current stream and releases any resources (such as sockets and file handles) associated with the current stream. Instead of calling this method, ensure that the stream is properly disposed. - , specifying `true` to release all resources. You do not have to specifically call the method. Instead, ensure that every object is properly disposed. You can declare objects within a `using` block (or `Using` block in Visual Basic) to ensure that the stream and all of its resources are disposed, or you can explicitly call the method. - - Flushing the stream will not flush its underlying encoder unless you explicitly call an implementation of or `Close`. 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 be encoded only after the encoder receives the adjacent character or characters. - - Attempts to manipulate the stream after the stream has been closed might throw an . - + , specifying `true` to release all resources. You do not have to specifically call the method. Instead, ensure that every object is properly disposed. You can declare objects within a `using` block (or `Using` block in Visual Basic) to ensure that the stream and all of its resources are disposed, or you can explicitly call the method. + + Flushing the stream will not flush its underlying encoder unless you explicitly call an implementation of or `Close`. 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 be encoded only after the encoder receives the adjacent character or characters. + + Attempts to manipulate the stream after the stream has been closed might throw an . + ]]> @@ -761,27 +761,27 @@ The stream to which the contents of the current stream will be copied. Reads the bytes from the current stream and writes them to another stream. Both streams positions are advanced by the number of bytes copied. - to a . - + to a . + :::code language="csharp" source="~/snippets/csharp/System.IO/Stream/CopyTo/program.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.io.stream.copyto/vb/program.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.io.stream.copyto/vb/program.vb" id="Snippet1"::: + ]]> is . - The current stream does not support reading. - - -or- - + The current stream does not support reading. + + -or- + does not support writing. Either the current stream or were closed before the method was called. An I/O error occurred. @@ -839,21 +839,21 @@ The size of the buffer. This value must be greater than zero. The default size is 81920. Reads the bytes from the current stream and writes them to another stream, using a specified buffer size. Both streams positions are advanced by the number of bytes copied. - is . is negative or zero. - The current stream does not support reading. - - -or- - + The current stream does not support reading. + + -or- + does not support writing. Either the current stream or were closed before the method was called. An I/O error occurred. @@ -922,18 +922,18 @@ Asynchronously reads the bytes from the current stream and writes them to another stream. Both streams positions are advanced by the number of bytes copied. A task that represents the asynchronous copy operation. - method enables you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in a Windows 8.x Store app or desktop app where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#. - - Copying begins at the current position in the current stream. - + method enables you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in a Windows 8.x Store app or desktop app where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#. + + Copying begins at the current position in the current stream. + 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 demonstrates how to use two objects to asynchronously copy the files from one directory to another. The class derives from the class. Notice that the event handler for the control is marked with the `async` modifier because it calls an asynchronous method - + +## Examples + The following example demonstrates how to use two objects to asynchronously copy the files from one directory to another. The class derives from the class. Notice that the event handler for the control is marked with the `async` modifier because it calls an asynchronous method + :::code language="csharp" source="~/snippets/csharp/System.IO/FileStream/Overview/example.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Asynchronous_File_IO_async/vb/example.vb" id="Snippet1"::: @@ -999,15 +999,15 @@ Asynchronously reads the bytes from the current stream and writes them to another stream, using a specified buffer size. Both streams positions are advanced by the number of bytes copied. A task that represents the asynchronous copy operation. - method enables you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in a Windows 8.x Store app or desktop app where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#. - - Copying begins at the current position in the current stream. - - For an example of copying between two streams, see the overload. - + method enables you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in a Windows 8.x Store app or desktop app where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#. + + Copying begins at the current position in the current stream. + + For an example of copying between two streams, see the overload. + 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 . ]]> @@ -1061,17 +1061,17 @@ Asynchronously reads the bytes from the current stream and writes them to another stream, using a specified cancellation token. Both streams positions are advanced by the number of bytes copied. A task that represents the asynchronous copy operation. - method enables you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in a Windows 8.x Store app or desktop app where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#. - - If the operation is canceled before it completes, the returned task contains the value for the property. - - Copying begins at the current position in the current stream. - - For an example of copying between two streams, see the overload. - + method enables you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in a Windows 8.x Store app or desktop app where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#. + + If the operation is canceled before it completes, the returned task contains the value for the property. + + Copying begins at the current position in the current stream. + + For an example of copying between two streams, see the overload. + 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 . ]]> @@ -1135,17 +1135,17 @@ Asynchronously reads the bytes from the current stream and writes them to another stream, using a specified buffer size and cancellation token. Both streams positions are advanced by the number of bytes copied. A task that represents the asynchronous copy operation. - method enables you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in a Windows 8.x Store app or desktop app where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#. - - If the operation is canceled before it completes, the returned task contains the value for the property. - - Copying begins at the current position in the current stream. - - For an example of copying between two streams, see the overload. - + method enables you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in a Windows 8.x Store app or desktop app where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#. + + If the operation is canceled before it completes, the returned task contains the value for the property. + + Copying begins at the current position in the current stream. + + For an example of copying between two streams, see the overload. + 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 . ]]> @@ -1215,13 +1215,13 @@ Allocates a object. A reference to the allocated . - or until the asynchronous operation is complete. - + or until the asynchronous operation is complete. + ]]> File and Stream I/O @@ -1286,18 +1286,18 @@ Releases all resources used by the . - to be reallocated for other purposes. For more information about `Dispose`, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). - + to be reallocated for other purposes. For more information about `Dispose`, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). + ]]> - Place all cleanup logic for your stream object in . Do not override . - + Place all cleanup logic for your stream object in . Do not override . + Note that because of backward compatibility requirements, this method's implementation differs from the recommended guidance for the Dispose pattern. This method calls , which then calls . @@ -1349,22 +1349,22 @@ to release both managed and unmanaged resources; to release only unmanaged resources. Releases the unmanaged resources used by the and optionally releases the managed resources. - for this purpose. - - 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 `disposing` set to `false`. - + for this purpose. + + 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 `disposing` set to `false`. + ]]> - In derived classes, do not override the method, instead, put all of the Stream cleanup logic in the method. - - can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). - + In derived classes, do not override the method, instead, put all of the Stream cleanup logic in the method. + + can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). + For more information about and , see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). @@ -1408,15 +1408,15 @@ Asynchronously releases the unmanaged resources used by the . A task that represents the asynchronous dispose operation. - method enables you to perform a resource-intensive dispose operation without blocking the main thread. This performance consideration is particularly important in a Windows 8.x Store app or desktop app where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#. - - This method disposes the stream by writing any changes to the backing store and closing the stream to release resources. - - Calling `DisposeAsync` allows the resources used by the to be reallocated for other purposes. For more information, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). - + method enables you to perform a resource-intensive dispose operation without blocking the main thread. This performance consideration is particularly important in a Windows 8.x Store app or desktop app where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#. + + This method disposes the stream by writing any changes to the backing store and closing the stream to release resources. + + Calling `DisposeAsync` allows the resources used by the to be reallocated for other purposes. For more information, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). + 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 . ]]> @@ -1461,32 +1461,32 @@ System.Int32 - + The reference to the pending asynchronous request to finish. Waits for the pending asynchronous read to complete. (Consider using instead.) The number of bytes read from the stream, between zero (0) and the number of bytes requested. ReadAsync returns zero (0) only if zero bytes were requested or if no more bytes will be available because it's at the end of the stream; otherwise, read operations do not complete until at least one byte is available. If zero bytes are requested, read operations may complete immediately or may not complete until at least one byte is available (but without consuming any data). - and to implement asynchronous I/O operations. These methods are still available in the .NET Framework 4.5 to support legacy code; however, the new async methods, such as , , , and , help you implement asynchronous I/O operations more easily. - - Call `EndRead` to determine how many bytes were read from the stream. - - `EndRead` can be called once on every from . - - This method blocks until the I/O operation has completed. - + and to implement asynchronous I/O operations. These methods are still available in the .NET Framework 4.5 to support legacy code; however, the new async methods, such as , , , and , help you implement asynchronous I/O operations more easily. + + Call `EndRead` to determine how many bytes were read from the stream. + + `EndRead` can be called once on every from . + + This method blocks until the I/O operation has completed. + ]]> is . - A handle to the pending read operation is not available. - - -or- - + A handle to the pending read operation is not available. + + -or- + The pending operation does not support reading. did not originate from a method on the current stream. @@ -1535,29 +1535,29 @@ System.Void - + A reference to the outstanding asynchronous I/O request. Ends an asynchronous write operation. (Consider using instead.) - and to implement asynchronous I/O operations. These methods are still available in the .NET Framework 4.5 to support legacy code; however, the new async methods, such as , , , and , help you implement asynchronous I/O operations more easily. - - `EndWrite` must be called exactly once on every from . - - This method blocks until the I/O operation has completed. Errors that occur during an asynchronous write request, such as a disk failure during the I/O request, occur on the thread pool thread and become visible upon a call to `EndWrite`. Exceptions thrown by the thread pool thread will not be visible when calling `EndWrite`. - + and to implement asynchronous I/O operations. These methods are still available in the .NET Framework 4.5 to support legacy code; however, the new async methods, such as , , , and , help you implement asynchronous I/O operations more easily. + + `EndWrite` must be called exactly once on every from . + + This method blocks until the I/O operation has completed. Errors that occur during an asynchronous write request, such as a disk failure during the I/O request, occur on the thread pool thread and become visible upon a call to `EndWrite`. Exceptions thrown by the thread pool thread will not be visible when calling `EndWrite`. + ]]> is . - A handle to the pending write operation is not available. - - -or- - + A handle to the pending write operation is not available. + + -or- + The pending operation does not support writing. did not originate from a method on the current stream. @@ -1612,15 +1612,15 @@ When overridden in a derived class, clears all buffers for this stream and causes any buffered data to be written to the underlying device. - . + . In a class derived from that doesn't support writing, is typically implemented as an empty method to ensure full compatibility with other types since it's valid to flush a read-only stream. - When using the or class, do not flush the base object. Instead, use the class's or method, which makes sure that the data is flushed to the underlying stream first and then written to the file. - + When using the or class, do not flush the base object. Instead, use the class's or method, which makes sure that the data is flushed to the underlying stream first and then written to the file. + ]]> An I/O error occurs. @@ -1689,11 +1689,11 @@ Asynchronously clears all buffers for this stream and causes any buffered data to be written to the underlying device. A task that represents the asynchronous flush operation. - or , does not flush the buffer in its implementation of the method, the method will not flush the buffer. - + or , does not flush the buffer in its implementation of the method, the method will not flush the buffer. + 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 . ]]> @@ -1753,13 +1753,13 @@ Asynchronously clears all buffers for this stream, causes any buffered data to be written to the underlying device, and monitors cancellation requests. A task that represents the asynchronous flush operation. - value for the property. - - If a derived class, such as or , does not flush the buffer in its implementation of the method, the method will not flush the buffer. - + value for the property. + + If a derived class, such as or , does not flush the buffer in its implementation of the method, the method will not flush the buffer. + 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 . ]]> @@ -1863,11 +1863,11 @@ A with no backing store. - File and Stream I/O @@ -1966,13 +1966,13 @@ When overridden in a derived class, gets or sets the position within the current stream. The current position within the stream. - property to determine whether the stream supports seeking. - - Seeking to any location beyond the length of the stream is supported. - + property to determine whether the stream supports seeking. + + Seeking to any location beyond the length of the stream is supported. + ]]> An I/O error occurs. @@ -2028,15 +2028,15 @@ When overridden in a derived class, reads a sequence of bytes from the current stream and advances the position within the stream by the number of bytes read. The total number of bytes read into the buffer. This can be less than the size of the buffer if that many bytes are not currently available, or zero (0) if the buffer's length is zero or the end of the stream has been reached. - property to determine whether the current instance supports reading. Use the method to read asynchronously from the current stream. - + property to determine whether the current instance supports reading. Use the method to read asynchronously from the current stream. + Implementations of this method read a maximum of `buffer.Length` bytes from the current stream and store them in `buffer`. 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. Implementations return the number of bytes read. If more than zero bytes are requested, the implementation will not complete the operation until at least one byte of data can be read (if zero bytes were requested, some implementations may similarly not complete until at least one byte is available, but no data will be consumed from the stream in such a case). returns 0 only if zero bytes were requested or when there is no more data in the stream and no more is expected (such as a closed socket or end of file). An implementation is free to return fewer bytes than requested even if the end of the stream has not been reached. - - Use for reading primitive data types. - + + Use for reading primitive data types. + ]]> @@ -2094,24 +2094,24 @@ When overridden in a derived class, reads a sequence of bytes from the current stream and advances the position within the stream by the number of bytes read. The total number of bytes read into the buffer. This can be less than the number of bytes requested if that many bytes are not currently available, or zero (0) if is 0 or the end of the stream has been reached. - property to determine whether the current instance supports reading. Use the method to read asynchronously from the current stream. - + property to determine whether the current instance supports reading. Use the method to read asynchronously from the current stream. + Implementations of this 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. Implementations return the number of bytes read. If more than zero bytes are requested, the implementation will not complete the operation until at least one byte of data can be read (some implementations may similarly not complete until at least one byte is available even if zero bytes were requested, but no data will be consumed from the stream in such a case). returns 0 only if zero bytes were requested or when there is no more data in the stream and no more is expected (such as a closed socket or end of file). An implementation is free to return fewer bytes than requested even if the end of the stream has not been reached. - - Use for reading primitive data types. - - - -## Examples - The following example shows how to use to read a block of data. - + + Use for reading primitive data types. + + + +## Examples + The following example shows how to use to read a block of data. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Stream.Read Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.IO/Stream/Read/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Stream.Read Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Stream.Read Example/VB/source.vb" id="Snippet1"::: + ]]> The sum of and is larger than the buffer length. @@ -2184,17 +2184,17 @@ Asynchronously reads a sequence of bytes from the current stream, advances the position within the stream by the number of bytes read, and monitors cancellation requests. A task that represents the asynchronous read operation. The value of its property contains the total number of bytes read into the buffer. The result value can be less than the length of the buffer if that many bytes are not currently available, or it can be 0 (zero) if the length of the buffer is 0 or if the end of the stream has been reached. - method enables you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in a Windows 8.x Store app or desktop app where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#. - - Use the property to determine whether the current instance supports reading. - - If the operation is canceled before it completes, the returned task contains the value for the property. - - For an example, see the overload. - + method enables you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in a Windows 8.x Store app or desktop app where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#. + + Use the property to determine whether the current instance supports reading. + + If the operation is canceled before it completes, the returned task contains the value for the property. + + For an example, see the overload. + ]]> The cancellation token was canceled. This exception is stored into the returned task. @@ -2256,18 +2256,18 @@ Asynchronously reads a sequence of bytes from the current stream and advances the position within the stream by the number of bytes read. A task that represents the asynchronous read operation. The value of the parameter contains the total number of bytes read into the buffer. The result value can be less than the number of bytes requested if the number of bytes currently available is less than the requested number, or it can be 0 (zero) if is 0 or if the end of the stream has been reached. - method enables you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in a Windows 8.x Store app or desktop app where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#. - - Use the property to determine whether the current instance supports reading. - + method enables you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in a Windows 8.x Store app or desktop app where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#. + + Use the property to determine whether the current instance supports reading. + 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 read from a file asynchronously. The example uses the class, which derives from the class. - + +## Examples + The following example shows how to read from a file asynchronously. The example uses the class, which derives from the class. + :::code language="csharp" source="~/snippets/csharp/System.IO/FileStream/Overview/example4.cs" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Asynchronous_File_IO_async/vb/example4.vb" id="Snippet4"::: @@ -2341,17 +2341,17 @@ Asynchronously reads a sequence of bytes from the current stream, advances the position within the stream by the number of bytes read, and monitors cancellation requests. A task that represents the asynchronous read operation. The value of the parameter contains the total number of bytes read into the buffer. The result value can be less than the number of bytes requested if the number of bytes currently available is less than the requested number, or it can be 0 (zero) if is 0 or if the end of the stream has been reached. - method enables you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in a Windows 8.x Store app or desktop app where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#. - - Use the property to determine whether the current instance supports reading. - - If the operation is canceled before it completes, the returned task contains the value for the property. - - For an example, see the overload. - + method enables you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in a Windows 8.x Store app or desktop app where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#. + + Use the property to determine whether the current instance supports reading. + + If the operation is canceled before it completes, the returned task contains the value for the property. + + For an example, see the overload. + 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 . ]]> @@ -2542,13 +2542,13 @@ When `minimumBytes` is 0 (zero), this read operation will be completed without w Reads a byte from the stream and advances the position within the stream by one byte, or returns -1 if at the end of the stream. The unsigned byte cast to an , or -1 if at the end of the stream. - property to determine whether the current instance supports reading. - - Attempts to manipulate the stream after the stream has been closed could throw an . - + property to determine whether the current instance supports reading. + + Attempts to manipulate the stream after the stream has been closed could throw an . + ]]> The stream does not support reading. @@ -2896,17 +2896,17 @@ The range specified by the combination of and When overridden in a derived class, sets the position within the current stream. The new position within the current stream. - property to determine whether the current instance supports seeking. - - If `offset` is negative, the new position is required to precede the position specified by `origin` by the number of bytes specified by `offset`. If `offset` is zero (0), the new position is required to be the position specified by `origin`. If `offset` is positive, the new position is required to follow the position specified by `origin` by the number of bytes specified by `offset`. - - Classes derived from `Stream` that support seeking must override this method to provide the functionality described above. - - Seeking to any location beyond the length of the stream is supported. - + property to determine whether the current instance supports seeking. + + If `offset` is negative, the new position is required to precede the position specified by `origin` by the number of bytes specified by `offset`. If `offset` is zero (0), the new position is required to be the position specified by `origin`. If `offset` is positive, the new position is required to follow the position specified by `origin` by the number of bytes specified by `offset`. + + Classes derived from `Stream` that support seeking must override this method to provide the functionality described above. + + Seeking to any location beyond the length of the stream is supported. + ]]> An I/O error occurs. @@ -2964,15 +2964,15 @@ The range specified by the combination of and The desired length of the current stream in bytes. When overridden in a derived class, sets the length of the current stream. - property to determine whether the current instance supports writing, and the property to determine whether seeking is supported. - + property to determine whether the current instance supports writing, and the property to determine whether seeking is supported. + ]]> An I/O error occurs. @@ -3020,18 +3020,18 @@ The range specified by the combination of and System.IO.Stream - + The object to synchronize. Creates a thread-safe (synchronized) wrapper around the specified object. A thread-safe object. - object and restricts access to it from multiple threads. All access to the object will be thread safe. - + object and restricts access to it from multiple threads. All access to the object will be thread safe. + ]]> @@ -3071,7 +3071,7 @@ The range specified by the combination of and instance is cast to an interface. ]]> @@ -3212,13 +3212,13 @@ This member is an explicit interface member implementation. It can be used only A region of memory. This method copies the contents of this region to the current stream. When overridden in a derived class, writes a sequence of bytes to the current stream and advances the current position within this stream by the number of bytes written. - property to determine whether the current instance supports writing. Use the method to write asynchronously to the current stream. - - If the write operation is successful, the position within the stream advances by the number of bytes written. If an exception occurs, the position within the stream remains unchanged. - + property to determine whether the current instance supports writing. Use the method to write asynchronously to the current stream. + + If the write operation is successful, the position within the stream advances by the number of bytes written. If an exception occurs, the position within the stream remains unchanged. + ]]> @@ -3274,13 +3274,13 @@ This member is an explicit interface member implementation. It can be used only The number of bytes to be written to the current stream. When overridden in a derived class, writes a sequence of bytes to the current stream and advances the current position within this stream by the number of bytes written. - property to determine whether the current instance supports writing. Use the method to write asynchronously to the current stream. - - If the write operation is successful, the position within the stream advances by the number of bytes written. If an exception occurs, the position within the stream remains unchanged. - + property to determine whether the current instance supports writing. Use the method to write asynchronously to the current stream. + + If the write operation is successful, the position within the stream advances by the number of bytes written. If an exception occurs, the position within the stream remains unchanged. + ]]> The sum of and is greater than the buffer length. @@ -3354,17 +3354,17 @@ This member is an explicit interface member implementation. It can be used only Asynchronously writes a sequence of bytes to the current stream, advances the current position within this stream by the number of bytes written, and monitors cancellation requests. A task that represents the asynchronous write operation. - method enables you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in a Windows 8.x Store app or desktop app where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#. - - Use the property to determine whether the current instance supports writing. - - If the operation is canceled before it completes, the returned task contains the value for the property. - - For an example, see the overload. - + method enables you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in a Windows 8.x Store app or desktop app where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#. + + Use the property to determine whether the current instance supports writing. + + If the operation is canceled before it completes, the returned task contains the value for the property. + + For an example, see the overload. + ]]> The cancellation token was canceled. This exception is stored into the returned task. @@ -3426,18 +3426,18 @@ This member is an explicit interface member implementation. It can be used only Asynchronously writes a sequence of bytes to the current stream and advances the current position within this stream by the number of bytes written. A task that represents the asynchronous write operation. - method enables you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in a Windows 8.x Store app or desktop app where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#. - - Use the property to determine whether the current instance supports writing. - + method enables you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in a Windows 8.x Store app or desktop app where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#. + + Use the property to determine whether the current instance supports writing. + 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 write asynchronously to a file. The example uses the class, which derives from the class. - + +## Examples + The following example shows how to write asynchronously to a file. The example uses the class, which derives from the class. + :::code language="csharp" source="~/snippets/csharp/System.IO/FileStream/Overview/example3.cs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Asynchronous_File_IO_async/vb/example3.vb" id="Snippet3"::: @@ -3511,17 +3511,17 @@ This member is an explicit interface member implementation. It can be used only Asynchronously writes a sequence of bytes to the current stream, advances the current position within this stream by the number of bytes written, and monitors cancellation requests. A task that represents the asynchronous write operation. - method enables you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in a Windows 8.x Store app or desktop app where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#. - - Use the property to determine whether the current instance supports writing. - - If the operation is canceled before it completes, the returned task contains the value for the property. - - For an example, see the overload. - + method enables you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in a Windows 8.x Store app or desktop app where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#. + + Use the property to determine whether the current instance supports writing. + + If the operation is canceled before it completes, the returned task contains the value for the property. + + For an example, see the overload. + 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 . ]]> @@ -3585,11 +3585,11 @@ This member is an explicit interface member implementation. It can be used only The byte to write to the stream. Writes a byte to the current position in the stream and advances the position within the stream by one byte. - property to determine whether the current instance supports writing. - + property to determine whether the current instance supports writing. + ]]> An I/O error occurs. diff --git a/xml/System.IO/StreamReader.xml b/xml/System.IO/StreamReader.xml index b2dde3da26a..993fb1a479a 100644 --- a/xml/System.IO/StreamReader.xml +++ b/xml/System.IO/StreamReader.xml @@ -84,39 +84,39 @@ Implements a that reads characters from a byte stream in a particular encoding. - is designed for character input in a particular encoding, whereas the class is designed for byte input and output. Use for reading lines of information from a standard text file. - + is designed for character input in a particular encoding, whereas the class is designed for byte input and output. Use for reading lines of information from a standard text 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. - - defaults to UTF-8 encoding unless specified otherwise, instead of defaulting to the ANSI code page for the current system. UTF-8 handles Unicode characters correctly and provides consistent results on localized versions of the operating system. If you get the current character encoding using the property, the value is not reliable until after the first method, since encoding auto detection is not done until the first call to a method. - - By default, a is not thread safe. See for a thread-safe wrapper. - - The and method overloads read and write the number of characters specified by the `count` parameter. These are to be distinguished from and , which read and write the number of bytes specified by the `count` parameter. Use the methods only for reading and writing an integral number of byte array elements. - +> 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. + + defaults to UTF-8 encoding unless specified otherwise, instead of defaulting to the ANSI code page for the current system. UTF-8 handles Unicode characters correctly and provides consistent results on localized versions of the operating system. If you get the current character encoding using the property, the value is not reliable until after the first method, since encoding auto detection is not done until the first call to a method. + + By default, a is not thread safe. See for a thread-safe wrapper. + + The and method overloads read and write the number of characters specified by the `count` parameter. These are to be distinguished from and , which read and write the number of bytes specified by the `count` parameter. Use the methods only for reading and writing an integral number of byte array elements. + > [!NOTE] -> When reading from a , it is more efficient to use a buffer that is the same size as the internal buffer of the stream. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following example uses an instance of to read text from a file. The constructor used in this example is not supported for use in Windows Store Apps. - +> When reading from a , it is more efficient to use a buffer that is the same size as the internal buffer of the stream. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following example uses an instance of to read text from a file. The constructor used in this example is not supported for use in Windows Store Apps. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/ReadTextFile/CPP/readtextfile.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.IO/StreamReader/Overview/readtextfile.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ReadTextFile/VB/readtextfile.vb" id="Snippet1"::: - - The following example instantiates a object and calls its method to read a file asynchronously. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ReadTextFile/VB/readtextfile.vb" id="Snippet1"::: + + The following example instantiates a object and calls its method to read a file asynchronously. + :::code language="csharp" source="~/snippets/csharp/System.IO/StreamReader/Overview/asyncex1.cs" id="Snippet51"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.StreamReader/VB/asyncex1.vb" id="Snippet51"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.StreamReader/VB/asyncex1.vb" id="Snippet51"::: + ]]> @@ -186,27 +186,27 @@ The stream to be read. Initializes a new instance of the class for the specified stream. - , the property using the `stream` parameter, and the internal buffer size to 1024 bytes. - - The object calls on the provided object when is called. - + , the property using the `stream` parameter, and the internal buffer size to 1024 bytes. + + The object calls on the provided object when is called. + > [!CAUTION] -> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following code example demonstrates this constructor. - +> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following code example demonstrates this constructor. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/StrmReader Ctor1/CPP/strmreader ctor1.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.IO/StreamReader/.ctor/strmreader ctor1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/StrmReader Ctor1/VB/strmreader ctor1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/StrmReader Ctor1/VB/strmreader ctor1.vb" id="Snippet1"::: + ]]> @@ -262,35 +262,35 @@ - + The complete file path to be read. Initializes a new instance of the class for the specified file name. - and the buffer size to 1024 bytes. - - The `path` parameter can be a file name, including a file on a Universal Naming Convention (UNC) share. - - The `path` parameter is not required to be a file stored on disk; it can be any part of a system that supports access using streams. - + and the buffer size to 1024 bytes. + + The `path` parameter can be a file name, including a file on a Universal Naming Convention (UNC) share. + + The `path` parameter is not required to be a file stored on disk; it can be any part of a system that supports access using streams. + > [!CAUTION] -> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following code example demonstrates this constructor. - +> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following code example demonstrates this constructor. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/StrmReader Ctor2/CPP/strmreader ctor2.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.IO/StreamReader/.ctor/strmreader ctor2.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/StrmReader Ctor2/VB/strmreader ctor2.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/StrmReader Ctor2/VB/strmreader ctor2.vb" id="Snippet1"::: + ]]> @@ -356,26 +356,26 @@ Indicates whether to look for byte order marks at the beginning of the file. Initializes a new instance of the class for the specified stream, with the specified byte order mark detection option. - , the property using the `stream` parameter, and the internal buffer size to 1024 bytes. - - The `detectEncodingFromByteOrderMarks` parameter detects the encoding by looking at the first four bytes of the stream. It automatically recognizes UTF-8, little-endian UTF-16, big-endian UTF-16, little-endian UTF-32, and big-endian UTF-32 text if the file starts with the appropriate byte order marks. See the method for more information. - - The object calls on the provided object when is called. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following code example demonstrates this constructor. - + , the property using the `stream` parameter, and the internal buffer size to 1024 bytes. + + The `detectEncodingFromByteOrderMarks` parameter detects the encoding by looking at the first four bytes of the stream. It automatically recognizes UTF-8, little-endian UTF-16, big-endian UTF-16, little-endian UTF-32, and big-endian UTF-32 text if the file starts with the appropriate byte order marks. See the method for more information. + + The object calls on the provided object when is called. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following code example demonstrates this constructor. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.StreamReader/CPP/streamreadersample.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.IO/StreamReader/Overview/streamreadersample.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.StreamReader/VB/streamreadersample.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.StreamReader/VB/streamreadersample.vb" id="Snippet2"::: + ]]> @@ -436,27 +436,27 @@ The character encoding to use. Initializes a new instance of the class for the specified stream, with the specified character encoding. - object attempts to detect the encoding by looking at the first four bytes of the stream. It automatically recognizes UTF-8, little-endian UTF-16, big-endian UTF-16, little-endian UTF-32, and big-endian UTF-32 text if the file starts with the appropriate byte order marks. Otherwise, the user-provided encoding is used. See the method for more information. - - The object calls on the provided object when is called. - + object attempts to detect the encoding by looking at the first four bytes of the stream. It automatically recognizes UTF-8, little-endian UTF-16, big-endian UTF-16, little-endian UTF-32, and big-endian UTF-32 text if the file starts with the appropriate byte order marks. Otherwise, the user-provided encoding is used. See the method for more information. + + The object calls on the provided object when is called. + > [!CAUTION] -> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following code example demonstrates this constructor. - +> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following code example demonstrates this constructor. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.StreamReader/CPP/streamreadersample.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.IO/StreamReader/Overview/streamreadersample.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.StreamReader/VB/streamreadersample.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.StreamReader/VB/streamreadersample.vb" id="Snippet2"::: + ]]> @@ -513,36 +513,36 @@ - - + + The complete file path to be read. Indicates whether to look for byte order marks at the beginning of the file. Initializes a new instance of the class for the specified file name, with the specified byte order mark detection option. - , the property using the `stream` parameter, and the internal buffer size to 1024 bytes. - - The `path` parameter can be a file name, including a file on a Universal Naming Convention (UNC) share. - - The `path` parameter is not required to be a file stored on disk; it can be any part of a system that supports access using streams. - - The `detectEncodingFromByteOrderMarks` parameter detects the encoding by looking at the first four bytes of the stream. It automatically recognizes UTF-8, little-endian UTF-16, big-endian UTF-16, little-endian UTF-32, and big-endian UTF-32 text if the file starts with the appropriate byte order marks. Otherwise, the is used. See the method for more information. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following code example demonstrates this constructor. - + , the property using the `stream` parameter, and the internal buffer size to 1024 bytes. + + The `path` parameter can be a file name, including a file on a Universal Naming Convention (UNC) share. + + The `path` parameter is not required to be a file stored on disk; it can be any part of a system that supports access using streams. + + The `detectEncodingFromByteOrderMarks` parameter detects the encoding by looking at the first four bytes of the stream. It automatically recognizes UTF-8, little-endian UTF-16, big-endian UTF-16, little-endian UTF-32, and big-endian UTF-32 text if the file starts with the appropriate byte order marks. Otherwise, the is used. See the method for more information. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following code example demonstrates this constructor. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.StreamReader/CPP/streamreadersample.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.IO/StreamReader/Overview/streamreadersample.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.StreamReader/VB/streamreadersample.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.StreamReader/VB/streamreadersample.vb" id="Snippet2"::: + ]]> @@ -656,37 +656,37 @@ - - + + The complete file path to be read. The character encoding to use. Initializes a new instance of the class for the specified file name, with the specified character encoding. - object attempts to detect the encoding by looking at the first four bytes of the stream. It automatically recognizes UTF-8, little-endian UTF-16, big-endian UTF-16, little-endian UTF-32, and big-endian UTF-32 text if the file starts with the appropriate byte order marks. Otherwise, the user-provided encoding is used. See the method for more information. - - The `path` parameter can be a file name, including a file on a Universal Naming Convention (UNC) share. - - The `path` parameter is not required to be a file stored on disk; it can be any part of a system that supports access using streams. - + object attempts to detect the encoding by looking at the first four bytes of the stream. It automatically recognizes UTF-8, little-endian UTF-16, big-endian UTF-16, little-endian UTF-32, and big-endian UTF-32 text if the file starts with the appropriate byte order marks. Otherwise, the user-provided encoding is used. See the method for more information. + + The `path` parameter can be a file name, including a file on a Universal Naming Convention (UNC) share. + + The `path` parameter is not required to be a file stored on disk; it can be any part of a system that supports access using streams. + > [!CAUTION] -> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following code example demonstrates this constructor. - +> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following code example demonstrates this constructor. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.StreamReader/CPP/streamreadersample.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.IO/StreamReader/Overview/streamreadersample.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.StreamReader/VB/streamreadersample.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.StreamReader/VB/streamreadersample.vb" id="Snippet2"::: + ]]> @@ -754,29 +754,29 @@ Indicates whether to look for byte order marks at the beginning of the file. Initializes a new instance of the class for the specified stream, with the specified character encoding and byte order mark detection option. - property using the `stream` parameter, and the internal buffer size to 1024 bytes. - - The `detectEncodingFromByteOrderMarks` parameter detects the encoding by looking at the first four bytes of the stream. It automatically recognizes UTF-8, little-endian UTF-16, big-endian UTF-16, little-endian UTF-32, and big-endian UTF-32 text if the file starts with the appropriate byte order marks. Otherwise, the user-provided encoding is used. See the method for more information. - - The object calls on the provided object when is called. - + property using the `stream` parameter, and the internal buffer size to 1024 bytes. + + The `detectEncodingFromByteOrderMarks` parameter detects the encoding by looking at the first four bytes of the stream. It automatically recognizes UTF-8, little-endian UTF-16, big-endian UTF-16, little-endian UTF-32, and big-endian UTF-32 text if the file starts with the appropriate byte order marks. Otherwise, the user-provided encoding is used. See the method for more information. + + The object calls on the provided object when is called. + > [!CAUTION] -> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following code example demonstrates this constructor. - +> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following code example demonstrates this constructor. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.StreamReader/CPP/streamreadersample.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.IO/StreamReader/Overview/streamreadersample.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.StreamReader/VB/streamreadersample.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.StreamReader/VB/streamreadersample.vb" id="Snippet2"::: + ]]> @@ -833,9 +833,9 @@ - - - + + + The complete file path to be read. @@ -843,31 +843,31 @@ Indicates whether to look for byte order marks at the beginning of the file. Initializes a new instance of the class for the specified file name, with the specified character encoding and byte order mark detection option. - method for more information. - - The `path` parameter can be a file name, including a file on a Universal Naming Convention (UNC) share. - - The `path` parameter is not required to be a file stored on disk; it can be any part of a system that supports access using streams. - + method for more information. + + The `path` parameter can be a file name, including a file on a Universal Naming Convention (UNC) share. + + The `path` parameter is not required to be a file stored on disk; it can be any part of a system that supports access using streams. + > [!CAUTION] -> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following code example demonstrates this constructor. - +> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following code example demonstrates this constructor. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.StreamReader/CPP/streamreadersample.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.IO/StreamReader/Overview/streamreadersample.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.StreamReader/VB/streamreadersample.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.StreamReader/VB/streamreadersample.vb" id="Snippet2"::: + ]]> @@ -937,32 +937,32 @@ The minimum buffer size. Initializes a new instance of the class for the specified stream, with the specified character encoding, byte order mark detection option, and buffer size. - object. The `detectEncodingFromByteOrderMarks` parameter detects the encoding by looking at the first four bytes of the stream. It automatically recognizes UTF-8, little-endian UTF-16, big-endian UTF-16, little-endian UTF-32, and big-endian UTF-32 text if the file starts with the appropriate byte order marks. Otherwise, the user-provided encoding is used. See the method for more information. - - The object calls on the provided object when is called. - + object. The `detectEncodingFromByteOrderMarks` parameter detects the encoding by looking at the first four bytes of the stream. It automatically recognizes UTF-8, little-endian UTF-16, big-endian UTF-16, little-endian UTF-32, and big-endian UTF-32 text if the file starts with the appropriate byte order marks. Otherwise, the user-provided encoding is used. See the method for more information. + + The object calls on the provided object when is called. + > [!NOTE] -> When reading from a , it is more efficient to use a buffer that is the same size as the internal buffer of the stream. - +> When reading from a , it is more efficient to use a buffer that is the same size as the internal buffer of the stream. + > [!CAUTION] -> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following code example demonstrates this constructor. - +> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following code example demonstrates this constructor. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.StreamReader/CPP/streamreadersample.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.IO/StreamReader/Overview/streamreadersample.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.StreamReader/VB/streamreadersample.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.StreamReader/VB/streamreadersample.vb" id="Snippet2"::: + ]]> The stream does not support reading. @@ -1020,10 +1020,10 @@ - - - - + + + + The complete file path to be read. @@ -1032,33 +1032,33 @@ The minimum buffer size, in number of 16-bit characters. Initializes a new instance of the class for the specified file name, with the specified character encoding, byte order mark detection option, and buffer size. - object. The `detectEncodingFromByteOrderMarks` parameter detects the encoding by looking at the first four bytes of the stream. It automatically recognizes UTF-8, little-endian UTF-16, big-endian UTF-16, little-endian UTF-32, and big-endian UTF-32 text if the file starts with the appropriate byte order marks. Otherwise, the user-provided encoding is used. See the method for more information. - - The buffer size, in number of 16-bit characters, is set by the `bufferSize` parameter. If `bufferSize` is less than the minimum allowable size (128 characters), the minimum allowable size is used. - - The `path` parameter can be a file name, including a file on a Universal Naming Convention (UNC) share. - - The `path` parameter is not required to be a file stored on disk; it can be any part of a system that supports access using streams. - + object. The `detectEncodingFromByteOrderMarks` parameter detects the encoding by looking at the first four bytes of the stream. It automatically recognizes UTF-8, little-endian UTF-16, big-endian UTF-16, little-endian UTF-32, and big-endian UTF-32 text if the file starts with the appropriate byte order marks. Otherwise, the user-provided encoding is used. See the method for more information. + + The buffer size, in number of 16-bit characters, is set by the `bufferSize` parameter. If `bufferSize` is less than the minimum allowable size (128 characters), the minimum allowable size is used. + + The `path` parameter can be a file name, including a file on a Universal Naming Convention (UNC) share. + + The `path` parameter is not required to be a file stored on disk; it can be any part of a system that supports access using streams. + > [!CAUTION] -> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following code example demonstrates this constructor. - +> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following code example demonstrates this constructor. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.StreamReader/CPP/streamreadersample.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.IO/StreamReader/Overview/streamreadersample.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.StreamReader/VB/streamreadersample.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.StreamReader/VB/streamreadersample.vb" id="Snippet2"::: + ]]> @@ -1199,21 +1199,21 @@ to leave the stream open after the object is disposed; otherwise, . Initializes a new instance of the class for the specified stream based on the specified character encoding, byte order mark detection option, and buffer size, and optionally leaves the stream open. - object calls on the provided object when is called. - - The buffer size, in number of 16-bit characters, is set by the `bufferSize` parameter. If `bufferSize` is less than the minimum allowable size (128 characters), the minimum allowable size is used. - - This constructor enables you to change the encoding the first time you read from the object. If the `detectEncodingFromByteOrderMarks` parameter is `true`, the constructor detects the encoding by looking at the first four bytes of the stream. It automatically recognizes UTF-8, little-endian UTF-16, big-endian UTF-16, little-endian UTF-32, and big-endian UTF-32 text if the file starts with the appropriate byte order marks. Otherwise, the user-provided encoding is used. See the method for more information. - + object calls on the provided object when is called. + + The buffer size, in number of 16-bit characters, is set by the `bufferSize` parameter. If `bufferSize` is less than the minimum allowable size (128 characters), the minimum allowable size is used. + + This constructor enables you to change the encoding the first time you read from the object. If the `detectEncodingFromByteOrderMarks` parameter is `true`, the constructor detects the encoding by looking at the first four bytes of the stream. It automatically recognizes UTF-8, little-endian UTF-16, big-endian UTF-16, little-endian UTF-32, and big-endian UTF-32 text if the file starts with the appropriate byte order marks. Otherwise, the user-provided encoding is used. See the method for more information. + > [!NOTE] -> When reading from a , it is more efficient to use a buffer that is the same size as the internal buffer of the stream. - +> When reading from a , it is more efficient to use a buffer that is the same size as the internal buffer of the stream. + > [!CAUTION] -> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpreted correctly, and could cause an exception to be thrown. - +> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpreted correctly, and could cause an exception to be thrown. + ]]> @@ -1265,13 +1265,13 @@ Returns the underlying stream. The underlying stream. - class buffers input from the underlying stream when you call one of the methods. If you manipulate the position of the underlying stream after reading data into the buffer, the position of the underlying stream might not match the position of the internal buffer. To reset the internal buffer, call the method; however, this method slows performance and should be called only when absolutely necessary. The constructors that have the `detectEncodingFromByteOrderMarks` parameter can change the encoding the first time you read from the object. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - + class buffers input from the underlying stream when you call one of the methods. If you manipulate the position of the underlying stream after reading data into the buffer, the position of the underlying stream might not match the position of the internal buffer. To reset the internal buffer, call the method; however, this method slows performance and should be called only when absolutely necessary. The constructors that have the `detectEncodingFromByteOrderMarks` parameter can change the encoding the first time you read from the object. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + ]]> File and Stream I/O @@ -1323,16 +1323,16 @@ Closes the object and the underlying stream, and releases any system resources associated with the reader. - method. - -This implementation of calls the method, passing a `true` value. - -Following a call to , any operations on the reader might raise exceptions. - + method. + +This implementation of calls the method, passing a `true` value. + +Following a call to , any operations on the reader might raise exceptions. + ]]> File and Stream I/O @@ -1387,20 +1387,20 @@ Following a call to , any operations on th Gets the current character encoding that the current object is using. The current character encoding used by the current reader. The value can be different after the first call to any method of , since encoding autodetection is not done until the first call to a method. - object. - + object. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/StrmReader CurrentEncoding/CPP/strmreader currentencoding.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.IO/StreamReader/CurrentEncoding/strmreader currentencoding.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/StrmReader CurrentEncoding/VB/strmreader currentencoding.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/StrmReader CurrentEncoding/VB/strmreader currentencoding.vb" id="Snippet1"::: + ]]> File and Stream I/O @@ -1455,21 +1455,21 @@ Following a call to , any operations on th Clears the internal buffer. - method to reset the internal buffer for the object. You need to call this method only when the position of the internal buffer and the do not match. These positions can become mismatched when you read data into the buffer and then seek a new position in the underlying stream. This method slows performance and should be used only when absolutely necessary, such as when you want to read a portion of the contents of a object more than once. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following example shows a scenario where the method must be called to synchronize the internal buffer and the underlying stream. The file in the example is used to illustrate position and consists of the text `abcdefghijklmnopqrstuvwxyz`. By calling after the data is read, the example works as expected. After the first 15 characters are read, the position is reset to the offset value of 2 and all the remaining characters are read. If you remove the call to , the example does not work as expected. The first 15 characters are read, but only the position of the underlying stream is reset. The internal buffer of the object is still on the 16th character. Therefore, returns all the characters in the buffer plus the characters in the underlying stream starting from the reset position. - + method to reset the internal buffer for the object. You need to call this method only when the position of the internal buffer and the do not match. These positions can become mismatched when you read data into the buffer and then seek a new position in the underlying stream. This method slows performance and should be used only when absolutely necessary, such as when you want to read a portion of the contents of a object more than once. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following example shows a scenario where the method must be called to synchronize the internal buffer and the underlying stream. The file in the example is used to illustrate position and consists of the text `abcdefghijklmnopqrstuvwxyz`. By calling after the data is read, the example works as expected. After the first 15 characters are read, the position is reset to the offset value of 2 and all the remaining characters are read. If you remove the call to , the example does not work as expected. The first 15 characters are read, but only the position of the underlying stream is reset. The internal buffer of the object is still on the 16th character. Therefore, returns all the characters in the buffer plus the characters in the underlying stream starting from the reset position. + :::code language="csharp" source="~/snippets/csharp/System.IO/StreamReader/Overview/program.cs" id="Snippet30"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.StreamReader/VB/module1.vb" id="Snippet30"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.StreamReader/VB/module1.vb" id="Snippet30"::: + ]]> File and Stream I/O @@ -1528,20 +1528,20 @@ Following a call to , any operations on th to release both managed and unmanaged resources; to release only unmanaged resources. Closes the underlying stream, releases the unmanaged resources used by the , and optionally releases the managed resources. - method and the method, if it has been overridden. invokes the protected method with the `disposing` parameter set to true. `Finalize` invokes with `disposing` set to false. - - When the `disposing` parameter is `true`, this method releases all resources held by any managed objects that the object references. This method invokes the method of each referenced object. - - . - + method and the method, if it has been overridden. invokes the protected method with the `disposing` parameter set to true. `Finalize` invokes with `disposing` set to false. + + When the `disposing` parameter is `true`, this method releases all resources held by any managed objects that the object references. This method invokes the method of each referenced object. + + . + ]]> - Dispose can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed of in an earlier call to Dispose[cref,...]. For more information about how to implement see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). - + Dispose can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed of in an earlier call to Dispose[cref,...]. For more information about how to implement see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). + For more information about and , see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). File and Stream I/O @@ -1651,13 +1651,13 @@ Following a call to , any operations on th A object around an empty stream. - , zero is always returned. When is invoked on , `null` is returned. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - + , zero is always returned. When is invoked on , `null` is returned. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + ]]> File and Stream I/O @@ -1719,24 +1719,24 @@ Following a call to , any operations on th Returns the next available character but does not consume it. An integer representing the next character to be read, or -1 if there are no characters to be read or if the stream does not support seeking. - method returns an integer value in order to determine whether the end of the file, or another error has occurred. This allows a user to first check if the returned value is -1 before casting it to a type. - - This method overrides . - - The current position of the object is not changed by . - - - -## Examples - The following code example reads lines from a file until the end of the file is reached. - + method returns an integer value in order to determine whether the end of the file, or another error has occurred. This allows a user to first check if the returned value is -1 before casting it to a type. + + This method overrides . + + The current position of the object is not changed by . + + + +## Examples + The following code example reads lines from a file until the end of the file is reached. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/StrmReader Peek/CPP/strmreader peek.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.IO/StreamReader/Peek/strmreader peek.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/StrmReader Peek/VB/strmreader peek.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/StrmReader Peek/VB/strmreader peek.vb" id="Snippet1"::: + ]]> An I/O error occurs. @@ -1810,30 +1810,30 @@ Following a call to , any operations on th Reads the next character from the input stream and advances the character position by one character. The next character from the input stream represented as an object, or -1 if no more characters are available. - . - - This method returns an integer so that it can return -1 if the end of the stream has been reached. If you manipulate the position of the underlying stream after reading data into the buffer, the position of the underlying stream might not match the position of the internal buffer. To reset the internal buffer, call the method; however, this method slows performance and should be called only when absolutely necessary. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following code example demonstrates a simple use of the method. - + . + + This method returns an integer so that it can return -1 if the end of the stream has been reached. If you manipulate the position of the underlying stream after reading data into the buffer, the position of the underlying stream might not match the position of the internal buffer. To reset the internal buffer, call the method; however, this method slows performance and should be called only when absolutely necessary. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following code example demonstrates a simple use of the method. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/StrmReader Read1/CPP/strmreader read1.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.IO/StreamReader/Read/strmreader read1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/StrmReader Read1/VB/strmreader read1.vb" id="Snippet1"::: - - The following code example demonstrates reading a single character using the method overload, formatting the ASCII integer output as decimal and hexadecimal. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/StrmReader Read1/VB/strmreader read1.vb" id="Snippet1"::: + + The following code example demonstrates reading a single character using the method overload, formatting the ASCII integer output as decimal and hexadecimal. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/StrmRdrRead/CPP/strmrdrread.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.IO/StreamReader/Read/strmrdrread.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/StrmRdrRead/VB/strmrdrread.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/StrmRdrRead/VB/strmrdrread.vb" id="Snippet1"::: + ]]> An I/O error occurs. @@ -1957,28 +1957,28 @@ Following a call to , any operations on th Reads a specified maximum of characters from the current stream into a buffer, beginning at the specified index. The number of characters that have been read, or 0 if at the end of the stream and no data was read. The number will be less than or equal to the parameter, depending on whether the data is available within the stream. - . - - This method returns an integer so that it can return 0 if the end of the stream has been reached. - - When using the method, it is more efficient to use a buffer that is the same size as the internal buffer of the stream, where the internal buffer is set to your desired block size, and to always read less than the block size. If the size of the internal buffer was unspecified when the stream was constructed, its default size is 4 kilobytes (4096 bytes). If you manipulate the position of the underlying stream after reading data into the buffer, the position of the underlying stream might not match the position of the internal buffer. To reset the internal buffer, call the method; however, this method slows performance and should be called only when absolutely necessary. - - This method returns after either the number of characters specified by the `count` parameter are read, or the end of the file is reached. is a blocking version of . - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following code example reads five characters at a time until the end of the file is reached. - + . + + This method returns an integer so that it can return 0 if the end of the stream has been reached. + + When using the method, it is more efficient to use a buffer that is the same size as the internal buffer of the stream, where the internal buffer is set to your desired block size, and to always read less than the block size. If the size of the internal buffer was unspecified when the stream was constructed, its default size is 4 kilobytes (4096 bytes). If you manipulate the position of the underlying stream after reading data into the buffer, the position of the underlying stream might not match the position of the internal buffer. To reset the internal buffer, call the method; however, this method slows performance and should be called only when absolutely necessary. + + This method returns after either the number of characters specified by the `count` parameter are read, or the end of the file is reached. is a blocking version of . + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following code example reads five characters at a time until the end of the file is reached. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/StrmReader Read2/CPP/strmreader read2.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.IO/StreamReader/Read/strmreader read2.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/StrmReader Read2/VB/strmreader read2.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/StrmReader Read2/VB/strmreader read2.vb" id="Snippet1"::: + ]]> The buffer length minus is less than . @@ -2103,16 +2103,16 @@ Following a call to , any operations on th Reads a specified maximum number of characters from the current stream asynchronously and writes the data to a buffer, beginning at the specified index. A task that represents the asynchronous read operation. The value of the parameter contains the total number of characters read into the buffer. The result value can be less than the number of characters requested if the number of characters currently available is less than the requested number, or it can be 0 (zero) if the end of the stream has been reached. - , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . - -## Examples - The following example shows how to read all the characters in a file by using the method. It checks whether each character is a letter, digit, or white space before adding the character to an instance of the class. - + +## Examples + The following example shows how to read all the characters in a file by using the method. It checks whether each character is a letter, digit, or white space before adding the character to an instance of the class. + :::code language="csharp" source="~/snippets/csharp/System.IO/StreamReader/Overview/example42.cs" id="Snippet42"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.StreamReader/VB/example42.vb" id="Snippet42"::: @@ -2235,13 +2235,13 @@ Following a call to , any operations on th Reads a specified maximum number of characters from the current stream and writes the data to a buffer, beginning at the specified index. The number of characters that have been read. The number will be less than or equal to , depending on whether all input characters have been read. - . - + . + ]]> @@ -2364,11 +2364,11 @@ Following a call to , any operations on th Reads a specified maximum number of characters from the current stream asynchronously and writes the data to a buffer, beginning at the specified index. A task that represents the asynchronous read operation. The value of the parameter contains the total number of characters read into the buffer. The result value can be less than the number of characters requested if the number of characters currently available is less than the requested number, or it can be 0 (zero) if the end of the stream has been reached. - , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . ]]> @@ -2441,26 +2441,26 @@ Following a call to , any operations on th Reads a line of characters from the current stream and returns the data as a string. The next line from the input stream, or if the end of the input stream is reached. - . - - If the current method throws an , the reader's position in the underlying object is advanced by the number of characters the method was able to read, but the characters already read into the internal buffer are discarded. If you manipulate the position of the underlying stream after reading data into the buffer, the position of the underlying stream might not match the position of the internal buffer. To reset the internal buffer, call the method; however, this method slows performance and should be called only when absolutely necessary. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following code example reads lines from a file until the end of the file is reached. - + . + + If the current method throws an , the reader's position in the underlying object is advanced by the number of characters the method was able to read, but the characters already read into the internal buffer are discarded. If you manipulate the position of the underlying stream after reading data into the buffer, the position of the underlying stream might not match the position of the internal buffer. To reset the internal buffer, call the method; however, this method slows performance and should be called only when absolutely necessary. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following code example reads lines from a file until the end of the file is reached. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/StrmReader ReadLine/CPP/strmreader readline.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.IO/StreamReader/ReadLine/strmreader readline.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/StrmReader ReadLine/VB/strmreader readline.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/StrmReader ReadLine/VB/strmreader readline.vb" id="Snippet1"::: + ]]> There is insufficient memory to allocate a buffer for the returned string. @@ -2528,10 +2528,10 @@ Following a call to , any operations on th ## 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 read the first line of a file by using the method. - + +## Examples + The following example shows how to read the first line of a file by using the method. + :::code language="csharp" source="~/snippets/csharp/System.IO/StreamReader/Overview/example41.cs" id="Snippet41"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.StreamReader/VB/example41.vb" id="Snippet41"::: @@ -2649,30 +2649,30 @@ This method stores in the task it returns all non-usage exceptions that the meth Reads all characters from the current position to the end of the stream. The rest of the stream as a string, from the current position to the end. If the current position is at the end of the stream, returns an empty string (""). - . - - works best when you need to read all the input from the current position to the end of the stream. If more control is needed over how many characters are read from the stream, use the method overload, which generally results in better performance. - - assumes that the stream knows when it has reached an end. For interactive protocols in which the server sends data only when you ask for it and does not close the connection, might block indefinitely because it does not reach an end, and should be avoided. - - Note that when using the method, it is more efficient to use a buffer that is the same size as the internal buffer of the stream. If the size of the buffer was unspecified when the stream was constructed, its default size is 4 kilobytes (4096 bytes). - - If the current method throws an , the reader's position in the underlying object is advanced by the number of characters the method was able to read, but the characters already read into the internal buffer are discarded. If you manipulate the position of the underlying stream after reading data into the buffer, the position of the underlying stream might not match the position of the internal buffer. To reset the internal buffer, call the method; however, this method slows performance and should be called only when absolutely necessary. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following code example reads all the way to the end of a file in one operation. - + . + + works best when you need to read all the input from the current position to the end of the stream. If more control is needed over how many characters are read from the stream, use the method overload, which generally results in better performance. + + assumes that the stream knows when it has reached an end. For interactive protocols in which the server sends data only when you ask for it and does not close the connection, might block indefinitely because it does not reach an end, and should be avoided. + + Note that when using the method, it is more efficient to use a buffer that is the same size as the internal buffer of the stream. If the size of the buffer was unspecified when the stream was constructed, its default size is 4 kilobytes (4096 bytes). + + If the current method throws an , the reader's position in the underlying object is advanced by the number of characters the method was able to read, but the characters already read into the internal buffer are discarded. If you manipulate the position of the underlying stream after reading data into the buffer, the position of the underlying stream might not match the position of the internal buffer. To reset the internal buffer, call the method; however, this method slows performance and should be called only when absolutely necessary. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following code example reads all the way to the end of a file in one operation. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/StrmReader ReadToEnd/CPP/strmreader readtoend.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.IO/StreamReader/ReadToEnd/strmreader readtoend.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/StrmReader ReadToEnd/VB/strmreader readtoend.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/StrmReader ReadToEnd/VB/strmreader readtoend.vb" id="Snippet1"::: + ]]> There is insufficient memory to allocate a buffer for the returned string. @@ -2734,17 +2734,17 @@ This method stores in the task it returns all non-usage exceptions that the meth Reads all characters from the current position to the end of the stream asynchronously and returns them as one string. A task that represents the asynchronous read operation. The value of the parameter contains a string with the characters from the current position to the end of the stream. - , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . - -## Examples - The following example shows how to read the contents of a file by using the method. - + +## Examples + The following example shows how to read the contents of a file by using the method. + :::code language="csharp" source="~/snippets/csharp/System.IO/StreamReader/Overview/example40.cs" id="Snippet40"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.StreamReader/VB/example40.vb" id="Snippet40"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.StreamReader/VB/example40.vb" id="Snippet40"::: ]]> diff --git a/xml/System.IO/StreamWriter.xml b/xml/System.IO/StreamWriter.xml index 6a82bdbb361..8df45fbb841 100644 --- a/xml/System.IO/StreamWriter.xml +++ b/xml/System.IO/StreamWriter.xml @@ -84,28 +84,28 @@ Implements a for writing characters to a stream in a particular encoding. - is designed for character output in a particular encoding, whereas classes derived from are designed for byte input and output. - + is designed for character output in a particular encoding, whereas classes derived from are designed for byte input and 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. - - defaults to using an instance of unless specified otherwise. This instance of `UTF8Encoding` is constructed without a byte order mark (BOM), so its method returns an empty byte array. The default UTF-8 encoding for this constructor throws an exception on invalid bytes. This behavior is different from the behavior provided by the encoding object in the property. To specify a BOM and determine whether an exception is thrown on invalid bytes, use a constructor that accepts an encoding object as a parameter, such as or . - - By default, a is not thread safe. See for a thread-safe wrapper. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following example shows how to use a object to write a file that lists the directories on the C drive, and then uses a object to read and display each directory name. A good practice is to use these objects in a `using` statement so that the unmanaged resources are correctly disposed. The `using` statement automatically calls on the object when the code that is using it has completed. The constructor used in this example is not supported for use in Windows Store Apps. - +> 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. + + defaults to using an instance of unless specified otherwise. This instance of `UTF8Encoding` is constructed without a byte order mark (BOM), so its method returns an empty byte array. The default UTF-8 encoding for this constructor throws an exception on invalid bytes. This behavior is different from the behavior provided by the encoding object in the property. To specify a BOM and determine whether an exception is thrown on invalid bytes, use a constructor that accepts an encoding object as a parameter, such as or . + + By default, a is not thread safe. See for a thread-safe wrapper. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following example shows how to use a object to write a file that lists the directories on the C drive, and then uses a object to read and display each directory name. A good practice is to use these objects in a `using` statement so that the unmanaged resources are correctly disposed. The `using` statement automatically calls on the object when the code that is using it has completed. The constructor used in this example is not supported for use in Windows Store Apps. + :::code language="csharp" source="~/snippets/csharp/System.IO/StreamWriter/Overview/program.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/streamreadwrite/vb/module1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/streamreadwrite/vb/module1.vb" id="Snippet1"::: + ]]> @@ -182,26 +182,26 @@ The stream to write to. Initializes a new instance of the class for the specified stream by using UTF-8 encoding and the default buffer size. - with UTF-8 encoding without a Byte-Order Mark (BOM), so its method returns an empty byte array. The default UTF-8 encoding for this constructor throws an exception on invalid bytes. This behavior is different from the behavior provided by the encoding object in the property. To specify whether an exception is thrown on invalid bytes, use a constructor that accepts an encoding object as a parameter, such as . The property is initialized using the `stream` parameter. The position of the stream is not reset. - - The object calls on the provided object when is called. - + with UTF-8 encoding without a Byte-Order Mark (BOM), so its method returns an empty byte array. The default UTF-8 encoding for this constructor throws an exception on invalid bytes. This behavior is different from the behavior provided by the encoding object in the property. To specify whether an exception is thrown on invalid bytes, use a constructor that accepts an encoding object as a parameter, such as . The property is initialized using the `stream` parameter. The position of the stream is not reset. + + The object calls on the provided object when is called. + > [!CAUTION] -> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable and could cause an exception to be thrown. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following code example demonstrates this constructor. - +> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable and could cause an exception to be thrown. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following code example demonstrates this constructor. + :::code language="csharp" source="~/snippets/csharp/System.IO/StreamWriter/.ctor/program1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.io.streamwriter.ctor/vb/program1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.io.streamwriter.ctor/vb/program1.vb" id="Snippet1"::: + ]]> @@ -257,42 +257,42 @@ - + The complete file path to write to. can be a file name. Initializes a new instance of the class for the specified file by using the default encoding and buffer size. - with UTF-8 encoding without a Byte-Order Mark (BOM), so its method returns an empty byte array. The default UTF-8 encoding for this constructor throws an exception on invalid bytes. This behavior is different from the behavior provided by the encoding object in the property. To specify a BOM and determine whether an exception is thrown on invalid bytes, use a constructor that accepts an encoding object as a parameter, such as . - - The `path` parameter can be a file name, including a file on a Universal Naming Convention (UNC) share. If the file exists, it is overwritten; otherwise, a new file is created. - - The `path` parameter is not required to be a file stored on disk; it can be any part of a system that supports access using streams. - + with UTF-8 encoding without a Byte-Order Mark (BOM), so its method returns an empty byte array. The default UTF-8 encoding for this constructor throws an exception on invalid bytes. This behavior is different from the behavior provided by the encoding object in the property. To specify a BOM and determine whether an exception is thrown on invalid bytes, use a constructor that accepts an encoding object as a parameter, such as . + + The `path` parameter can be a file name, including a file on a Universal Naming Convention (UNC) share. If the file exists, it is overwritten; otherwise, a new file is created. + + The `path` parameter is not required to be a file stored on disk; it can be any part of a system that supports access using streams. + > [!CAUTION] -> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable and could cause an exception to be thrown. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following code example demonstrates this constructor. - +> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable and could cause an exception to be thrown. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following code example demonstrates this constructor. + :::code language="csharp" source="~/snippets/csharp/System.IO/StreamWriter/.ctor/program5.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.io.streamwriter.ctor/vb/program5.vb" id="Snippet5"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.io.streamwriter.ctor/vb/program5.vb" id="Snippet5"::: + ]]> Access is denied. - is an empty string (""). - - -or- - + is an empty string (""). + + -or- + contains the name of a system device (com1, com2, and so on). is . @@ -361,26 +361,26 @@ The character encoding to use. Initializes a new instance of the class for the specified stream by using the specified encoding and the default buffer size. - property using the encoding parameter, and the property using the stream parameter. The position of the stream is not reset. For additional information, see . - - The object calls on the provided object when is called. - + property using the encoding parameter, and the property using the stream parameter. The position of the stream is not reset. For additional information, see . + + The object calls on the provided object when is called. + > [!CAUTION] -> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following example demonstrates this constructor. - +> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following example demonstrates this constructor. + :::code language="csharp" source="~/snippets/csharp/System.IO/StreamWriter/.ctor/program2.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.io.streamwriter.ctor/vb/program2.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.io.streamwriter.ctor/vb/program2.vb" id="Snippet2"::: + ]]> @@ -437,8 +437,8 @@ - - + + The complete file path to write to. @@ -446,36 +446,36 @@ to append data to the file; to overwrite the file. If the specified file does not exist, this parameter has no effect, and the constructor creates a new file. Initializes a new instance of the class for the specified file by using the default encoding and buffer size. If the file exists, it can be either overwritten or appended to. If the file does not exist, this constructor creates a new file. - with UTF-8 encoding without a Byte-Order Mark (BOM), so its method returns an empty byte array. The default UTF-8 encoding for this constructor throws an exception on invalid bytes. This behavior is different from the behavior provided by the encoding object in the property. To specify a BOM and determine whether an exception is thrown on invalid bytes, use a constructor that accepts an encoding object as a parameter, such as . - - The `path` parameter can be a file name, including a file on a Universal Naming Convention (UNC) share. - - The `path` parameter is not required to be a file stored on disk; it can be any part of a system that supports access using streams. - + with UTF-8 encoding without a Byte-Order Mark (BOM), so its method returns an empty byte array. The default UTF-8 encoding for this constructor throws an exception on invalid bytes. This behavior is different from the behavior provided by the encoding object in the property. To specify a BOM and determine whether an exception is thrown on invalid bytes, use a constructor that accepts an encoding object as a parameter, such as . + + The `path` parameter can be a file name, including a file on a Universal Naming Convention (UNC) share. + + The `path` parameter is not required to be a file stored on disk; it can be any part of a system that supports access using streams. + > [!CAUTION] -> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following code example demonstrates this constructor. - +> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following code example demonstrates this constructor. + :::code language="csharp" source="~/snippets/csharp/System.IO/StreamWriter/.ctor/program6.cs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.io.streamwriter.ctor/vb/program6.vb" id="Snippet6"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.io.streamwriter.ctor/vb/program6.vb" id="Snippet6"::: + ]]> Access is denied. - is empty. - - -or- - + is empty. + + -or- + contains the name of a system device (com1, com2, and so on). is . @@ -592,26 +592,26 @@ The buffer size, in bytes. Initializes a new instance of the class for the specified stream by using the specified encoding and buffer size. - property using the `encoding` parameter, and the property using the `stream` parameter. The position of the stream is not reset. For additional information, see . - - The object calls on the provided object when is called. - + property using the `encoding` parameter, and the property using the `stream` parameter. The position of the stream is not reset. For additional information, see . + + The object calls on the provided object when is called. + > [!CAUTION] -> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following example demonstrates this constructor. - +> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following example demonstrates this constructor. + :::code language="csharp" source="~/snippets/csharp/System.IO/StreamWriter/.ctor/program3.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.io.streamwriter.ctor/vb/program3.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.io.streamwriter.ctor/vb/program3.vb" id="Snippet3"::: + ]]> @@ -670,9 +670,9 @@ - - - + + + The complete file path to write to. @@ -681,36 +681,36 @@ The character encoding to use. Initializes a new instance of the class for the specified file by using the specified encoding and default buffer size. If the file exists, it can be either overwritten or appended to. If the file does not exist, this constructor creates a new file. - property using the encoding parameter. For additional information, see . - - `path` can be a file name, including a file on a Universal Naming Convention (UNC) share. - - `path` is not required to be a file stored on disk; it can be any part of a system that supports access via streams. - + property using the encoding parameter. For additional information, see . + + `path` can be a file name, including a file on a Universal Naming Convention (UNC) share. + + `path` is not required to be a file stored on disk; it can be any part of a system that supports access via streams. + > [!CAUTION] -> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following example demonstrates this constructor. - +> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following example demonstrates this constructor. + :::code language="csharp" source="~/snippets/csharp/System.IO/StreamWriter/.ctor/program7.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.io.streamwriter.ctor/vb/program7.vb" id="Snippet7"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.io.streamwriter.ctor/vb/program7.vb" id="Snippet7"::: + ]]> Access is denied. - is empty. - - -or- - + is empty. + + -or- + contains the name of a system device (com1, com2, and so on). is . @@ -834,24 +834,24 @@ to leave the stream open after the object is disposed; otherwise, . Initializes a new instance of the class for the specified stream by using the specified encoding and buffer size, and optionally leaves the stream open. - object calls on the provided object when is called. - - This constructor initializes the property by using the `encoding` parameter, and initializes the property by using the `stream` parameter. The position of the stream is not reset. For additional information, see the property. - + object calls on the provided object when is called. + + This constructor initializes the property by using the `encoding` parameter, and initializes the property by using the `stream` parameter. The position of the stream is not reset. For additional information, see the property. + > [!CAUTION] -> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. - - - -## Examples - The following example demonstrates this constructor. - +> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. + + + +## Examples + The following example demonstrates this constructor. + :::code language="csharp" source="~/snippets/csharp/System.IO/StreamWriter/.ctor/program4.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.io.streamwriter.ctor/vb/program4.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.io.streamwriter.ctor/vb/program4.vb" id="Snippet4"::: + ]]> @@ -906,10 +906,10 @@ - - - - + + + + The complete file path to write to. @@ -919,35 +919,35 @@ The buffer size, in bytes. Initializes a new instance of the class for the specified file on the specified path, using the specified encoding and buffer size. If the file exists, it can be either overwritten or appended to. If the file does not exist, this constructor creates a new file. - property using the encoding parameter. For additional information, see . - - `path` can be a file name, including a file on a Universal Naming Convention (UNC) share. - - `path` is not required to be a file stored on disk; it can be any part of a system that supports access via streams. - + property using the encoding parameter. For additional information, see . + + `path` can be a file name, including a file on a Universal Naming Convention (UNC) share. + + `path` is not required to be a file stored on disk; it can be any part of a system that supports access via streams. + > [!CAUTION] -> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following example demonstrates this constructor. - +> When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following example demonstrates this constructor. + :::code language="csharp" source="~/snippets/csharp/System.IO/StreamWriter/.ctor/program8.cs" id="Snippet8"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.io.streamwriter.ctor/vb/program8.vb" id="Snippet8"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.io.streamwriter.ctor/vb/program8.vb" id="Snippet8"::: + ]]> - is an empty string (""). - - -or- - + is an empty string (""). + + -or- + contains the name of a system device (com1, com2, and so on). or is . @@ -1013,26 +1013,26 @@ to force to flush its buffer; otherwise, . - or . Setting to `true` means that data will be flushed from the buffer to the stream after each write operation, 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. - - When `AutoFlush` is set to `false`, `StreamWriter` will do a limited amount of buffering, both internally and potentially in the encoder from the encoding you passed in. You can get better performance by setting `AutoFlush` to `false`, assuming that you always call `Close` (or at least `Flush`) when you're done writing with a `StreamWriter`. - - For example, set `AutoFlush` to `true` when you are writing to a device where the user expects immediate feedback. `Console.Out` is one of these cases: The `StreamWriter` used internally for writing to `Console` flushes all its internal state except the encoder state after every call to . - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following example shows the syntax for using the `AutoFlush` property. - + or . Setting to `true` means that data will be flushed from the buffer to the stream after each write operation, 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. + + When `AutoFlush` is set to `false`, `StreamWriter` will do a limited amount of buffering, both internally and potentially in the encoder from the encoding you passed in. You can get better performance by setting `AutoFlush` to `false`, assuming that you always call `Close` (or at least `Flush`) when you're done writing with a `StreamWriter`. + + For example, set `AutoFlush` to `true` when you are writing to a device where the user expects immediate feedback. `Console.Out` is one of these cases: The `StreamWriter` used internally for writing to `Console` flushes all its internal state except the encoder state after every call to . + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following example shows the syntax for using the `AutoFlush` property. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.StreamWriter/CPP/logger.cpp" id="Snippet5"::: :::code language="csharp" source="~/snippets/csharp/System.IO/StreamWriter/AutoFlush/logger.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.StreamWriter/VB/logger.vb" id="Snippet5"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.StreamWriter/VB/logger.vb" id="Snippet5"::: + ]]> File and Stream I/O @@ -1087,11 +1087,11 @@ Gets the underlying stream that interfaces with a backing store. The stream this is writing to. - File and Stream I/O @@ -1143,26 +1143,26 @@ Closes the current object and the underlying stream. - . - - This implementation of calls the method passing a `true` value. - - You must call to ensure that all data is correctly written out to the underlying stream. Following a call to , any operations on the might raise exceptions. If there is insufficient space on the disk, calling will raise an exception. - - 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 - The following code example demonstrates the `Close` method. - + . + + This implementation of calls the method passing a `true` value. + + You must call to ensure that all data is correctly written out to the underlying stream. Following a call to , any operations on the might raise exceptions. If there is insufficient space on the disk, calling will raise an exception. + + 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 + The following code example demonstrates the `Close` method. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.StreamWriter/CPP/logger.cpp" id="Snippet17"::: :::code language="csharp" source="~/snippets/csharp/System.IO/StreamWriter/AutoFlush/logger.cs" id="Snippet17"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.StreamWriter/VB/logger.vb" id="Snippet17"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.StreamWriter/VB/logger.vb" id="Snippet17"::: + ]]> The current encoding does not support displaying half of a Unicode surrogate pair. @@ -1222,18 +1222,18 @@ to release both managed and unmanaged resources; to release only unmanaged resources. Causes any buffered data to be written to the underlying stream, releases the unmanaged resources used by the , and optionally the managed resources. - references. This method invokes the `Dispose` method of each referenced object. - + references. This method invokes the `Dispose` method of each referenced object. + ]]> The current encoding does not support displaying half of a Unicode surrogate pair. - can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed in an earlier call to . - + can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed in an earlier call to . + This method calls the dispose method of the base class, . File and Stream I/O @@ -1329,22 +1329,22 @@ Gets the in which the output is written. The specified in the constructor for the current instance, or if an encoding was not specified. - . This allows the XML code to consume an arbitrary and generate the correct XML header. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - The following example retrieves the encoding of the specified instance. - + . This allows the XML code to consume an arbitrary and generate the correct XML header. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + The following example retrieves the encoding of the specified instance. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.IO.StreamWriter/CPP/logger.cpp" id="Snippet11"::: :::code language="csharp" source="~/snippets/csharp/System.IO/StreamWriter/AutoFlush/logger.cs" id="Snippet11"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.StreamWriter/VB/logger.vb" id="Snippet11"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.StreamWriter/VB/logger.vb" id="Snippet11"::: + ]]> File and Stream I/O @@ -1385,7 +1385,7 @@ @@ -1442,15 +1442,15 @@ For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/commo Clears all buffers for the current writer and causes any buffered data to be written to the underlying stream. - . - - Flushing the stream will not flush its underlying encoder unless you explicitly call `Flush` or . Setting to `true` means that data will be flushed from the buffer to the stream after each write operation, 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 a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - + . + + Flushing the stream will not flush its underlying encoder unless you explicitly call `Flush` or . Setting to `true` means that data will be flushed from the buffer to the stream after each write operation, 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 a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + ]]> The current writer is closed. @@ -1602,24 +1602,24 @@ For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/commo Provides a with no backing store that can be written to, but not read from. - File and Stream I/O @@ -1688,15 +1688,15 @@ For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/commo The character to write to the stream. Writes a character to the stream. - . - - The specified character is written to the underlying stream unless the end of the stream is reached prematurely. If is `true`, is invoked automatically. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - + . + + The specified character is written to the underlying stream unless the end of the stream is reached prematurely. If is `true`, is invoked automatically. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + ]]> An I/O error occurs. @@ -1770,17 +1770,17 @@ For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/commo A character array containing the data to write. If is , nothing is written. Writes a character array to the stream. - . - - The specified characters are written to the underlying stream unless the end of the stream is reached prematurely. If is `true`, is invoked automatically. - - This method might provide faster performance than `Write` (`char[],``int,``int`) because it has fewer arguments to check. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - + . + + The specified characters are written to the underlying stream unless the end of the stream is reached prematurely. If is `true`, is invoked automatically. + + This method might provide faster performance than `Write` (`char[],``int,``int`) because it has fewer arguments to check. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + ]]> An I/O error occurs. @@ -1903,17 +1903,17 @@ For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/commo The string to write to the stream. If is null, nothing is written. Writes a string to the stream. - . - - The specified is written to the underlying stream unless the end of the stream is reached prematurely. - - is invoked automatically if is `true`. If `value` is `null`, no entries are written. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - + . + + The specified is written to the underlying stream unless the end of the stream is reached prematurely. + + is invoked automatically if is `true`. If `value` is `null`, no entries are written. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + ]]> @@ -2122,24 +2122,24 @@ See for a descr The maximum number of characters to write. Writes a subarray of characters to the stream. - . - - The characters are read from `buffer` beginning at `index` and continuing through `index` + (`count` - 1). All characters are written to the underlying stream unless the end of the underlying stream is reached prematurely. is invoked automatically if is `true`. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - - -## Examples - This example writes eight characters from a 13-element array to a file, beginning at the third element of the array. - + . + + The characters are read from `buffer` beginning at `index` and continuing through `index` + (`count` - 1). All characters are written to the underlying stream unless the end of the underlying stream is reached prematurely. is invoked automatically if is `true`. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + + +## Examples + This example writes eight characters from a 13-element array to a file, beginning at the third element of the array. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic StreamWriter.Write2 Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.IO/StreamWriter/Write/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic StreamWriter.Write2 Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic StreamWriter.Write2 Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -2369,15 +2369,15 @@ See , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . - -## Examples - The following example shows how to write a single character (the letter "a") to a text file by using the method. - + +## Examples + The following example shows how to write a single character (the letter "a") to a text file by using the method. + :::code language="csharp" source="~/snippets/csharp/System.IO/StreamWriter/AutoFlush/example20.cs" id="Snippet20"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.StreamWriter/VB/example20.vb" id="Snippet20"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.StreamWriter/VB/example20.vb" id="Snippet20"::: ]]> @@ -2453,10 +2453,10 @@ This method stores in the task it returns all non-usage exceptions that the meth ## 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 write a string to a text file by using the method. - + +## Examples + The following example shows how to write a string to a text file by using the method. + :::code language="csharp" source="~/snippets/csharp/System.IO/StreamWriter/AutoFlush/example21.cs" id="Snippet21"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.StreamWriter/VB/example21.vb" id="Snippet21"::: @@ -2582,10 +2582,10 @@ This method stores in the task it returns all non-usage exceptions that the meth ## 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 write multiple characters to a text file by using the method. - + +## Examples + The following example shows how to write multiple characters to a text file by using the method. + :::code language="csharp" source="~/snippets/csharp/System.IO/StreamWriter/AutoFlush/example24.cs" id="Snippet24"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.StreamWriter/VB/example24.vb" id="Snippet24"::: @@ -2647,7 +2647,7 @@ This method stores in the task it returns all non-usage exceptions that the meth The character span to write to the stream. Writes the text representation of a character span to the stream, followed by a line terminator. - Asynchronously writes a line terminator to the stream. A task that represents the asynchronous write operation. - property. - + property. + ]]> The stream writer is disposed. @@ -3134,19 +3134,19 @@ See Asynchronously writes a character to the stream, followed by a line terminator. A task that represents the asynchronous write operation. - property. - - - -## Examples - The following example shows how to write a single character (the letter "a") to a line in a text file, followed by another line that contains a single character (the letter "b"), by using the method. - + property. + + + +## Examples + The following example shows how to write a single character (the letter "a") to a line in a text file, followed by another line that contains a single character (the letter "b"), by using the method. + :::code language="csharp" source="~/snippets/csharp/System.IO/StreamWriter/AutoFlush/example22.cs" id="Snippet22"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.StreamWriter/VB/example22.vb" id="Snippet22"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.StreamWriter/VB/example22.vb" id="Snippet22"::: + ]]> The stream writer is disposed. @@ -3216,16 +3216,16 @@ See Asynchronously writes a string to the stream, followed by a line terminator. A task that represents the asynchronous write operation. - property. 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 write two lines that consist of string values to a text file by using the method. - + +## Examples + The following example shows how to write two lines that consist of string values to a text file by using the method. + :::code language="csharp" source="~/snippets/csharp/System.IO/StreamWriter/AutoFlush/example23.cs" id="Snippet23"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.StreamWriter/VB/example23.vb" id="Snippet23"::: @@ -3284,12 +3284,12 @@ See Asynchronously writes the text representation of a character memory region to the stream, followed by a line terminator. A task that represents the asynchronous write operation. - field. - + ]]> The cancellation token was canceled. This exception is stored into the returned task. @@ -3354,19 +3354,19 @@ The line terminator is defined by the fi Asynchronously writes a subarray of characters to the stream, followed by a line terminator. A task that represents the asynchronous write operation. - property. - - - -## Examples - The following example shows how to write characters to two separate lines in a text file by using the method. The first line contains the first 11 characters from the string (the letters "First line" followed by a space). The second line contains the remaining characters from the string (the letters "and second line"). - + property. + + + +## Examples + The following example shows how to write characters to two separate lines in a text file by using the method. The first line contains the first 11 characters from the string (the letters "First line" followed by a space). The second line contains the remaining characters from the string (the letters "and second line"). + :::code language="csharp" source="~/snippets/csharp/System.IO/StreamWriter/AutoFlush/example25.cs" id="Snippet25"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.StreamWriter/VB/example25.vb" id="Snippet25"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.StreamWriter/VB/example25.vb" id="Snippet25"::: + ]]> diff --git a/xml/System.IO/TextReader.xml b/xml/System.IO/TextReader.xml index 40a756680c0..30d2fdd4051 100644 --- a/xml/System.IO/TextReader.xml +++ b/xml/System.IO/TextReader.xml @@ -94,22 +94,22 @@ Represents a reader that can read a sequential series of characters. - is the abstract base class of and , which read characters from streams and strings, respectively. Use these derived classes to open a text file for reading a specified range of characters, or to create a reader based on an existing stream. - + is the abstract base class of and , which read characters from streams and strings, respectively. Use these derived classes to open a text file for reading a specified range of characters, or to create a reader based on an existing stream. + > [!IMPORTANT] -> This type implements the interface. When you have finished using any type that derives from this 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 Dispose and the "Using an Object that Implements IDisposable" section in the interface topic. - - - -## Examples - The class is an abstract class. Therefore, you do not instantiate it in your code. The class derives from and provides implementations of the members for reading from a stream. The following example shows how to read all the characters in a file by using the method. It checks whether each character is a letter, digit, or white space before adding the character to an instance of the class. - +> This type implements the interface. When you have finished using any type that derives from this 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 Dispose and the "Using an Object that Implements IDisposable" section in the interface topic. + + + +## Examples + The class is an abstract class. Therefore, you do not instantiate it in your code. The class derives from and provides implementations of the members for reading from a stream. The following example shows how to read all the characters in a file by using the method. It checks whether each character is a letter, digit, or white space before adding the character to an instance of the class. + :::code language="csharp" source="~/snippets/csharp/System.IO/StreamReader/Overview/example42.cs" id="Snippet42"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.StreamReader/VB/example42.vb" id="Snippet42"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.StreamReader/VB/example42.vb" id="Snippet42"::: + ]]> @@ -166,11 +166,11 @@ Initializes a new instance of the class. - @@ -224,14 +224,14 @@ Closes the and releases any system resources associated with the . - method and passes it a `true` value. - + method and passes it a `true` value. + > [!NOTE] -> In derived classes, do not override the method. Instead, override the method to add code for releasing resources. - +> In derived classes, do not override the method. Instead, override the method to add code for releasing resources. + ]]> @@ -301,16 +301,16 @@ Releases all resources used by the object. - 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). - + 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 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 method. + ]]> @@ -366,19 +366,19 @@ to release both managed and unmanaged resources; to release only unmanaged resources. Releases the unmanaged resources used by the and optionally releases the managed resources. - method, if it has been overridden. `Dispose()` invokes this method with the `disposing` parameter set to `true`. `Finalize` invokes this method with `disposing` set to `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. - + + 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. + ]]> - can be called multiple times by other objects. When overriding this method, be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement this method, see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). - + can be called multiple times by other objects. When overriding this method, be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement this method, see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). + For more information about and , see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). File and Stream I/O @@ -432,19 +432,19 @@ Provides a with no data to read from. - text reader is similar to reading from the end of a stream: - -- The and methods return -1. - -- The method returns zero. - -- The method returns `null`. - -- The method returns an empty string. - + text reader is similar to reading from the end of a stream: + +- The and methods return -1. + +- The method returns zero. + +- The method returns `null`. + +- The method returns an empty string. + ]]> @@ -502,15 +502,15 @@ Reads the next character without changing the state of the reader or the character source. Returns the next available character without actually reading it from the reader. An integer representing the next character to be read, or -1 if no more characters are available or the reader does not support seeking. - method returns an integer value in order to determine whether the end of the file, or another error has occurred. This allows a user to first check if the returned value is -1 before casting it to a type. - - The current position of the is not changed by this operation. The returned value is -1 if no more characters are available. The default implementation returns -1. - - The class is an abstract class. Therefore, you do not instantiate it in your code. For an example of using the method, see the method. - + method returns an integer value in order to determine whether the end of the file, or another error has occurred. This allows a user to first check if the returned value is -1 before casting it to a type. + + The current position of the is not changed by this operation. The returned value is -1 if no more characters are available. The default implementation returns -1. + + The class is an abstract class. Therefore, you do not instantiate it in your code. For an example of using the method, see the method. + ]]> The is closed. @@ -581,11 +581,11 @@ Reads the next character from the text reader and advances the character position by one character. The next character from the text reader, or -1 if no more characters are available. The default implementation returns -1. - class is an abstract class. Therefore, you do not instantiate it in your code. For an example of using the method, see the method. - + class is an abstract class. Therefore, you do not instantiate it in your code. For an example of using the method, see the method. + ]]> The is closed. @@ -706,13 +706,13 @@ Reads a specified maximum number of characters from the current reader and writes the data to a buffer, beginning at the specified index. The number of characters that have been read. The number will be less than or equal to , depending on whether the data is available within the reader. This method returns 0 (zero) if it is called when no more characters are left to read. - is a blocking version of this method. - - The class is an abstract class. Therefore, you do not instantiate it in your code. For an example of using the method, see the method. - + is a blocking version of this method. + + The class is an abstract class. Therefore, you do not instantiate it in your code. For an example of using the method, see the method. + ]]> @@ -840,13 +840,13 @@ Reads a specified maximum number of characters from the current text reader asynchronously and writes the data to a buffer, beginning at the specified index. A task that represents the asynchronous read operation. The value of the parameter contains the total number of bytes read into the buffer. The result value can be less than the number of bytes requested if the number of bytes currently available is less than the requested number, or it can be 0 (zero) if the end of the text has been reached. - class is an abstract class. Therefore, you do not instantiate it in your code. For an example of using the method, see the method. - + class is an abstract class. Therefore, you do not instantiate it in your code. For an example of using the method, see the method. + 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 . ]]> @@ -975,13 +975,13 @@ Reads a specified maximum number of characters from the current text reader and writes the data to a buffer, beginning at the specified index. The number of characters that have been read. The number will be less than or equal to , depending on whether all input characters have been read. - . - + . + ]]> @@ -1108,11 +1108,11 @@ Reads a specified maximum number of characters from the current text reader asynchronously and writes the data to a buffer, beginning at the specified index. A task that represents the asynchronous read operation. The value of the parameter contains the total number of bytes read into the buffer. The result value can be less than the number of bytes requested if the number of bytes currently available is less than the requested number, or it can be 0 (zero) if the end of the text has been reached. - , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . ]]> @@ -1186,17 +1186,17 @@ Reads a line of characters from the text reader and returns the data as a string. The next line from the reader, or if all characters have been read. - , or the end-of-stream marker. The string that is returned does not contain the terminating carriage return or line feed. The return value is `null` if the end of the input stream has been reached. - - If the method throws an exception, the reader's position in the underlying is advanced by the number of characters the method was able to read, but the characters that were already read into the internal buffer are discarded. Because the position of the reader in the stream cannot be changed, the characters that were already read are unrecoverable and can be accessed only by reinitializing the object. If the initial position within the stream is unknown or the stream does not support seeking, the underlying also needs to be reinitialized. - - To avoid such a situation and produce robust code you should use the method and store the read characters in a preallocated buffer. - - The class is an abstract class. Therefore, you do not instantiate it in your code. For an example of using the method, see the method. - + , or the end-of-stream marker. The string that is returned does not contain the terminating carriage return or line feed. The return value is `null` if the end of the input stream has been reached. + + If the method throws an exception, the reader's position in the underlying is advanced by the number of characters the method was able to read, but the characters that were already read into the internal buffer are discarded. Because the position of the reader in the stream cannot be changed, the characters that were already read are unrecoverable and can be accessed only by reinitializing the object. If the initial position within the stream is unknown or the stream does not support seeking, the underlying also needs to be reinitialized. + + To avoid such a situation and produce robust code you should use the method and store the read characters in a preallocated buffer. + + The class is an abstract class. Therefore, you do not instantiate it in your code. For an example of using the method, see the method. + ]]> An I/O error occurs. @@ -1263,13 +1263,13 @@ Reads a line of characters asynchronously and returns the data as a string. A task that represents the asynchronous read operation. The value of the parameter contains the next line from the text reader, or is if all of the characters have been read. - class is an abstract class. Therefore, you do not instantiate it in your code. For an example of using the method, see the method. - - If the current represents the standard input stream returned by the property, the method executes synchronously rather than asynchronously. - + class is an abstract class. Therefore, you do not instantiate it in your code. For an example of using the method, see the method. + + If the current represents the standard input stream returned by the property, the method executes synchronously rather than asynchronously. + 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 . ]]> @@ -1391,15 +1391,15 @@ This method stores in the task it returns all non-usage exceptions that the meth Reads all characters from the current position to the end of the text reader and returns them as one string. A string that contains all characters from the current position to the end of the text reader. - exception, the reader's position in the underlying is advanced by the number of characters the method was able to read, but the characters that were already read into the internal buffer are discarded. Because the position of the reader in the stream cannot be changed, the characters that were already read are unrecoverable and can be accessed only by reinitializing the . If the initial position within the stream is unknown or the stream does not support seeking, the underlying also needs to be reinitialized. - - To avoid such a situation and produce robust code you should use the method and store the read characters in a preallocated buffer. - - The class is an abstract class. Therefore, you do not instantiate it in your code. For an example of using the method, see the method. - + exception, the reader's position in the underlying is advanced by the number of characters the method was able to read, but the characters that were already read into the internal buffer are discarded. Because the position of the reader in the stream cannot be changed, the characters that were already read are unrecoverable and can be accessed only by reinitializing the . If the initial position within the stream is unknown or the stream does not support seeking, the underlying also needs to be reinitialized. + + To avoid such a situation and produce robust code you should use the method and store the read characters in a preallocated buffer. + + The class is an abstract class. Therefore, you do not instantiate it in your code. For an example of using the method, see the method. + ]]> An I/O error occurs. @@ -1469,11 +1469,11 @@ This method stores in the task it returns all non-usage exceptions that the meth Reads all characters from the current position to the end of the text reader asynchronously and returns them as one string. A task that represents the asynchronous read operation. The value of the parameter contains a string with the characters from the current position to the end of the text reader. - class is an abstract class. Therefore, you do not instantiate it in your code. For an example of using the method, see the method. - + class is an abstract class. Therefore, you do not instantiate it in your code. For an example of using the method, see the method. + 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 . ]]> @@ -1584,18 +1584,18 @@ This method stores in the task it returns all non-usage exceptions that the meth System.IO.TextReader - + The to synchronize. Creates a thread-safe wrapper around the specified . A thread-safe . - instance and restricts access to it by multiple threads. All reads from the returned wrapper will be thread safe. - + instance and restricts access to it by multiple threads. All reads from the returned wrapper will be thread safe. + ]]> @@ -1641,7 +1641,7 @@ This method stores in the task it returns all non-usage exceptions that the meth instance is cast to an interface. ]]> diff --git a/xml/System.IO/TextWriter.xml b/xml/System.IO/TextWriter.xml index 86611d5e15b..9ef51688799 100644 --- a/xml/System.IO/TextWriter.xml +++ b/xml/System.IO/TextWriter.xml @@ -102,26 +102,26 @@ Represents a writer that can write a sequential series of characters. This class is abstract. - is the abstract base class of and , which write characters to streams and strings, respectively. Use an instance of to write an object to a string, write strings to a file, or to serialize XML. You can also use the instance of to write text to a custom backing store using the same APIs you would use for a string or a stream, or to add support for text formatting. - - All the `Write` methods of having primitive data types as parameters write out the values as strings. - - By default, a is not thread safe. See for a thread-safe wrapper. - + is the abstract base class of and , which write characters to streams and strings, respectively. Use an instance of to write an object to a string, write strings to a file, or to serialize XML. You can also use the instance of to write text to a custom backing store using the same APIs you would use for a string or a stream, or to add support for text formatting. + + All the `Write` methods of having primitive data types as parameters write out the values as strings. + + By default, a is not thread safe. See for a thread-safe wrapper. + > [!IMPORTANT] -> This type implements the interface. When you have finished using any type that derives from this 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 Dispose and the "Using an Object that Implements IDisposable" section in the interface topic. - +> This type implements the interface. When you have finished using any type that derives from this 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 Dispose and the "Using an Object that Implements IDisposable" section in the interface topic. + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - -## Examples + +## Examples The class is an abstract class. Therefore, you do not instantiate it in your code. The class derives from and provides implementations of the members for writing to a stream. The following example shows how to write two lines that consist of string values to a text file by using the method. - + :::code language="csharp" source="~/snippets/csharp/System.IO/StreamWriter/AutoFlush/example23.cs" id="Snippet23"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.StreamWriter/VB/example23.vb" id="Snippet23"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.StreamWriter/VB/example23.vb" id="Snippet23"::: + ]]> @@ -189,15 +189,15 @@ Initializes a new instance of the class. - property. When the property is `null`, the culture of the current thread is used for formatting. - - Use this constructor for derived classes. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - + property. When the property is `null`, the culture of the current thread is used for formatting. + + Use this constructor for derived classes. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + ]]> @@ -262,13 +262,13 @@ An object that controls formatting. Initializes a new instance of the class with the specified format provider. - property. The value of the property specifies the culture-specific formatting that is used when you call the and methods. If you do not want to provide a format provider, you create an instance by using the constructor, which sets the property to `null`. When the property is `null`, the culture of the current thread is used for formatting. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - + property. The value of the property specifies the culture-specific formatting that is used when you call the and methods. If you do not want to provide a format provider, you create an instance by using the constructor, which sets the property to `null`. When the property is `null`, the culture of the current thread is used for formatting. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + ]]> @@ -323,16 +323,16 @@ Closes the current writer and releases any system resources associated with the writer. - method and passes it a `true` value. - - Flushing the stream will not flush its underlying encoder unless you explicitly call or `Close`. Setting the property 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 be encoded only after the encoder receives the adjacent character or characters. - + method and passes it a `true` value. + + Flushing the stream will not flush its underlying encoder unless you explicitly call or `Close`. Setting the property 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 be encoded only after the encoder receives the adjacent character or characters. + > [!NOTE] -> In derived classes, do not override the method. Instead, override the method to add code for releasing resources. - +> In derived classes, do not override the method. Instead, override the method to add code for releasing resources. + ]]> File and Stream I/O @@ -386,11 +386,11 @@ Stores the newline characters used for this . - @@ -504,15 +504,15 @@ Releases all resources used by the object. - 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 method. - + 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 method. + ]]> @@ -568,19 +568,19 @@ to release both managed and unmanaged resources; to release only unmanaged resources. Releases the unmanaged resources used by the and optionally releases the managed resources. - . By default, this method specifies the `disposing` parameter as `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. - + . By default, this method specifies the `disposing` parameter as `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. + ]]> - can be called multiple times by other objects. When overriding this method, be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement this method, see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). - + can be called multiple times by other objects. When overriding this method, be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement this method, see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). + For more information about and , see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). File and Stream I/O @@ -679,13 +679,13 @@ When overridden in a derived class, returns the character encoding in which the output is written. The character encoding in which the output is written. - @@ -742,13 +742,13 @@ Clears all buffers for the current writer and causes any buffered data to be written to the underlying device. - . 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. - + . 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. + ]]> @@ -904,15 +904,15 @@ Gets an object that controls formatting. An object for a specific culture, or the formatting of the current culture if no other culture is specified. - property specifies the culture-specific formatting that is used when you call the and methods. If you do not want to provide a format provider, you create an instance by using the constructor, which sets the property to `null`. When the property contains `null`, the culture of the current thread is used for formatting. - - For an example of creating a file and writing text to a file, see [How to: Write Text to a File](/dotnet/standard/io/how-to-write-text-to-a-file). For an example of reading text from a file, see [How to: Read Text from a File](/dotnet/standard/io/how-to-read-text-from-a-file). For an example of reading from and writing to a binary file, see [How to: Read and Write to a Newly Created Data File](/dotnet/standard/io/how-to-read-and-write-to-a-newly-created-data-file). - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - + property specifies the culture-specific formatting that is used when you call the and methods. If you do not want to provide a format provider, you create an instance by using the constructor, which sets the property to `null`. When the property contains `null`, the culture of the current thread is used for formatting. + + For an example of creating a file and writing text to a file, see [How to: Write Text to a File](/dotnet/standard/io/how-to-write-text-to-a-file). For an example of reading text from a file, see [How to: Read Text from a File](/dotnet/standard/io/how-to-read-text-from-a-file). For an example of reading from and writing to a binary file, see [How to: Read and Write to a Newly Created Data File](/dotnet/standard/io/how-to-read-and-write-to-a-newly-created-data-file). + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + ]]> @@ -975,16 +975,16 @@ Gets or sets the line terminator string used by the current . The line terminator string for the current . - , only "\n" or "\r\n" should be used as terminator strings. If `NewLine` is set to `null`, the default newline character is used instead. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - + , only "\n" or "\r\n" should be used as terminator strings. If `NewLine` is set to `null`, the default newline character is used instead. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + ]]> @@ -1040,15 +1040,15 @@ For non-Unix platforms, the default line terminator string is a carriage return Provides a with no backing store that can be written to, but not read from. - methods are invoked on `Null`, the call simply returns, and no data is actually written to any backing store. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - + methods are invoked on `Null`, the call simply returns, and no data is actually written to any backing store. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + ]]> @@ -1105,20 +1105,20 @@ For non-Unix platforms, the default line terminator string is a carriage return System.IO.TextWriter - + The to synchronize. Creates a thread-safe wrapper around the specified . A thread-safe wrapper. - instance that is returned. For more information about synchronization and threading, see [Synchronizing Data for Multithreading](/dotnet/standard/threading/synchronizing-data-for-multithreading). - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - + instance that is returned. For more information about synchronization and threading, see [Synchronizing Data for Multithreading](/dotnet/standard/threading/synchronizing-data-for-multithreading). + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + ]]> @@ -1164,7 +1164,7 @@ For non-Unix platforms, the default line terminator string is a carriage return instance is cast to an interface. ]]> @@ -1232,15 +1232,15 @@ This member is an explicit interface member implementation. It can be used only The value to write. Writes the text representation of a value to the text stream. - method. - - This method outputs either or . - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - + method. + + This method outputs either or . + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + ]]> The is closed. @@ -1306,13 +1306,13 @@ This member is an explicit interface member implementation. It can be used only The character to write to the text stream. Writes a character to the text stream. - The is closed. @@ -1381,15 +1381,15 @@ This member is an explicit interface member implementation. It can be used only The character array to write to the text stream. Writes a character array to the text stream. - . - - This default method calls the method and passes the entire character array. If the character array is `null`, nothing is written. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - + . + + This default method calls the method and passes the entire character array. If the character array is `null`, nothing is written. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + ]]> The is closed. @@ -1450,11 +1450,11 @@ This member is an explicit interface member implementation. It can be used only The decimal value to write. Writes the text representation of a decimal value to the text stream. - property, if not `null`, specifies the culture-specific formatting. - + property, if not `null`, specifies the culture-specific formatting. + ]]> The is closed. @@ -1517,13 +1517,13 @@ This member is an explicit interface member implementation. It can be used only The 8-byte floating-point value to write. Writes the text representation of an 8-byte floating-point value to the text stream. - method. The property, if not `null`, specifies the culture-specific formatting. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - + method. The property, if not `null`, specifies the culture-specific formatting. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + ]]> The is closed. @@ -1586,13 +1586,13 @@ This member is an explicit interface member implementation. It can be used only The 4-byte signed integer to write. Writes the text representation of a 4-byte signed integer to the text stream. - method. The property, if not `null`, specifies the culture-specific formatting. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - + method. The property, if not `null`, specifies the culture-specific formatting. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + ]]> The is closed. @@ -1655,15 +1655,15 @@ This member is an explicit interface member implementation. It can be used only The 8-byte signed integer to write. Writes the text representation of an 8-byte signed integer to the text stream. - method. The property, if not `null`, specifies the culture-specific formatting. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - [How to: Write Text to a File](/dotnet/standard/io/how-to-write-text-to-a-file) - + method. The property, if not `null`, specifies the culture-specific formatting. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + [How to: Write Text to a File](/dotnet/standard/io/how-to-write-text-to-a-file) + ]]> The is closed. @@ -1730,15 +1730,15 @@ This member is an explicit interface member implementation. It can be used only The object to write. Writes the text representation of an object to the text stream by calling the method on that object. - overload. - - If the specified object is `null`, no action is taken and no exception is thrown. Otherwise, the object's `ToString` method is called to produce the string representation, and the resulting string is then written to the output stream. The property, if not `null`, specifies the culture-specific formatting. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - + overload. + + If the specified object is `null`, no action is taken and no exception is thrown. Otherwise, the object's `ToString` method is called to produce the string representation, and the resulting string is then written to the output stream. The property, if not `null`, specifies the culture-specific formatting. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + ]]> The is closed. @@ -1860,13 +1860,13 @@ For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/commo The 4-byte floating-point value to write. Writes the text representation of a 4-byte floating-point value to the text stream. - method. The property, if not `null`, specifies the culture-specific formatting. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - + method. The property, if not `null`, specifies the culture-specific formatting. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + ]]> The is closed. @@ -1936,17 +1936,17 @@ For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/commo The string to write. Writes a string to the text stream. - overload. - - This method does not search the specified string for individual newline characters (hexadecimal 0x000a) and replace them with . - - If `value` is `null`, nothing is written to the text stream. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - + overload. + + This method does not search the specified string for individual newline characters (hexadecimal 0x000a) and replace them with . + + If `value` is `null`, nothing is written to the text stream. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + ]]> The is closed. @@ -2070,13 +2070,13 @@ This method is equivalent to `Write(stringBuilder.ToString())`, but it uses the The 4-byte unsigned integer to write. Writes the text representation of a 4-byte unsigned integer to the text stream. - method. The property, if not `null`, specifies the culture-specific formatting. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - + method. The property, if not `null`, specifies the culture-specific formatting. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + ]]> The is closed. @@ -2145,13 +2145,13 @@ This method is equivalent to `Write(stringBuilder.ToString())`, but it uses the The 8-byte unsigned integer to write. Writes the text representation of an 8-byte unsigned integer to the text stream. - method. The property, if not `null`, specifies the culture-specific formatting. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - + method. The property, if not `null`, specifies the culture-specific formatting. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + ]]> The is closed. @@ -2230,43 +2230,43 @@ This method is equivalent to `Write(stringBuilder.ToString())`, but it uses the The object to format and write. Writes a formatted string to the text stream, using the same semantics as the method. - . Because this overload has only a single object in its parameter list, the value of *index* must always be 0. If there is no parameter in the *index* position, a is thrown.| -|,*length*|The minimum number of characters in the string representation of the parameter. If positive, the parameter is right-aligned; if negative, it is left-aligned.| -|:*formatString*|A standard or custom format string that is supported by the object to be formatted. Possible values for *formatString* are the same as the values supported by the object's `ToString(string format)` method. If *formatString* is not specified and the object to be formatted implements the interface, `null` is passed as the value of the `format` parameter that is used as the format string.| - - The leading and trailing brace characters, "{" and "}", are required. To specify a single literal brace character in `format`, specify two leading or trailing brace characters; that is, "{{" or "}}". - - This method does not search the specified string for individual newline characters (hexadecimal 0x000a) and replace them with . - - If a specified object is not referenced in the format string, it is ignored. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - + . Because this overload has only a single object in its parameter list, the value of *index* must always be 0. If there is no parameter in the *index* position, a is thrown.| +|,*length*|The minimum number of characters in the string representation of the parameter. If positive, the parameter is right-aligned; if negative, it is left-aligned.| +|:*formatString*|A standard or custom format string that is supported by the object to be formatted. Possible values for *formatString* are the same as the values supported by the object's `ToString(string format)` method. If *formatString* is not specified and the object to be formatted implements the interface, `null` is passed as the value of the `format` parameter that is used as the format string.| + + The leading and trailing brace characters, "{" and "}", are required. To specify a single literal brace character in `format`, specify two leading or trailing brace characters; that is, "{{" or "}}". + + This method does not search the specified string for individual newline characters (hexadecimal 0x000a) and replace them with . + + If a specified object is not referenced in the format string, it is ignored. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + ]]> @@ -2274,10 +2274,10 @@ This method is equivalent to `Write(stringBuilder.ToString())`, but it uses the The is closed. An I/O error occurs. - is not a valid composite format string. - - -or- - + is not a valid composite format string. + + -or- + The index of a format item is less than 0 (zero), or greater than or equal to the number of objects to be formatted (which, for this method overload, is one). @@ -2358,43 +2358,43 @@ This method is equivalent to `Write(stringBuilder.ToString())`, but it uses the An object array that contains zero or more objects to format and write. Writes a formatted string to the text stream, using the same semantics as the method. - . Because this overload has an array in its parameter list, the value of *index* must always be less than the length of the array. If there is no parameter in the *index* position, a is thrown.| -|,*length*|The minimum number of characters in the string representation of the parameter. If positive, the parameter is right-aligned; if negative, it is left-aligned.| -|:*formatString*|A standard or custom format string that is supported by the object to be formatted. Possible values for *formatString* are the same as the values supported by the object's `ToString(string format)` method. If *formatString* is not specified and the object to be formatted implements the interface, `null` is passed as the value of the `format` parameter that is used as the format string.| - - The leading and trailing brace characters, "{" and "}", are required. To specify a single literal brace character in `format`, specify two leading or trailing brace characters; that is, "{{" or "}}". - - This method does not search the specified string for individual newline characters (hexadecimal 0x000a) and replace them with . - - If a specified object is not referenced in the format string, it is ignored. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - + . Because this overload has an array in its parameter list, the value of *index* must always be less than the length of the array. If there is no parameter in the *index* position, a is thrown.| +|,*length*|The minimum number of characters in the string representation of the parameter. If positive, the parameter is right-aligned; if negative, it is left-aligned.| +|:*formatString*|A standard or custom format string that is supported by the object to be formatted. Possible values for *formatString* are the same as the values supported by the object's `ToString(string format)` method. If *formatString* is not specified and the object to be formatted implements the interface, `null` is passed as the value of the `format` parameter that is used as the format string.| + + The leading and trailing brace characters, "{" and "}", are required. To specify a single literal brace character in `format`, specify two leading or trailing brace characters; that is, "{{" or "}}". + + This method does not search the specified string for individual newline characters (hexadecimal 0x000a) and replace them with . + + If a specified object is not referenced in the format string, it is ignored. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + ]]> @@ -2402,10 +2402,10 @@ This method is equivalent to `Write(stringBuilder.ToString())`, but it uses the The is closed. An I/O error occurs. - is not a valid composite format string. - - -or- - + is not a valid composite format string. + + -or- + The index of a format item is less than 0 (zero), or greater than or equal to the length of the array. @@ -2469,15 +2469,15 @@ This method is equivalent to `Write(stringBuilder.ToString())`, but it uses the The number of characters to write. Writes a subarray of characters to the text stream. - overload for each character in `buffer` between `index` and (`index` + `count`). - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - + overload for each character in `buffer` between `index` and (`index` + `count`). + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + ]]> The buffer length minus is less than . @@ -2564,43 +2564,43 @@ This method is equivalent to `Write(stringBuilder.ToString())`, but it uses the The second object to format and write. Writes a formatted string to the text stream using the same semantics as the method. - . Because this overload has two objects in its parameter list, the value of *index* must always be 0 or 1. If there is no parameter in the *index* position, a is thrown.| -|,*length*|The minimum number of characters in the string representation of the parameter. If positive, the parameter is right-aligned; if negative, it is left-aligned.| -|:*formatString*|A standard or custom format string that is supported by the object to be formatted. Possible values for *formatString* are the same as the values supported by the object's `ToString(string format)` method. If *formatString* is not specified and the object to be formatted implements the interface, `null` is passed as the value of the `format` parameter that is used as the format string.| - - The leading and trailing brace characters, "{" and "}", are required. To specify a single literal brace character in `format`, specify two leading or trailing brace characters; that is, "{{" or "}}". - - This method does not search the specified string for individual newline characters (hexadecimal 0x000a) and replace them with . - - If a specified object is not referenced in the format string, it is ignored. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - + . Because this overload has two objects in its parameter list, the value of *index* must always be 0 or 1. If there is no parameter in the *index* position, a is thrown.| +|,*length*|The minimum number of characters in the string representation of the parameter. If positive, the parameter is right-aligned; if negative, it is left-aligned.| +|:*formatString*|A standard or custom format string that is supported by the object to be formatted. Possible values for *formatString* are the same as the values supported by the object's `ToString(string format)` method. If *formatString* is not specified and the object to be formatted implements the interface, `null` is passed as the value of the `format` parameter that is used as the format string.| + + The leading and trailing brace characters, "{" and "}", are required. To specify a single literal brace character in `format`, specify two leading or trailing brace characters; that is, "{{" or "}}". + + This method does not search the specified string for individual newline characters (hexadecimal 0x000a) and replace them with . + + If a specified object is not referenced in the format string, it is ignored. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + ]]> @@ -2608,10 +2608,10 @@ This method is equivalent to `Write(stringBuilder.ToString())`, but it uses the The is closed. An I/O error occurs. - is not a valid composite format string. - - -or- - + is not a valid composite format string. + + -or- + The index of a format item is less than 0 (zero) or greater than or equal to the number of objects to be formatted (which, for this method overload, is two). @@ -2694,43 +2694,43 @@ This method is equivalent to `Write(stringBuilder.ToString())`, but it uses the The third object to format and write. Writes a formatted string to the text stream, using the same semantics as the method. - . Because this overload has three objects in its parameter list, the value of *index* must always be 0, 1, or 2. If there is no parameter in the *index* position, a is thrown.| -|,*length*|The minimum number of characters in the string representation of the parameter. If positive, the parameter is right-aligned; if negative, it is left-aligned.| -|:*formatString*|A standard or custom format string that is supported by the object to be formatted. Possible values for *formatString* are the same as the values supported by the object's `ToString(string format)` method. If *formatString* is not specified and the object to be formatted implements the interface, `null` is passed as the value of the `format` parameter that is used as the format string.| - - The leading and trailing brace characters, "{" and "}", are required. To specify a single literal brace character in `format`, specify two leading or trailing brace characters; that is, "{{" or "}}". - - This method does not search the specified string for individual newline characters (hexadecimal 0x000a) and replace them with . - - If a specified object is not referenced in the format string, it is ignored. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - + . Because this overload has three objects in its parameter list, the value of *index* must always be 0, 1, or 2. If there is no parameter in the *index* position, a is thrown.| +|,*length*|The minimum number of characters in the string representation of the parameter. If positive, the parameter is right-aligned; if negative, it is left-aligned.| +|:*formatString*|A standard or custom format string that is supported by the object to be formatted. Possible values for *formatString* are the same as the values supported by the object's `ToString(string format)` method. If *formatString* is not specified and the object to be formatted implements the interface, `null` is passed as the value of the `format` parameter that is used as the format string.| + + The leading and trailing brace characters, "{" and "}", are required. To specify a single literal brace character in `format`, specify two leading or trailing brace characters; that is, "{{" or "}}". + + This method does not search the specified string for individual newline characters (hexadecimal 0x000a) and replace them with . + + If a specified object is not referenced in the format string, it is ignored. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + ]]> @@ -2738,10 +2738,10 @@ This method is equivalent to `Write(stringBuilder.ToString())`, but it uses the The is closed. An I/O error occurs. - is not a valid composite format string. - - -or- - + is not a valid composite format string. + + -or- + The index of a format item is less than 0 (zero), or greater than or equal to the number of objects to be formatted (which, for this method overload, is three). @@ -2817,11 +2817,11 @@ This method is equivalent to `Write(stringBuilder.ToString())`, but it uses the Writes a character to the text stream asynchronously. A task that represents the asynchronous write operation. - class is an abstract class. Therefore, you do not instantiate it in your code. For an example of using the method, see the method. - + class is an abstract class. Therefore, you do not instantiate it in your code. For an example of using the method, see the method. + 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 . ]]> @@ -2964,11 +2964,11 @@ This method is equivalent to `Write(stringBuilder.ToString())`, but it uses the Writes a string to the text stream asynchronously. A task that represents the asynchronous write operation. - class is an abstract class. Therefore, you do not instantiate it in your code. For an example of using the method, see the method. - + class is an abstract class. Therefore, you do not instantiate it in your code. For an example of using the method, see the method. + 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 . ]]> @@ -3082,7 +3082,7 @@ This method is equivalent to `Write(stringBuilder.ToString())`, but it uses the method to avoid creating the intermediate string. @@ -3152,11 +3152,11 @@ This method stores in the task it returns all non-usage exceptions that the meth Writes a subarray of characters to the text stream asynchronously. A task that represents the asynchronous write operation. - class is an abstract class. Therefore, you do not instantiate it in your code. For an example of using the method, see the method. - + class is an abstract class. Therefore, you do not instantiate it in your code. For an example of using the method, see the method. + 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 . ]]> @@ -3299,17 +3299,17 @@ For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/commo The value to write. Writes the text representation of a value to the text stream, followed by a line terminator. - method. - - This method outputs either or . - - The line terminator is defined by the field. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - + method. + + This method outputs either or . + + The line terminator is defined by the field. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + ]]> The is closed. @@ -3371,15 +3371,15 @@ For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/commo The character to write to the text stream. Writes a character to the text stream, followed by a line terminator. - followed by . - - The line terminator is defined by the field. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - + followed by . + + The line terminator is defined by the field. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + ]]> The is closed. @@ -3448,17 +3448,17 @@ For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/commo The character array from which data is read. Writes an array of characters to the text stream, followed by a line terminator. - followed by . - - The line terminator is defined by the field. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - + followed by . + + The line terminator is defined by the field. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + ]]> The is closed. @@ -3520,13 +3520,13 @@ For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/commo The decimal value to write. Writes the text representation of a decimal value to the text stream, followed by a line terminator. - property, if not `null`, specifies the culture-specific formatting. For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - The line terminator is defined by the field. - + property, if not `null`, specifies the culture-specific formatting. For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + The line terminator is defined by the field. + ]]> The is closed. @@ -3589,13 +3589,13 @@ For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/commo The 8-byte floating-point value to write. Writes the text representation of a 8-byte floating-point value to the text stream, followed by a line terminator. - property, if not `null`, specifies the culture-specific formatting. For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - - The line terminator is defined by the field. - + property, if not `null`, specifies the culture-specific formatting. For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + + The line terminator is defined by the field. + ]]> The is closed. @@ -3658,15 +3658,15 @@ For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/commo The 4-byte signed integer to write. Writes the text representation of a 4-byte signed integer to the text stream, followed by a line terminator. - method. The property, if not `null`, specifies the culture-specific formatting. - - The line terminator is defined by the field. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - + method. The property, if not `null`, specifies the culture-specific formatting. + + The line terminator is defined by the field. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + ]]> The is closed. @@ -3729,15 +3729,15 @@ For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/commo The 8-byte signed integer to write. Writes the text representation of an 8-byte signed integer to the text stream, followed by a line terminator. - method. The property, if not `null`, specifies the culture-specific formatting. - - The line terminator is defined by the field. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - + method. The property, if not `null`, specifies the culture-specific formatting. + + The line terminator is defined by the field. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + ]]> The is closed. @@ -3807,7 +3807,7 @@ For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/commo The object to write. If is , only the line terminator is written. Writes the text representation of an object to the text stream, by calling the method on that object, followed by a line terminator. - The char span value to write to the text stream. Writes the text representation of a character span to the text stream, followed by a line terminator. - The string, as a string builder, to write to the text stream. Writes the text representation of a string builder to the text stream, followed by a line terminator. - The 4-byte unsigned integer to write. Writes the text representation of a 4-byte unsigned integer to the text stream, followed by a line terminator. - method. The property, if not `null`, specifies the culture-specific formatting. - - The line terminator is defined by the field. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - + method. The property, if not `null`, specifies the culture-specific formatting. + + The line terminator is defined by the field. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + ]]> The is closed. @@ -4237,15 +4237,15 @@ For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/commo The 8-byte unsigned integer to write. Writes the text representation of an 8-byte unsigned integer to the text stream, followed by a line terminator. - method. The property, if not `null`, specifies the culture-specific formatting. - - The line terminator is defined by the field. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - + method. The property, if not `null`, specifies the culture-specific formatting. + + The line terminator is defined by the field. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + ]]> The is closed. @@ -4324,45 +4324,45 @@ For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/commo The object to format and write. Writes a formatted string and a new line to the text stream, using the same semantics as the method. - . Because this overload has only a single object in its parameter list, the value of *index* must always be 0. If there is no parameter in the *index* position, a is thrown.| -|,*length*|The minimum number of characters in the string representation of the parameter. If positive, the parameter is right-aligned; if negative, it is left-aligned.| -|:*formatString*|A standard or custom format string that is supported by the object to be formatted. Possible values for *formatString* are the same as the values supported by the object's `ToString(string format)` method. If *formatString* is not specified and the object to be formatted implements the interface, `null` is passed as the value of the `format` parameter that is used as the format string.| - - The leading and trailing brace characters, "{" and "}", are required. To specify a single literal brace character in `format`, specify two leading or trailing brace characters; that is, "{{" or "}}". - - This method does not search the specified string for individual newline characters (hexadecimal 0x000a) and replace them with . - - If a specified object is not referenced in the format string, it is ignored. - - The line terminator is defined by the field. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - + . Because this overload has only a single object in its parameter list, the value of *index* must always be 0. If there is no parameter in the *index* position, a is thrown.| +|,*length*|The minimum number of characters in the string representation of the parameter. If positive, the parameter is right-aligned; if negative, it is left-aligned.| +|:*formatString*|A standard or custom format string that is supported by the object to be formatted. Possible values for *formatString* are the same as the values supported by the object's `ToString(string format)` method. If *formatString* is not specified and the object to be formatted implements the interface, `null` is passed as the value of the `format` parameter that is used as the format string.| + + The leading and trailing brace characters, "{" and "}", are required. To specify a single literal brace character in `format`, specify two leading or trailing brace characters; that is, "{{" or "}}". + + This method does not search the specified string for individual newline characters (hexadecimal 0x000a) and replace them with . + + If a specified object is not referenced in the format string, it is ignored. + + The line terminator is defined by the field. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + ]]> @@ -4370,10 +4370,10 @@ For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/commo The is closed. An I/O error occurs. - is not a valid composite format string. - - -or- - + is not a valid composite format string. + + -or- + The index of a format item is less than 0 (zero), or greater than or equal to the number of objects to be formatted (which, for this method overload, is one). @@ -4454,55 +4454,55 @@ For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/commo An object array that contains zero or more objects to format and write. Writes out a formatted string and a new line to the text stream, using the same semantics as . - . Because this overload has an array in its parameter list, the value of *index* must always be less than the length of the array. If there is no parameter in the *index* position, a is thrown.| -|,*length*|The minimum number of characters in the string representation of the parameter. If positive, the parameter is right-aligned; if negative, it is left-aligned.| -|:*formatString*|A standard or custom format string that is supported by the object to be formatted. Possible values for *formatString* are the same as the values supported by the object's `ToString(string format)` method. If *formatString* is not specified and the object to be formatted implements the interface, `null` is passed as the value of the `format` parameter that is used as the format string.| - - The leading and trailing brace characters, "{" and "}", are required. To specify a single literal brace character in `format`, specify two leading or trailing brace characters; that is, "{{" or "}}". - - This method does not search the specified string for individual newline characters (hexadecimal 0x000a) and replace them with . - - If a specified object is not referenced in the format string, it is ignored. - - The line terminator is defined by the field. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - + . Because this overload has an array in its parameter list, the value of *index* must always be less than the length of the array. If there is no parameter in the *index* position, a is thrown.| +|,*length*|The minimum number of characters in the string representation of the parameter. If positive, the parameter is right-aligned; if negative, it is left-aligned.| +|:*formatString*|A standard or custom format string that is supported by the object to be formatted. Possible values for *formatString* are the same as the values supported by the object's `ToString(string format)` method. If *formatString* is not specified and the object to be formatted implements the interface, `null` is passed as the value of the `format` parameter that is used as the format string.| + + The leading and trailing brace characters, "{" and "}", are required. To specify a single literal brace character in `format`, specify two leading or trailing brace characters; that is, "{{" or "}}". + + This method does not search the specified string for individual newline characters (hexadecimal 0x000a) and replace them with . + + If a specified object is not referenced in the format string, it is ignored. + + The line terminator is defined by the field. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + ]]> A string or object is passed in as . The is closed. An I/O error occurs. - is not a valid composite format string. - - -or- - + is not a valid composite format string. + + -or- + The index of a format item is less than 0 (zero), or greater than or equal to the length of the array. @@ -4566,17 +4566,17 @@ For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/commo The maximum number of characters to write. Writes a subarray of characters to the text stream, followed by a line terminator. - method followed by for each character in `buffer` between `index` and (`index` + `count`). - - The line terminator is defined by the field. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - + method followed by for each character in `buffer` between `index` and (`index` + `count`). + + The line terminator is defined by the field. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + ]]> The buffer length minus is less than . @@ -4663,45 +4663,45 @@ For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/commo The second object to format and write. Writes a formatted string and a new line to the text stream, using the same semantics as the method. - . Because this overload has two objects in its parameter list, the value of *index* must always be 0 or 1. If there is no parameter in the *index* position, a is thrown.| -|,*length*|The minimum number of characters in the string representation of the parameter. If positive, the parameter is right-aligned; if negative, it is left-aligned.| -|:*formatString*|A standard or custom format string that is supported by the object to be formatted. Possible values for *formatString* are the same as the values supported by the object's `ToString(string format)` method. If *formatString* is not specified and the object to be formatted implements the interface, `null` is passed as the value of the `format` parameter that is used as the format string.| - - The leading and trailing brace characters, "{" and "}", are required. To specify a single literal brace character in `format`, specify two leading or trailing brace characters; that is, "{{" or "}}". - - This method does not search the specified string for individual newline characters (hexadecimal 0x000a) and replace them with . - - If a specified object is not referenced in the format string, it is ignored. - - The line terminator is defined by the field. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - + . Because this overload has two objects in its parameter list, the value of *index* must always be 0 or 1. If there is no parameter in the *index* position, a is thrown.| +|,*length*|The minimum number of characters in the string representation of the parameter. If positive, the parameter is right-aligned; if negative, it is left-aligned.| +|:*formatString*|A standard or custom format string that is supported by the object to be formatted. Possible values for *formatString* are the same as the values supported by the object's `ToString(string format)` method. If *formatString* is not specified and the object to be formatted implements the interface, `null` is passed as the value of the `format` parameter that is used as the format string.| + + The leading and trailing brace characters, "{" and "}", are required. To specify a single literal brace character in `format`, specify two leading or trailing brace characters; that is, "{{" or "}}". + + This method does not search the specified string for individual newline characters (hexadecimal 0x000a) and replace them with . + + If a specified object is not referenced in the format string, it is ignored. + + The line terminator is defined by the field. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + ]]> @@ -4709,10 +4709,10 @@ For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/commo The is closed. An I/O error occurs. - is not a valid composite format string. - - -or- - + is not a valid composite format string. + + -or- + The index of a format item is less than 0 (zero), or greater than or equal to the number of objects to be formatted (which, for this method overload, is two). @@ -4795,45 +4795,45 @@ For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/commo The third object to format and write. Writes out a formatted string and a new line to the text stream, using the same semantics as . - . Because this overload has three objects in its parameter list, the value of *index* must always be 0, 1, or 2. If there is no parameter in the *index* position, a is thrown.| -|,*length*|The minimum number of characters in the string representation of the parameter. If positive, the parameter is right-aligned; if negative, it is left-aligned.| -|:*formatString*|A standard or custom format string that is supported by the object to be formatted. Possible values for *formatString* are the same as the values supported by the object's `ToString(string format)` method. If *formatString* is not specified and the object to be formatted implements the interface, `null` is passed as the value of the `format` parameter that is used as the format string.| - - The leading and trailing brace characters, "{" and "}", are required. To specify a single literal brace character in `format`, specify two leading or trailing brace characters; that is, "{{" or "}}". - - This method does not search the specified string for individual newline characters (hexadecimal 0x000a) and replace them with . - - If a specified object is not referenced in the format string, it is ignored. - - The line terminator is defined by the field. - - For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). - + . Because this overload has three objects in its parameter list, the value of *index* must always be 0, 1, or 2. If there is no parameter in the *index* position, a is thrown.| +|,*length*|The minimum number of characters in the string representation of the parameter. If positive, the parameter is right-aligned; if negative, it is left-aligned.| +|:*formatString*|A standard or custom format string that is supported by the object to be formatted. Possible values for *formatString* are the same as the values supported by the object's `ToString(string format)` method. If *formatString* is not specified and the object to be formatted implements the interface, `null` is passed as the value of the `format` parameter that is used as the format string.| + + The leading and trailing brace characters, "{" and "}", are required. To specify a single literal brace character in `format`, specify two leading or trailing brace characters; that is, "{{" or "}}". + + This method does not search the specified string for individual newline characters (hexadecimal 0x000a) and replace them with . + + If a specified object is not referenced in the format string, it is ignored. + + The line terminator is defined by the field. + + For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + ]]> @@ -4841,10 +4841,10 @@ For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/commo The is closed. An I/O error occurs. - is not a valid composite format string. - - -or- - + is not a valid composite format string. + + -or- + The index of a format item is less than 0 (zero), or greater than or equal to the number of objects to be formatted (which, for this method overload, is three). @@ -4996,13 +4996,13 @@ This method stores in the task it returns all non-usage exceptions that the meth Asynchronously writes a character to the text stream, followed by a line terminator. A task that represents the asynchronous write operation. - field. - - The class is an abstract class. Therefore, you do not instantiate it in your code. For an example of using the method, see the method. - + field. + + The class is an abstract class. Therefore, you do not instantiate it in your code. For an example of using the method, see the method. + 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 . ]]> @@ -5076,11 +5076,11 @@ This method stores in the task it returns all non-usage exceptions that the meth Asynchronously writes an array of characters to the text stream, followed by a line terminator. A task that represents the asynchronous write operation. - field. - + field. + 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 . ]]> @@ -5154,13 +5154,13 @@ This method stores in the task it returns all non-usage exceptions that the meth Asynchronously writes a string to the text stream, followed by a line terminator. A task that represents the asynchronous write operation. - field. - - The class is an abstract class. Therefore, you do not instantiate it in your code. For an example of using the method, see the method. - + field. + + The class is an abstract class. Therefore, you do not instantiate it in your code. For an example of using the method, see the method. + 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 . ]]> @@ -5220,12 +5220,12 @@ This method stores in the task it returns all non-usage exceptions that the meth Asynchronously writes the text representation of a character memory region to the text stream, followed by a line terminator. A task that represents the asynchronous write operation. - field. - + ]]> The cancellation token was canceled. This exception is stored into the returned task. @@ -5285,7 +5285,7 @@ The line terminator is defined by the fi ## Remarks The line terminator is defined by the field. - + 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.IO/UnmanagedMemoryAccessor.xml b/xml/System.IO/UnmanagedMemoryAccessor.xml index 9d53a91c8f0..3952583d88c 100644 --- a/xml/System.IO/UnmanagedMemoryAccessor.xml +++ b/xml/System.IO/UnmanagedMemoryAccessor.xml @@ -57,13 +57,13 @@ Provides random access to unmanaged blocks of memory from managed code. - method of a object returns the unmanaged blocks of memory for working with views of memory-mapped files. - + method of a object returns the unmanaged blocks of memory for working with views of memory-mapped files. + [!INCLUDE[note_unnecessary_dispose](~/includes/note-unnecessary-dispose.md)] - + ]]> @@ -243,10 +243,10 @@ is . - or is less than zero. - - -or- - + or is less than zero. + + -or- + is not a valid enumeration value. plus would wrap around the high end of the address space. @@ -483,19 +483,19 @@ to release both managed and unmanaged resources; to release only unmanaged resources. Releases the unmanaged resources used by the and optionally releases the managed resources. - method, if it has been overridden. `Dispose()` invokes this method with the `disposing` parameter set to `true`. `Finalize` invokes this method with `disposing` set to `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. - + + 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. + ]]> - can be called multiple times by other objects. When overriding be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). - + can be called multiple times by other objects. When overriding be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). + For more information about and , see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). @@ -560,11 +560,11 @@ The type of access allowed to the memory. The default is . Sets the initial values for the accessor. - @@ -572,10 +572,10 @@ is . - or is less than zero. - - -or- - + or is less than zero. + + -or- + is not a valid enumeration value. plus would wrap around the high end of the address space. @@ -676,8 +676,8 @@ - - + + The type of structure. @@ -685,17 +685,17 @@ The structure to contain the read data. Reads a structure of type from the accessor into a provided reference. - - There are not enough bytes after to read in a structure of type . - - -or- - + There are not enough bytes after to read in a structure of type . + + -or- + is a value type that contains one or more reference types. is less than zero or greater than the capacity of the accessor. @@ -754,8 +754,8 @@ - - + + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 0 })] @@ -763,8 +763,8 @@ - - + + The type of structure. @@ -775,11 +775,11 @@ Reads structures of type from the accessor into an array of type . The number of structures read into . This value can be less than if there are fewer structures available, or zero if the end of the accessor is reached. - @@ -1006,10 +1006,10 @@ Reads a decimal value from the accessor. The value that was read. To be added. - There are not enough bytes after to read a value. - - -or- - + There are not enough bytes after to read a value. + + -or- + The decimal to read is invalid. is less than zero or greater than the capacity of the accessor. @@ -1785,10 +1785,10 @@ The value to write. Writes a decimal value into the accessor. To be added. - There are not enough bytes after to write a value. - - -or- - + There are not enough bytes after to write a value. + + -or- + The decimal is invalid. is less than zero or greater than the capacity of the accessor. @@ -2398,8 +2398,8 @@ - - + + The type of structure. @@ -2407,11 +2407,11 @@ The structure to write. Writes a structure into the accessor. - methods in this class. - + methods in this class. + ]]> There are not enough bytes in the accessor after to write a structure of type . @@ -2472,8 +2472,8 @@ - - + + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 0 })] @@ -2481,8 +2481,8 @@ - - + + The type of structure. @@ -2494,10 +2494,10 @@ To be added. There are not enough bytes in the accessor after to write the number of structures specified by . - is less than zero or greater than the capacity of the accessor. - - -or- - + is less than zero or greater than the capacity of the accessor. + + -or- + or is less than zero. is . diff --git a/xml/System.IdentityModel.Claims/Claim.xml b/xml/System.IdentityModel.Claims/Claim.xml index 8b72274cc04..10ef8dbc64e 100644 --- a/xml/System.IdentityModel.Claims/Claim.xml +++ b/xml/System.IdentityModel.Claims/Claim.xml @@ -29,21 +29,21 @@ Represents a claim that is associated with an entity. - over the value `Martin` indicates that the entity with the claim possesses a `Name` property with the value `Martin`. - - Although various claim types and rights are defined as part of Identity Model, the system is extensible. The various systems building on top of the Identity Model infrastructure can define claim types and rights as required. - - - -## Examples + over the value `Martin` indicates that the entity with the claim possesses a `Name` property with the value `Martin`. + + Although various claim types and rights are defined as part of Identity Model, the system is extensible. The various systems building on top of the Identity Model infrastructure can define claim types and rights as required. + + + +## Examples :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/c_claim/cs/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/c_claim/vb/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/c_claim/vb/source.vb" id="Snippet1"::: + ]]> @@ -78,24 +78,24 @@ The URI of the right associated with the claim. Initializes a new instance of the class with the specified type, resource, and right. - and classes. - + and classes. + ]]> - is . - - -or- - + is . + + -or- + is . - is zero length. - - -or- - + is zero length. + + -or- + is zero length. @@ -125,19 +125,19 @@ Gets the type of the claim. A URI that represents the type of the claim. - property can be one of the pre-defined claim types that are represented by the static properties of the class. - - Claim types specify the type of claim that is being asserted, such as an email address. - - - -## Examples + property can be one of the pre-defined claim types that are represented by the static properties of the class. + + Claim types specify the type of claim that is being asserted, such as an email address. + + + +## Examples :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/c_claim/cs/source.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/c_claim/vb/source.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/c_claim/vb/source.vb" id="Snippet2"::: + ]]> @@ -160,27 +160,25 @@ - A that represents the deny-only SID. - A that represents the deny-only SID. Creates a object that represents a deny-only specified security identifier (SID). A that represents the SID specified in the parameter. - object this method creates has the property values shown in the following table. - -|Property|Value| -|--------------|-----------| -||| -||The value of the `sid` parameter.| -||.| - + object this method creates has the property values shown in the following table. + +|Property|Value| +|--------------|-----------| +||| +||The value of the `sid` parameter.| +||.| + ]]> @@ -217,17 +215,17 @@ Creates a object that represents the specified Domain Name System (DNS) name. The object this method creates. - object this method creates has the property values shown in the following table. - -|Property|Value| -|--------------|-----------| -||| -||The value of the `dns` parameter.| -||| - + object this method creates has the property values shown in the following table. + +|Property|Value| +|--------------|-----------| +||| +||The value of the `dns` parameter.| +||| + ]]> The parameter is . @@ -263,17 +261,17 @@ Creates a object that represents the specified hash value. The object this method creates. - object this method creates has the property values shown in the following table. - -|Property|Value| -|--------------|-----------| -||| -||The value of the `hash` parameter.| -||.| - + object this method creates has the property values shown in the following table. + +|Property|Value| +|--------------|-----------| +||| +||The value of the `hash` parameter.| +||.| + ]]> The parameter is . @@ -296,24 +294,24 @@ System.IdentityModel.Claims.Claim - + A that specifies the email address this claim represents. This parameter must not be . If this parameter is , this method throws an exception. Creates a object that represents the specified email address. The object this method creates. - object this method creates has the property values shown in the following table. - -|Property|Value| -|--------------|-----------| -||| -||The value of the `mailAddress` parameter.| -||.| - + object this method creates has the property values shown in the following table. + +|Property|Value| +|--------------|-----------| +||| +||The value of the `mailAddress` parameter.| +||.| + ]]> The parameter is . @@ -349,17 +347,17 @@ Creates a object that represents the specified name. The object this method creates. - object this method creates has the property values shown in the following table. - -|Property|Value| -|--------------|-----------| -||| -||The value of the `name` parameter.| -||.| - + object this method creates has the property values shown in the following table. + +|Property|Value| +|--------------|-----------| +||| +||The value of the `name` parameter.| +||.| + ]]> The parameter is . @@ -395,17 +393,17 @@ Creates a object that represents the specified RSA key. The object this method creates. - object this method creates has the property values shown in the following table. - -|Property|Value| -|--------------|-----------| -||| -||The value of the `rsa` parameter.| -||.| - + object this method creates has the property values shown in the following table. + +|Property|Value| +|--------------|-----------| +||| +||The value of the `rsa` parameter.| +||.| + ]]> The parameter is . @@ -441,17 +439,17 @@ Creates a object that represents the specified Service Principal Name (SPN). The object this method creates. - object this method creates has the property values shown in the following table. - -|Property|Value| -|--------------|-----------| -||| -||The value of the `spn` parameter.| -||.| - + object this method creates has the property values shown in the following table. + +|Property|Value| +|--------------|-----------| +||| +||The value of the `spn` parameter.| +||.| + ]]> The parameter is . @@ -487,17 +485,17 @@ Creates a object that represents the specified thumbprint. The object this method creates. - object this method creates has the property values shown in the following table. - -|Property|Value| -|--------------|-----------| -||| -||The value of the `thumbprint` parameter.| -||.| - + object this method creates has the property values shown in the following table. + +|Property|Value| +|--------------|-----------| +||| +||The value of the `thumbprint` parameter.| +||.| + ]]> The parameter is . @@ -533,17 +531,17 @@ Creates a object that represents the specified Universal Principal Name (UPN). The object this method creates. - object this method creates has the property values shown in the following table. - -|Property|Value| -|--------------|-----------| -||| -||The value of the `upn` parameter.| -||.| - + object this method creates has the property values shown in the following table. + +|Property|Value| +|--------------|-----------| +||| +||The value of the `upn` parameter.| +||.| + ]]> The parameter is . @@ -579,17 +577,17 @@ Creates a object that represents the specified Uniform Resource Locator (URL). The object this method creates. - object this method creates has the property values shown in the following table. - -|Property|Value| -|--------------|-----------| -||| -||The value of the `uri` parameter.| -||.| - + object this method creates has the property values shown in the following table. + +|Property|Value| +|--------------|-----------| +||| +||The value of the `uri` parameter.| +||.| + ]]> The parameter is . @@ -625,17 +623,17 @@ Creates a object that represents the specified security identifier (SID). A that represents the SID specified in the parameter. - object this method creates has the property values shown in the following table. - -|Property|Value| -|--------------|-----------| -||| -||The value of the `sid` parameter.| -||.| - + object this method creates has the property values shown in the following table. + +|Property|Value| +|--------------|-----------| +||| +||The value of the `sid` parameter.| +||.| + ]]> @@ -672,20 +670,20 @@ Creates a object that represents the specified X.500 distinguished name. The object this method creates. - object this method creates has the property values shown in the following table. - - - - - - The value of the `x500DistinguishedName` parameter. - - - . - + object this method creates has the property values shown in the following table. + + + + + + The value of the `x500DistinguishedName` parameter. + + + . + ]]> The parameter is . @@ -717,11 +715,11 @@ Gets an object that can compare two objects for equality. A interface implementation that compares two objects. - property to match any of the pre-defined claim types. - + property to match any of the pre-defined claim types. + ]]> @@ -757,20 +755,20 @@ if represents the same claim as the current ; otherwise . - method to provide equality comparisons for objects. The comparison consists of three comparisons on the values of the , , and properties. The comparison algorithm that is used on the property depends upon the value of the property. The following table details the comparison algorithm that is used for the specified claim type. - -|Claim type|Comparison| -|----------------|----------------| -||Case insensitive string comparison on the resource.| -||Byte-by-byte comparison.| -||Byte-by-byte comparison on the Modulus and Exponent parts of the algorithm.| -||Byte-by-byte comparison.| -||SID comparison.| -||Normalized X.500 raw data comparison.| - + method to provide equality comparisons for objects. The comparison consists of three comparisons on the values of the , , and properties. The comparison algorithm that is used on the property depends upon the value of the property. The following table details the comparison algorithm that is used for the specified claim type. + +|Claim type|Comparison| +|----------------|----------------| +||Case insensitive string comparison on the resource.| +||Byte-by-byte comparison.| +||Byte-by-byte comparison on the Modulus and Exponent parts of the algorithm.| +||Byte-by-byte comparison.| +||SID comparison.| +||Normalized X.500 raw data comparison.| + ]]> @@ -802,11 +800,11 @@ Returns a hash code for the current claim. The hash code for the claim. - method. - + method. + ]]> @@ -837,12 +835,12 @@ Gets the resource with which this object is associated. The resource with which this object is associated. - @@ -873,17 +871,17 @@ A string representation of a uniform resource identifier (URI) that specifies the right associated with this object. Pre-defined rights are available as static properties of the class. A URI that specifies the right associated with this object. - and . - - - -## Examples + and . + + + +## Examples :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/c_claim/cs/source.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/c_claim/vb/source.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/c_claim/vb/source.vb" id="Snippet2"::: + ]]> @@ -912,12 +910,12 @@ A pre-defined claim that represents the system entity. - A object that represents the system entity. This object has the property values shown in the following table. - - Property - - Value - + A object that represents the system entity. This object has the property values shown in the following table. + + Property + + Value + To be added. @@ -949,11 +947,11 @@ Returns a string representation of this object. This object. - and properties. - + and properties. + ]]> diff --git a/xml/System.IdentityModel.Policy/IAuthorizationPolicy.xml b/xml/System.IdentityModel.Policy/IAuthorizationPolicy.xml index 8f1caba589d..8cb254ca49d 100644 --- a/xml/System.IdentityModel.Policy/IAuthorizationPolicy.xml +++ b/xml/System.IdentityModel.Policy/IAuthorizationPolicy.xml @@ -38,19 +38,19 @@ Defines a set of rules for authorizing a user, given a set of claims. - interface to add or map one set of claims to another. An authorization policy examines a set of claims and adds additional claims based on the current set. For example, an authorization policy might evaluate a claim that contains the date of birth and add a claim that asserts that the user is over 21 years old and add an Over21 claim to the . - - Classes that implement the interface do not authorize users, but they enable the class to do so. The calls the method for each authorization policy in effect. The method determines whether additional claims should be added for the user, based on the current context. An authorization policy's method may be called multiple times, as claims are added to the by other authorization policies. When all authorization policies in effect are done, the class makes authorization decisions based upon the final set of claims. The class then creates an that contains an immutable set of claims that reflects these authorization decisions. - - - -## Examples + interface to add or map one set of claims to another. An authorization policy examines a set of claims and adds additional claims based on the current set. For example, an authorization policy might evaluate a claim that contains the date of birth and add a claim that asserts that the user is over 21 years old and add an Over21 claim to the . + + Classes that implement the interface do not authorize users, but they enable the class to do so. The calls the method for each authorization policy in effect. The method determines whether additional claims should be added for the user, based on the current context. An authorization policy's method may be called multiple times, as claims are added to the by other authorization policies. When all authorization policies in effect are done, the class makes authorization decisions based upon the final set of claims. The class then creates an that contains an immutable set of claims that reflects these authorization decisions. + + + +## Examples :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/c_iauthorizationpolicy/cs/service.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/c_iauthorizationpolicy/vb/myauthorizationpolicy.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/c_iauthorizationpolicy/vb/myauthorizationpolicy.vb" id="Snippet1"::: + ]]> Authorization Policy Sample @@ -79,8 +79,8 @@ System.Boolean - - + + An that contains the claim set that the authorization policy evaluates. @@ -89,21 +89,21 @@ if the method for this authorization policy must be called if additional claims are added by other authorization policies to ; otherwise, to state no additional evaluation is required by this authorization policy. - [!NOTE] -> Implementers of the interface should expect the method to be called multiple times by different threads. - - Implementers of the interface can use the `state` parameter to track state between calls to the method. If a state object is set inside a given call to the method, the same object instance is passed to each and every subsequent call to the method in the current evaluation process. - - - -## Examples +> Implementers of the interface should expect the method to be called multiple times by different threads. + + Implementers of the interface can use the `state` parameter to track state between calls to the method. If a state object is set inside a given call to the method, the same object instance is passed to each and every subsequent call to the method in the current evaluation process. + + + +## Examples :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/c_iauthorizationpolicy/cs/service.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/c_iauthorizationpolicy/vb/myauthorizationpolicy.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/c_iauthorizationpolicy/vb/myauthorizationpolicy.vb" id="Snippet2"::: + ]]> diff --git a/xml/System.IdentityModel.Selectors/SecurityTokenAuthenticator.xml b/xml/System.IdentityModel.Selectors/SecurityTokenAuthenticator.xml index f65c1f556a2..674131d5ed4 100644 --- a/xml/System.IdentityModel.Selectors/SecurityTokenAuthenticator.xml +++ b/xml/System.IdentityModel.Selectors/SecurityTokenAuthenticator.xml @@ -28,24 +28,24 @@ Authenticates a security token. - class and the classes that derive from it authenticate security tokens. Typically, you would only derive a class directly from when you create a custom security token. If you wanted to override the default authentication or authorization behaviors for built-in security tokens, derive from one of the classes that derive from , such as . - - When you derive a class from , override the following two methods: and . The method determines whether this security token authenticator can authenticate a specific security token. The method authenticates the security token and establishes a set of authorization policies for authorization. The authorization policies map the claims found in the security token to claims required by the application. - + class and the classes that derive from it authenticate security tokens. Typically, you would only derive a class directly from when you create a custom security token. If you wanted to override the default authentication or authorization behaviors for built-in security tokens, derive from one of the classes that derive from , such as . + + When you derive a class from , override the following two methods: and . The method determines whether this security token authenticator can authenticate a specific security token. The method authenticates the security token and establishes a set of authorization policies for authorization. The authorization policies map the claims found in the security token to claims required by the application. + ]]> - - - - - + + + + + Constructor System.IdentityModel @@ -87,7 +87,7 @@ System.Boolean - + The to be validated. @@ -95,11 +95,11 @@ when token can be validated; otherwise, . - method checks whether the token parameter is `null` and then calls the method to determine whether this security token authenticator can authenticate the security token type for `token`. - + method checks whether the token parameter is `null` and then calls the method to determine whether this security token authenticator can authenticate the security token type for `token`. + ]]> @@ -130,7 +130,7 @@ System.Boolean - + The to be validated. @@ -138,11 +138,11 @@ when can be validated; otherwise, . - method is called by the method to determine whether this security token authenticator can authenticate the security token type for `token`. This does not authenticate the security token; that is performed by the method. - + method is called by the method to determine whether this security token authenticator can authenticate the security token type for `token`. This does not authenticate the security token; that is performed by the method. + ]]> @@ -171,27 +171,27 @@ System.Collections.ObjectModel.ReadOnlyCollection<System.IdentityModel.Policy.IAuthorizationPolicy> - + The to be validated. Authenticates the specified security token and returns the set of authorization policies for the security token. A of type that contains the set of authorization policies in effect for this application. - method checks whether the `token` parameter is `null`, calls the method to determine if this security token authenticator can authenticate this security token, and then if it can, calls the method. - + method checks whether the `token` parameter is `null`, calls the method to determine if this security token authenticator can authenticate this security token, and then if it can, calls the method. + ]]> is . - cannot be authenticated by this security token authenticator - - -or- - + cannot be authenticated by this security token authenticator + + -or- + is not authenticated. @@ -220,28 +220,28 @@ System.Collections.ObjectModel.ReadOnlyCollection<System.IdentityModel.Policy.IAuthorizationPolicy> - + The to be validated. When overridden in a derived class, authenticates the specified security token and returns the set of authorization policies for the security token. A of type that contains the set of authorization policies in effect for this application. - method to authenticate a specific security token type. - - When the method is overridden, follow these guidelines: - -- When the security token passed into the `token` parameter cannot be validated, throw a exception. - -- When there are no authorization policies in effect for this application, return an empty of type . - - When this method returns `null`, Windows Communication Foundation throws a exception. - - The method is called by the method. - + method to authenticate a specific security token type. + + When the method is overridden, follow these guidelines: + +- When the security token passed into the `token` parameter cannot be validated, throw a exception. + +- When there are no authorization policies in effect for this application, return an empty of type . + + When this method returns `null`, Windows Communication Foundation throws a exception. + + The method is called by the method. + ]]> diff --git a/xml/System.IdentityModel.Selectors/SecurityTokenResolver.xml b/xml/System.IdentityModel.Selectors/SecurityTokenResolver.xml index bb0d959a81a..87223e1d598 100644 --- a/xml/System.IdentityModel.Selectors/SecurityTokenResolver.xml +++ b/xml/System.IdentityModel.Selectors/SecurityTokenResolver.xml @@ -37,21 +37,21 @@ Represents a utility class that can retrieve security tokens or keys when you have a key identifier or key identifier clause. - class to retrieve a key or security token when you have a key identifier or key identifier clause. The and methods retrieve a token given that there is a key identifier or key identifier clause. The and retrieve a key given that there is a key identifier clause. The methods with a `Try` prefix return `false` when the retrieval is unsuccessful, whereas the methods without a `Try` prefix throw an exception. - + class to retrieve a key or security token when you have a key identifier or key identifier clause. The and methods retrieve a token given that there is a key identifier or key identifier clause. The and retrieve a key given that there is a key identifier clause. The methods with a `Try` prefix return `false` when the retrieval is unsuccessful, whereas the methods without a `Try` prefix throw an exception. + ]]> - - - - - + + + + + Constructor System.IdentityModel @@ -89,8 +89,8 @@ System.IdentityModel.Selectors.SecurityTokenResolver - - + + A of type that contains the set of security tokens for which this security token resolver can resolve key identifiers and key identifier clauses to. @@ -99,11 +99,11 @@ Creates a default security token resolver for the specified security tokens. A that resolves key identifiers and clauses that match the security tokens specified in the parameter. - and methods on the specified security tokens to resolve key identifiers and key identifier clauses. - + and methods on the specified security tokens to resolve key identifiers and key identifier clauses. + ]]> @@ -133,11 +133,11 @@ The custom configuration elements. When overridden in a derived class, loads custom configuration from XML. - . You can override this method to provide functionality in a derived class. - + . You can override this method to provide functionality in a derived class. + ]]> @@ -163,18 +163,18 @@ System.IdentityModel.Tokens.SecurityKey - + A to retrieve the key for. Obtains the key that is referenced in the specified key identifier clause. A that is the key referenced in the specified key identifier clause. - and methods differ in what happens when the key identifier clause cannot be resolved to a key. The method returns `false`, whereas the method throws an exception. - + and methods differ in what happens when the key identifier clause cannot be resolved to a key. The method returns `false`, whereas the method throws an exception. + ]]> @@ -212,18 +212,18 @@ System.IdentityModel.Tokens.SecurityToken - + The to create a security token for. Retrieves a security token that matches one of the security key identifier clauses contained within the specified key identifier. A that represents the specified key identifier. - and methods differ in what happens when the key identifier cannot be resolved to a security token. The method returns `false`, whereas the method throws an exception. - + and methods differ in what happens when the key identifier cannot be resolved to a security token. The method returns `false`, whereas the method throws an exception. + ]]> @@ -252,18 +252,18 @@ System.IdentityModel.Tokens.SecurityToken - + The to create a security token for. Retrieves the security token that matches the specified key identifier clause. A that represents the specified key identifier clause. - and methods differ in what happens when the key identifier clause cannot be resolved to a security token. The method returns `false`, whereas the method throws an exception. - + and methods differ in what happens when the key identifier clause cannot be resolved to a security token. The method returns `false`, whereas the method throws an exception. + ]]> @@ -289,8 +289,8 @@ System.Boolean - - + + A to retrieve the key for. @@ -299,11 +299,11 @@ when a key can be retrieved for the specified key identifier clause; otherwise, . - and methods differ in what happens when the key identifier clause cannot be resolved to a key. The method returns `false`, whereas the method throws an exception. - + and methods differ in what happens when the key identifier clause cannot be resolved to a key. The method returns `false`, whereas the method throws an exception. + ]]> @@ -331,8 +331,8 @@ System.Boolean - - + + A to retrieve the key for. @@ -341,11 +341,11 @@ when a key can be retrieved for the specified key identifier clause; otherwise, . - method is called by the and methods. - + method is called by the and methods. + ]]> @@ -380,8 +380,8 @@ System.Boolean - - + + The to create a security token for. @@ -390,11 +390,11 @@ when a security token can be retrieved for the specified key identifier; otherwise, . - and methods differ in what happens when the key identifier cannot be resolved to a security token. The method returns `false`, whereas the method throws an exception. - + and methods differ in what happens when the key identifier cannot be resolved to a security token. The method returns `false`, whereas the method throws an exception. + ]]> @@ -422,8 +422,8 @@ System.Boolean - - + + The to create a security token for. @@ -432,11 +432,11 @@ when a security token can be retrieved for the specified key identifier clause; otherwise, . - and methods differ in what happens when the key identifier clause cannot be resolved to a security token. The method returns `false`, whereas the method throws an exception. - + and methods differ in what happens when the key identifier clause cannot be resolved to a security token. The method returns `false`, whereas the method throws an exception. + ]]> @@ -473,8 +473,8 @@ System.Boolean - - + + The to create a security token for. @@ -483,11 +483,11 @@ when a security token can be retrieved for the specified key identifier; otherwise, . - method is called by the and methods. - + method is called by the and methods. + ]]> @@ -513,8 +513,8 @@ System.Boolean - - + + The to create a security token for. @@ -523,11 +523,11 @@ when a security token can be retrieved for the specified key identifier clause; otherwise, . - method is called by the and methods. - + method is called by the and methods. + ]]> diff --git a/xml/System.IdentityModel.Selectors/X509CertificateValidator.xml b/xml/System.IdentityModel.Selectors/X509CertificateValidator.xml index abf3f24ae67..8b62668f82b 100644 --- a/xml/System.IdentityModel.Selectors/X509CertificateValidator.xml +++ b/xml/System.IdentityModel.Selectors/X509CertificateValidator.xml @@ -41,17 +41,17 @@ Validates an X.509 certificate. - class to specify how an X.509 certificate is deemed valid. This can be done using by deriving a class from and overriding the method. - - - -## Examples + class to specify how an X.509 certificate is deemed valid. This can be done using by deriving a class from and overriding the method. + + + +## Examples :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/c_x509certificatevalidator/cs/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/c_x509certificatevalidator/vb/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/c_x509certificatevalidator/vb/source.vb" id="Snippet1"::: + ]]> @@ -84,17 +84,17 @@ Initializes a new instance of the class. - @@ -123,13 +123,13 @@ Gets a validator that validates the X.509 certificate using a trust chain. A that validates the X.509 certificate using a trust chain. - class. - + class. + ]]> @@ -158,8 +158,8 @@ System.IdentityModel.Selectors.X509CertificateValidator - - + + @@ -168,13 +168,13 @@ Gets a validator that verifies the X.509 certificate by specifying the context and chain policy that is used to build and verify a trust chain. A that validates the X.509 certificate using a trust chain. - method instead of the property to specify the context or to set chain policy. Chain policy can be used to specify the Enhanced Key Usage (EKU) for which the chain should be validated, or specify revocation checking. - - The return value for this static method can be supplied as a parameter to the constructors for the class that take a validator. - + method instead of the property to specify the context or to set chain policy. Chain policy can be used to specify the Enhanced Key Usage (EKU) for which the chain should be validated, or specify revocation checking. + + The return value for this static method can be supplied as a parameter to the constructors for the class that take a validator. + ]]> @@ -200,8 +200,8 @@ System.IdentityModel.Selectors.X509CertificateValidator - - + + @@ -210,13 +210,13 @@ Gets a validator that verifies the certificate is in the certificate store or by specifying the context and chain policy that is used to build a certificate trust chain. The certificate is trusted if it passes either verification method. A that verifies the certificate is in the certificate store or by building a certificate trust chain. - method instead of the property to specify the context or to set chain policy. Chain policy can be used to specify the Enhanced Key Usage (EKU) for which the chain should be validated, or specify revocation checking. - - The value of this static property can be supplied as a parameter to one of the constructors for the class. - + method instead of the property to specify the context or to set chain policy. Chain policy can be used to specify the Enhanced Key Usage (EKU) for which the chain should be validated, or specify revocation checking. + + The value of this static property can be supplied as a parameter to one of the constructors for the class. + ]]> @@ -246,11 +246,11 @@ The custom configuration elements. When overridden in a derived class, loads custom configuration from XML. - . You can override this method to provide functionality in a derived class. - + . You can override this method to provide functionality in a derived class. + ]]> @@ -279,13 +279,13 @@ Gets a validator that performs no validation on an X.509 certificate. As a result, an X.509 certificate is always considered to be valid. A that performs no validation on the X.509 certificate. - class. - + class. + ]]> @@ -314,11 +314,11 @@ Gets a validator that verifies the certificate is in the certificate store or by building a certificate trust chain. The certificate is trusted if it passes either verification method. A that verifies the certificate is in the certificate store or by building a certificate trust chain. - class. - + class. + ]]> @@ -347,11 +347,11 @@ Gets a validator that verifies the certificate is in the certificate store. A that verifies the certificate is in the certificate store. - class. - + class. + ]]> @@ -391,19 +391,19 @@ The that represents the X.509 certificate to validate. When overridden in a derived class, validates the X.509 certificate. - method to specify how the X.509 certificate is validated. - - When the X.509 certificate that is passed into the `certificate` parameter does not pass validation, throw the . - - - -## Examples + method to specify how the X.509 certificate is validated. + + When the X.509 certificate that is passed into the `certificate` parameter does not pass validation, throw the . + + + +## Examples :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/c_x509certificatevalidator/cs/source.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/c_x509certificatevalidator/vb/source.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/c_x509certificatevalidator/vb/source.vb" id="Snippet2"::: + ]]> diff --git a/xml/System.IdentityModel.Selectors/X509SecurityTokenAuthenticator.xml b/xml/System.IdentityModel.Selectors/X509SecurityTokenAuthenticator.xml index 58aad4655ae..07d48a28ae5 100644 --- a/xml/System.IdentityModel.Selectors/X509SecurityTokenAuthenticator.xml +++ b/xml/System.IdentityModel.Selectors/X509SecurityTokenAuthenticator.xml @@ -23,11 +23,11 @@ Authenticates an . - class to authenticate security tokens. - + class to authenticate security tokens. + ]]> @@ -63,11 +63,11 @@ Initializes a new instance of the class. - method is called to authenticate the token, the X.509 certificate is not mapped to a Windows identity and the certificate is validated using a certificate chain. - + method is called to authenticate the token, the X.509 certificate is not mapped to a Windows identity and the certificate is validated using a certificate chain. + ]]> @@ -98,13 +98,13 @@ A that verifies that the certificate is valid. Initializes a new instance of the class using the specified certificate validator. - class provides a set of pre-defined certificate validation models, such as the property. These validation models can be passed to the `validator` parameter. When an application requires a custom validation method, derive a class from and override the method. The method is called by the method. - - By default, the does not map the X.509 certificate to a Windows identity. - + class provides a set of pre-defined certificate validation models, such as the property. These validation models can be passed to the `validator` parameter. When an application requires a custom validation method, derive a class from and override the method. The method is called by the method. + + By default, the does not map the X.509 certificate to a Windows identity. + ]]> @@ -123,8 +123,8 @@ 4.0.0.0 - - + + A that verifies that the certificate is valid. @@ -132,17 +132,17 @@ to map the identity of the certificate to a Windows identity; otherwise, . Initializes a new instance of the class using the specified certificate validation method and indicates whether the identity of the certificate is mapped to a Windows identity. - class provides a set of pre-defined certificate validation models, such as the property. These validation models can be passed to the `validator` parameter. When an application requires a custom validation method, derive a class from and override the method. The method is called by the method. - - When the method is called to authenticate the token and `mapToWindows` is `true`, the X.509 certificate is mapped to a Windows account and claims are added to the with the Windows groups that the user belongs to. How the X.509 certificate is mapped to a Windows account depends upon the security token type: - -- When the security token is of type , the X.509 certificate is mapped using the property. - -- When the security token is of type `X509SecurityToken`, the X.509 certificate is mapped to a Windows account using its user principal name (UPN). - + class provides a set of pre-defined certificate validation models, such as the property. These validation models can be passed to the `validator` parameter. When an application requires a custom validation method, derive a class from and override the method. The method is called by the method. + + When the method is called to authenticate the token and `mapToWindows` is `true`, the X.509 certificate is mapped to a Windows account and claims are added to the with the Windows groups that the user belongs to. How the X.509 certificate is mapped to a Windows account depends upon the security token type: + +- When the security token is of type , the X.509 certificate is mapped using the property. + +- When the security token is of type `X509SecurityToken`, the X.509 certificate is mapped to a Windows account using its user principal name (UPN). + ]]> @@ -161,9 +161,9 @@ 4.0.0.0 - - - + + + A that verifies that the certificate is valid. @@ -173,15 +173,15 @@ to include the groups the Windows user belongs to in the property that is constructed throughout the authentication process; otherwise, . Initializes a new instance of the class using the specified certificate validation method and indicates whether the identity of the certificate is mapped to a Windows identity and the Windows groups the user belongs to. - class has several static properties, such as the property that can be passed to the `validator` parameter. These properties provide common validation methods for X.509 certificates. When a custom validation method is required, derive a class from and override the method. The method is called by the method. - - When `true` is passed into the `mapToWindows` parameter, the X.509 certificate is mapped to a Windows account and relevant claims are added to the , such as the Windows groups that the user belongs to. When the security token is of type , the property is using the identity that is specified in the token; otherwise, the X.509 certificate is mapped to a Windows identity using a Kerberos S4U logon based on the user principal name SubjectAltNames extension of the X.509 certificate. - + class has several static properties, such as the property that can be passed to the `validator` parameter. These properties provide common validation methods for X.509 certificates. When a custom validation method is required, derive a class from and override the method. The method is called by the method. + + When `true` is passed into the `mapToWindows` parameter, the X.509 certificate is mapped to a Windows account and relevant claims are added to the , such as the Windows groups that the user belongs to. When the security token is of type , the property is using the identity that is specified in the token; otherwise, the X.509 certificate is mapped to a Windows identity using a Kerberos S4U logon based on the user principal name SubjectAltNames extension of the X.509 certificate. + ]]> @@ -217,11 +217,11 @@ when is a security token or a class that derives from ; otherwise, . - method does not authenticate the security token; that is performed by the method. - + method does not authenticate the security token; that is performed by the method. + ]]> @@ -247,13 +247,13 @@ to map the X.509 certificate to a Windows account; otherwise, . - property can only be set in a constructor. - - If transport-level SSL or HTTPS security is being used and mapping is already provided by the underlying security channel or by Internet Information Services (IIS), then that mapping is applied with no chain validation. Otherwise, prior to doing the mapping, the certificate is validated using a certificate chain, and the certificate must chain to an NT_AUTHORITY identity. The chain structure used corresponds to the CERT_CHAIN_POLICY_NT_AUTH as defined in the [CertVerifyCertificateChainPolicy function](/windows/win32/api/wincrypt/nf-wincrypt-certverifycertificatechainpolicy). This behavior only occurs when mapping a certificate to a Windows account. - + property can only be set in a constructor. + + If transport-level SSL or HTTPS security is being used and mapping is already provided by the underlying security channel or by Internet Information Services (IIS), then that mapping is applied with no chain validation. Otherwise, prior to doing the mapping, the certificate is validated using a certificate chain, and the certificate must chain to an NT_AUTHORITY identity. The chain structure used corresponds to the CERT_CHAIN_POLICY_NT_AUTH as defined in the [CertVerifyCertificateChainPolicy function](/windows/win32/api/wincrypt/nf-wincrypt-certverifycertificatechainpolicy). This behavior only occurs when mapping a certificate to a Windows account. + ]]> @@ -288,19 +288,19 @@ Authenticates the specified security token and returns the set of authorization policies for the security token. A of type that contains the set of authorization policies in effect for this application. - method is overridden, follow these guidelines: - -- When the security token passed into the `token` parameter cannot be validated, throw the exception. - -- When there are no authorization policies in effect for this application, return an empty of type . - - When this method returns `null`, Windows Communication Foundation throws a exception. - - The method calls the method of the validation method specified in the constructor to authenticate the `token` parameter. - + method is overridden, follow these guidelines: + +- When the security token passed into the `token` parameter cannot be validated, throw the exception. + +- When there are no authorization policies in effect for this application, return an empty of type . + + When this method returns `null`, Windows Communication Foundation throws a exception. + + The method calls the method of the validation method specified in the constructor to authenticate the `token` parameter. + ]]> diff --git a/xml/System.IdentityModel.Tokens/GenericXmlSecurityToken.xml b/xml/System.IdentityModel.Tokens/GenericXmlSecurityToken.xml index 1d39a803de1..01dcb0b6cdc 100644 --- a/xml/System.IdentityModel.Tokens/GenericXmlSecurityToken.xml +++ b/xml/System.IdentityModel.Tokens/GenericXmlSecurityToken.xml @@ -31,13 +31,13 @@ Represents a security token that is based upon XML. - class when you receive a token over the wire that is not defined in a specification or there is no way for you to determine the type of the security token. For example, in a federation scenario when you send a Request Security Token (RST) to a Security Token Service (STS) you do not always know the type of the security token returned by the STS. In such cases, you can use a to store the security token as XML along with its internal and external references. - - Use the class to define claims using XML when one of the built-in security tokens does not suffice. Other security tokens can define their claims using XML, however the security token generically allows a security token to have an application-defined set of XML. - + class when you receive a token over the wire that is not defined in a specification or there is no way for you to determine the type of the security token. For example, in a federation scenario when you send a Request Security Token (RST) to a Security Token Service (STS) you do not always know the type of the security token returned by the STS. In such cases, you can use a to store the security token as XML along with its internal and external references. + + Use the class to define claims using XML when one of the built-in security tokens does not suffice. Other security tokens can define their claims using XML, however the security token generically allows a security token to have an application-defined set of XML. + ]]> @@ -85,20 +85,20 @@ A of type that contains the set authorization policies for this security token. Initializes a new instance of the class. - key identifier clause is created for this security token and set to the property. - - When the is obtained in a federation scenario, the proof token contains the key that is encrypted for the client. - + key identifier clause is created for this security token and set to the property. + + When the is obtained in a federation scenario, the proof token contains the key that is encrypted for the client. + ]]> - is . - - -or- - + is . + + -or- + is . @@ -178,11 +178,11 @@ when is not and the same type as either the or property values; otherwise, . - method to determine if a security token can create a specific key identifier. To create the key identifier call the method. - + method to determine if a security token can create a specific key identifier. To create the key identifier call the method. + ]]> @@ -228,13 +228,13 @@ Creates the specified key identifier clause. A that is a key identifier clause for a security token. - property or the property is returned by the method depending on the type that is passed into the `T` parameter. - - Use the method to determine if a security token can create a specific key identifier. To create the key identifier call the method. - + property or the property is returned by the method depending on the type that is passed into the `T` parameter. + + Use the method to determine if a security token can create a specific key identifier. To create the key identifier call the method. + ]]> @@ -306,11 +306,11 @@ Gets a unique identifier of the security token. The unique identifier of the security token. - security token is serialized into XML, the value of the `Id` attribute is set to the value of the property. - + security token is serialized into XML, the value of the `Id` attribute is set to the value of the property. + ]]> @@ -379,20 +379,18 @@ - An to compare to this instance. - An to compare to this instance. Returns a value that indicates whether the key identifier for this instance is equal to the specified key identifier. when is not and matches either the or property values; otherwise, . - and property values using the method on the key identifier clause that is returned by the property values. - + and property values using the method on the key identifier clause that is returned by the property values. + ]]> @@ -429,11 +427,11 @@ Gets the proof token for the security token. A that represents the proof token for the security token. - security token used for authentication in obtaining the security token. - + security token used for authentication in obtaining the security token. + ]]> @@ -469,11 +467,11 @@ Gets the cryptographic keys associated with the proof token. A of type that contains the set of keys associated with the proof token. - property. - + property. + ]]> @@ -510,11 +508,11 @@ Gets the XML that is associated with the security token. An that represents the XML that is associated with the security token. - security token is extensible, so exactly what is contained within the XML is application-dependent. - + security token is extensible, so exactly what is contained within the XML is application-dependent. + ]]> @@ -552,11 +550,11 @@ Returns the current object. The current object. - method returns the , , , and properties. - + method returns the , , , and properties. + ]]> @@ -592,13 +590,13 @@ Gets the first instant in time at which this security token is valid. A that represents the first instant in time at which this security token is valid. - and properties to determine the time period in which a token is valid. The and properties represent the first and last instants in time in which the security token is valid, respectively. - - The property is specified using the `effectiveTime` parameter of the constructor. The value returned from this property is always in Coordinated Universal Time (UTC). - + and properties to determine the time period in which a token is valid. The and properties represent the first and last instants in time in which the security token is valid, respectively. + + The property is specified using the `effectiveTime` parameter of the constructor. The value returned from this property is always in Coordinated Universal Time (UTC). + ]]> @@ -634,13 +632,13 @@ Gets the last instant in time at which this security token is valid. A that represents the last instant in time at which this security token is valid. - and properties to determine the time period in which a token is valid. The and properties represent the first and last instants in time in which the security token is valid, respectively. - - The property is specified using the `expirationTime` parameter of the constructor. The value returned from this property is always in Coordinated Universal Time (UTC). - + and properties to determine the time period in which a token is valid. The and properties represent the first and last instants in time in which the security token is valid, respectively. + + The property is specified using the `expirationTime` parameter of the constructor. The value returned from this property is always in Coordinated Universal Time (UTC). + ]]> diff --git a/xml/System.IdentityModel.Tokens/SamlAssertionKeyIdentifierClause.xml b/xml/System.IdentityModel.Tokens/SamlAssertionKeyIdentifierClause.xml index fa6b70b6eee..fa75d61af7d 100644 --- a/xml/System.IdentityModel.Tokens/SamlAssertionKeyIdentifierClause.xml +++ b/xml/System.IdentityModel.Tokens/SamlAssertionKeyIdentifierClause.xml @@ -53,11 +53,11 @@ The identifier of the that contains the key identifier. Initializes a new instance of the class using the specified SAML assertion identifier. - property of a to this constructor. - + property of a to this constructor. + ]]> @@ -88,13 +88,13 @@ The size of the derived key. Initializes a new instance of the class using the specified SAML assertion identifier, nonce, and key length. - property of a to this constructor. - - The `derivationNonce` and `derivationLength` parameters are ignored when the class is serialized into an outgoing SOAP message. - + property of a to this constructor. + + The `derivationNonce` and `derivationLength` parameters are ignored when the class is serialized into an outgoing SOAP message. + ]]> @@ -121,11 +121,11 @@ Gets the identifier for the that contains the key identifier. The identifier for the that contains the key identifier. - is specified in the property. - + is specified in the property. + ]]> @@ -172,15 +172,15 @@ when the specified key identifier is the same as the current instance; otherwise, . - overload returns a value of `true` when either of the following is `true`: - -- The property of the `keyIdentifierClause` parameter has the same value as the current instance's property. - -- The `keyIdentifierClause` parameter and this instance are the same instance. - + overload returns a value of `true` when either of the following is `true`: + +- The property of the `keyIdentifierClause` parameter has the same value as the current instance's property. + +- The `keyIdentifierClause` parameter and this instance are the same instance. + ]]> @@ -202,7 +202,7 @@ System.Boolean - + The SAML assertion identifier to be compared. @@ -210,11 +210,11 @@ when has the same value as the current instance's property; otherwise, . - diff --git a/xml/System.IdentityModel.Tokens/SecurityKey.xml b/xml/System.IdentityModel.Tokens/SecurityKey.xml index e95fd510616..0ce61f83eab 100644 --- a/xml/System.IdentityModel.Tokens/SecurityKey.xml +++ b/xml/System.IdentityModel.Tokens/SecurityKey.xml @@ -28,21 +28,21 @@ Base class for security keys. - - - - - - + + + + + Constructor System.IdentityModel @@ -80,8 +80,8 @@ System.Byte[] - - + + The cryptographic algorithm that was used to encrypt the key. @@ -89,11 +89,11 @@ When overridden in a derived class, decrypts the specified encrypted key. An array of that contains the decrypted key. - class to specify the algorithm. - + class to specify the algorithm. + ]]> @@ -119,8 +119,8 @@ System.Byte[] - - + + The cryptographic algorithm to encrypt the key with. @@ -128,11 +128,11 @@ When overridden in a derived class, encrypts the specified key. An array of that contains the encrypted key. - class to specify the algorithm. - + class to specify the algorithm. + ]]> @@ -158,7 +158,7 @@ System.Boolean - + The cryptographic algorithm. @@ -166,11 +166,11 @@ when the specified algorithm uses asymmetric keys; otherwise, . - class to specify the algorithm. - + class to specify the algorithm. + ]]> @@ -196,7 +196,7 @@ System.Boolean - + The cryptographic algorithm. @@ -227,7 +227,7 @@ System.Boolean - + The cryptographic algorithm. @@ -235,11 +235,11 @@ when the specified algorithm uses symmetric keys; otherwise, . - class to specify the algorithm. - + class to specify the algorithm. + ]]> diff --git a/xml/System.IdentityModel.Tokens/SecurityToken.xml b/xml/System.IdentityModel.Tokens/SecurityToken.xml index a3b57fa586d..fbc5f5ce0c5 100644 --- a/xml/System.IdentityModel.Tokens/SecurityToken.xml +++ b/xml/System.IdentityModel.Tokens/SecurityToken.xml @@ -286,11 +286,9 @@ - A to compare to this instance. - A to compare to this instance. Returns a value that indicates whether the key identifier for this instance can be resolved to the specified key identifier. if is a and it has the same unique identifier as the property; otherwise, . @@ -329,11 +327,9 @@ - A to get the key for. - A to get the key for. Gets the key for the specified key identifier clause. A that represents the key. diff --git a/xml/System.IdentityModel.Tokens/SymmetricSecurityKey.xml b/xml/System.IdentityModel.Tokens/SymmetricSecurityKey.xml index 71bfbc35a24..4bc0beb85b0 100644 --- a/xml/System.IdentityModel.Tokens/SymmetricSecurityKey.xml +++ b/xml/System.IdentityModel.Tokens/SymmetricSecurityKey.xml @@ -28,11 +28,11 @@ Represents the abstract base class for all keys that are generated using symmetric algorithms. - @@ -84,11 +84,11 @@ System.Byte[] - - - - - + + + + + A URI that represents the cryptographic algorithm to use to generate the derived key. @@ -99,13 +99,13 @@ When overridden in a derived class, generates a derived key using the specified cryptographic algorithm and parameters for the current key. An array of that contains the derived key. - field. + field. Due to collision problems with SHA1, Microsoft recommends a security model based on SHA256 or better. - + ]]> @@ -131,8 +131,8 @@ System.Security.Cryptography.ICryptoTransform - - + + A cryptographic algorithm that decrypts cipher text, such as encrypted XML. @@ -140,11 +140,11 @@ When overridden in a derived class, gets a transform that decrypts cipher text using the specified cryptographic algorithm. An that represents the decryption transform. - class to specify the algorithm. - + class to specify the algorithm. + ]]> @@ -170,8 +170,8 @@ System.Security.Cryptography.ICryptoTransform - - + + A cryptographic algorithm that encrypts XML. @@ -179,11 +179,11 @@ When overridden in a derived class, gets a transform that encrypts XML using the specified cryptographic algorithm. An that represents the encryption transform. - class to specify the algorithm. - + class to specify the algorithm. + ]]> @@ -209,7 +209,7 @@ System.Int32 - + The cryptographic algorithm to get the size of the initialization vector (). @@ -239,18 +239,18 @@ System.Security.Cryptography.KeyedHashAlgorithm - + The keyed hash algorithm to get an instance of. When overridden in a derived class, gets an instance of the specified keyed hash algorithm. A that represents the keyed hash algorithm. - class to specify the algorithm. - + class to specify the algorithm. + ]]> @@ -287,11 +287,11 @@ When overridden in a derived class, gets an instance of the specified symmetric algorithm. A that represents the symmetric algorithm. - class to specify the algorithm. - + class to specify the algorithm. + ]]> diff --git a/xml/System.Linq.Expressions/Expression.xml b/xml/System.Linq.Expressions/Expression.xml index 12829443a42..efedaddba7e 100644 --- a/xml/System.Linq.Expressions/Expression.xml +++ b/xml/System.Linq.Expressions/Expression.xml @@ -163,8 +163,8 @@ - - + + The to set as the node type. @@ -6329,9 +6329,9 @@ The following code example shows how to create an expression that adds two integ System.Linq.Expressions.DynamicExpression - - - + + + The runtime binder for the dynamic operation. @@ -6382,9 +6382,9 @@ The following code example shows how to create an expression that adds two integ System.Linq.Expressions.DynamicExpression - - - + + + The runtime binder for the dynamic operation. @@ -6435,9 +6435,9 @@ The following code example shows how to create an expression that adds two integ System.Linq.Expressions.DynamicExpression - - - + + + [System.ParamArray] @@ -6495,10 +6495,10 @@ The following code example shows how to create an expression that adds two integ System.Linq.Expressions.DynamicExpression - - - - + + + + The runtime binder for the dynamic operation. @@ -6550,11 +6550,11 @@ The following code example shows how to create an expression that adds two integ System.Linq.Expressions.DynamicExpression - - - - - + + + + + The runtime binder for the dynamic operation. @@ -6607,12 +6607,12 @@ The following code example shows how to create an expression that adds two integ System.Linq.Expressions.DynamicExpression - - - - - - + + + + + + The runtime binder for the dynamic operation. @@ -13196,9 +13196,9 @@ As with `Func`, the last argument is the return type. It can be set to `System.V System.Linq.Expressions.DynamicExpression - - - + + + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 2, 1 })] @@ -13249,9 +13249,9 @@ As with `Func`, the last argument is the return type. It can be set to `System.V System.Linq.Expressions.DynamicExpression - - - + + + The type of the delegate used by the . @@ -13296,9 +13296,9 @@ As with `Func`, the last argument is the return type. It can be set to `System.V System.Linq.Expressions.DynamicExpression - - - + + + [System.ParamArray] @@ -13353,10 +13353,10 @@ As with `Func`, the last argument is the return type. It can be set to `System.V System.Linq.Expressions.DynamicExpression - - - - + + + + The type of the delegate used by the . @@ -13401,11 +13401,11 @@ As with `Func`, the last argument is the return type. It can be set to `System.V System.Linq.Expressions.DynamicExpression - - - - - + + + + + The type of the delegate used by the . @@ -13451,12 +13451,12 @@ As with `Func`, the last argument is the return type. It can be set to `System.V System.Linq.Expressions.DynamicExpression - - - - - - + + + + + + The type of the delegate used by the . diff --git a/xml/System.Linq.Expressions/ExpressionVisitor.xml b/xml/System.Linq.Expressions/ExpressionVisitor.xml index 0a67491d3c4..85035e62635 100644 --- a/xml/System.Linq.Expressions/ExpressionVisitor.xml +++ b/xml/System.Linq.Expressions/ExpressionVisitor.xml @@ -54,11 +54,11 @@ Represents a visitor or rewriter for expression trees. - @@ -772,7 +772,7 @@ System.Linq.Expressions.Expression - + The expression to visit. @@ -869,13 +869,13 @@ Visits the children of the extension expression. The modified expression, if it or any subexpression was modified; otherwise, returns the original expression. - , which gives the node a chance to walk its children. By default, will try to reduce the node. - + , which gives the node a chance to walk its children. By default, will try to reduce the node. + ]]> diff --git a/xml/System.Linq.Expressions/Expression`1.xml b/xml/System.Linq.Expressions/Expression`1.xml index e5c38f1def9..2858129300f 100644 --- a/xml/System.Linq.Expressions/Expression`1.xml +++ b/xml/System.Linq.Expressions/Expression`1.xml @@ -66,32 +66,32 @@ The type of the delegate that the represents. Represents a strongly typed lambda expression as a data structure in the form of an expression tree. This class cannot be inherited. - , the compiler emits instructions to build an expression tree. - + , the compiler emits instructions to build an expression tree. + > [!NOTE] -> A conversion from a lambda expression to type `Expression` (`Expression(Of D)` in Visual Basic) exists if a conversion from the lambda expression to a delegate of type `D` exists. However, the conversion may fail, for example, if the body of the lambda expression is a block. This means that delegates and expression trees behave similarly with regard to overload resolution. - - The expression tree is an in-memory data representation of the lambda expression. The expression tree makes the structure of the lambda expression transparent and explicit. You can interact with the data in the expression tree just as you can with any other data structure. - - The ability to treat expressions as data structures enables APIs to receive user code in a format that can be inspected, transformed, and processed in a custom manner. For example, the LINQ to SQL data access implementation uses this facility to translate expression trees to Transact-SQL statements that can be evaluated by the database. - - Many standard query operators defined in the class have one or more parameters of type . - - The of an is . - - Use the or method to create an object. - - - -## Examples - The following code example demonstrates how to represent a lambda expression both as executable code in the form of a delegate and as data in the form of an expression tree. It also demonstrates how to turn the expression tree back into executable code by using the method. - +> A conversion from a lambda expression to type `Expression` (`Expression(Of D)` in Visual Basic) exists if a conversion from the lambda expression to a delegate of type `D` exists. However, the conversion may fail, for example, if the body of the lambda expression is a block. This means that delegates and expression trees behave similarly with regard to overload resolution. + + The expression tree is an in-memory data representation of the lambda expression. The expression tree makes the structure of the lambda expression transparent and explicit. You can interact with the data in the expression tree just as you can with any other data structure. + + The ability to treat expressions as data structures enables APIs to receive user code in a format that can be inspected, transformed, and processed in a custom manner. For example, the LINQ to SQL data access implementation uses this facility to translate expression trees to Transact-SQL statements that can be evaluated by the database. + + Many standard query operators defined in the class have one or more parameters of type . + + The of an is . + + Use the or method to create an object. + + + +## Examples + The following code example demonstrates how to represent a lambda expression both as executable code in the form of a delegate and as data in the form of an expression tree. It also demonstrates how to turn the expression tree back into executable code by using the method. + :::code language="csharp" source="~/snippets/csharp/System.Linq.Expressions/ExpressionTDelegate/Overview/ExpressionT.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Linq.Expressions.ExpressionT/VB/ExpressionT.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Linq.Expressions.ExpressionT/VB/ExpressionT.vb" id="Snippet1"::: + ]]> Lambda Expressions (C# Programming Guide) @@ -184,21 +184,21 @@ Compiles the lambda expression described by the expression tree into executable code and produces a delegate that represents the lambda expression. A delegate of type that represents the compiled lambda expression described by the . - method produces a delegate of type `TDelegate` at runtime. When that delegate is executed, it has the behavior described by the semantics of the . - - The method can be used to obtain the value of any expression tree. First, create a lambda expression that has the expression as its body by using the method. Then call to obtain a delegate, and execute the delegate to obtain the value of the expression. - - - -## Examples - The following code example demonstrates how is used to execute an expression tree. - + method produces a delegate of type `TDelegate` at runtime. When that delegate is executed, it has the behavior described by the semantics of the . + + The method can be used to obtain the value of any expression tree. First, create a lambda expression that has the expression as its body by using the method. Then call to obtain a delegate, and execute the delegate to obtain the value of the expression. + + + +## Examples + The following code example demonstrates how is used to execute an expression tree. + :::code language="csharp" source="~/snippets/csharp/System.Linq.Expressions/ExpressionTDelegate/Overview/ExpressionT.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Linq.Expressions.ExpressionT/VB/ExpressionT.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Linq.Expressions.ExpressionT/VB/ExpressionT.vb" id="Snippet2"::: + ]]> @@ -243,7 +243,7 @@ TDelegate - + @@ -286,7 +286,7 @@ TDelegate - + Debugging information generator used by the compiler to mark sequence points and annotate local variables. diff --git a/xml/System.Linq.Expressions/LambdaExpression.xml b/xml/System.Linq.Expressions/LambdaExpression.xml index 7dce79e853e..be25025afc2 100644 --- a/xml/System.Linq.Expressions/LambdaExpression.xml +++ b/xml/System.Linq.Expressions/LambdaExpression.xml @@ -63,23 +63,23 @@ Describes a lambda expression. This captures a block of code that is similar to a .NET method body. - type represents a lambda expression in the form of an expression tree. The type, which derives from and captures the type of the lambda expression more explicitly, can also be used to represent a lambda expression. At runtime, an expression tree node that represents a lambda expression is always of type . - - The value of the property of a is . - - Use the factory methods to create a object. - - - -## Examples - The following example demonstrates how to create an expression that represents a lambda expression that adds 1 to the passed argument by using the method. - + type represents a lambda expression in the form of an expression tree. The type, which derives from and captures the type of the lambda expression more explicitly, can also be used to represent a lambda expression. At runtime, an expression tree node that represents a lambda expression is always of type . + + The value of the property of a is . + + Use the factory methods to create a object. + + + +## Examples + The following example demonstrates how to create an expression that represents a lambda expression that adds 1 to the passed argument by using the method. + :::code language="csharp" source="~/snippets/csharp/System.Linq.Expressions/BlockExpression/Overview/program.cs" id="Snippet42"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet42"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.linq.expressions.expressiondev10/vb/module1.vb" id="Snippet42"::: + ]]> @@ -185,11 +185,11 @@ Produces a delegate that represents the lambda expression. A that contains the compiled version of the lambda expression. - method can be used to convert a expression tree into the delegate that it represents. - + method can be used to convert a expression tree into the delegate that it represents. + ]]> @@ -234,7 +234,7 @@ System.Delegate - + @@ -277,7 +277,7 @@ System.Delegate - + Debugging information generator used by the compiler to mark sequence points and annotate local variables. @@ -324,7 +324,7 @@ System.Void - + A which will be used to hold the lambda's IL. @@ -354,8 +354,8 @@ System.Void - - + + A which will be used to hold the lambda's IL. @@ -418,11 +418,11 @@ Gets the name of the lambda expression. The name of the lambda expression. - diff --git a/xml/System.Linq.Expressions/MemberBinding.xml b/xml/System.Linq.Expressions/MemberBinding.xml index bbebf95c71f..6f4b5729a97 100644 --- a/xml/System.Linq.Expressions/MemberBinding.xml +++ b/xml/System.Linq.Expressions/MemberBinding.xml @@ -102,8 +102,8 @@ - - + + The that discriminates the type of binding that is represented. diff --git a/xml/System.Linq/Enumerable.xml b/xml/System.Linq/Enumerable.xml index 100af2669f3..d3261150a05 100644 --- a/xml/System.Linq/Enumerable.xml +++ b/xml/System.Linq/Enumerable.xml @@ -792,8 +792,8 @@ - - + + The type of the elements of . @@ -11335,8 +11335,8 @@ If comparer is `null`, the default comparer - + + The type of the elements of . diff --git a/xml/System.Messaging/MessageQueue.xml b/xml/System.Messaging/MessageQueue.xml index beab1331b13..9d4e8af6857 100644 --- a/xml/System.Messaging/MessageQueue.xml +++ b/xml/System.Messaging/MessageQueue.xml @@ -57,38 +57,38 @@ Provides access to a queue on a Message Queuing server. - class is a wrapper around Message Queuing. There are multiple versions of Message Queuing, and using the class can result in slightly different behavior, depending on the operating system you are using. - - The class provides a reference to a Message Queuing queue. You can specify a path in the constructor to connect to an existing resource, or you can create a new queue on the server. Before you can call , , or , you must associate the new instance of the class with an existing queue. At that point, you can manipulate the queue properties such as and . - - supports two types of message retrieval: synchronous and asynchronous. The synchronous methods, and , cause the process thread to wait a specified time interval for a new message to arrive in the queue. The asynchronous methods, and , allow the main application tasks to continue in a separate thread until a message arrives in the queue. These methods work by using callback objects and state objects to communicate information between threads. - - When you create a new instance of the class, you are not creating a new Message Queuing queue. Instead, you can use the , , and methods to manage queues on the server. - - Unlike , and are `static` members, so you can call them without creating a new instance of the class. - - You can set the object's property with one of three names: the friendly name, the , or the . The friendly name, which is defined by the queue's and properties, is \\ for a public queue, and \\`Private$`\\ for a private queue. The property allows offline access to message queues. Lastly, you can use the queue's property to set the queue's . - + + The class provides a reference to a Message Queuing queue. You can specify a path in the constructor to connect to an existing resource, or you can create a new queue on the server. Before you can call , , or , you must associate the new instance of the class with an existing queue. At that point, you can manipulate the queue properties such as and . + + supports two types of message retrieval: synchronous and asynchronous. The synchronous methods, and , cause the process thread to wait a specified time interval for a new message to arrive in the queue. The asynchronous methods, and , allow the main application tasks to continue in a separate thread until a message arrives in the queue. These methods work by using callback objects and state objects to communicate information between threads. + + When you create a new instance of the class, you are not creating a new Message Queuing queue. Instead, you can use the , , and methods to manage queues on the server. + + Unlike , and are `static` members, so you can call them without creating a new instance of the class. + + You can set the object's property with one of three names: the friendly name, the , or the . The friendly name, which is defined by the queue's and properties, is \\ for a public queue, and \\`Private$`\\ for a private queue. The property allows offline access to message queues. Lastly, you can use the queue's property to set the queue's . + For a list of initial property values for an instance of , see the constructor. - -## Examples - The following code example creates new objects using various path name syntax types. In each case, it sends a message to the queue whose path is defined in the constructor. - + +## Examples + The following code example creates new objects using various path name syntax types. In each case, it sends a message to the queue whose path is defined in the constructor. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue.Path/CPP/mqpath.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/Overview/mqpath.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.Path/VB/mqpath.vb" id="Snippet1"::: - - The following code example sends a message to a queue, and receives a message from a queue, using an application-specific class called `Order`. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.Path/VB/mqpath.vb" id="Snippet1"::: + + The following code example sends a message to a queue, and receives a message from a queue, using an application-specific class called `Order`. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue.Receive_noparms/CPP/mqreceive_noparms.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/Overview/mqreceive_noparms.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.Receive_noparms/VB/mqreceive_noparms.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.Receive_noparms/VB/mqreceive_noparms.vb" id="Snippet1"::: + ]]> Only the method is thread safe. @@ -133,29 +133,29 @@ Initializes a new instance of the class. After the parameterless constructor initializes the new instance, you must set the instance's property before you can use the instance. - class that is not immediately tied to a queue on the Message Queuing server. Before using this instance, you must connect it to an existing Message Queuing queue by setting the property. Alternatively, you can set the reference to the method's return value, thereby creating a new Message Queuing queue. - - The constructor instantiates a new instance of the class; it does not create a new Message Queuing queue. - - The following table shows initial property values for an instance of . - -|Property|Initial value| -|--------------|-------------------| -||The values set by the parameterless constructor of the class.| -||| -||The values set by the parameterless constructor of the class. All the filter values are set to `true`.| -||`false`| - - - -## Examples - The following code example creates a new . - - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/.ctor/class1.cs" id="Snippet1"::: - + class that is not immediately tied to a queue on the Message Queuing server. Before using this instance, you must connect it to an existing Message Queuing queue by setting the property. Alternatively, you can set the reference to the method's return value, thereby creating a new Message Queuing queue. + + The constructor instantiates a new instance of the class; it does not create a new Message Queuing queue. + + The following table shows initial property values for an instance of . + +|Property|Initial value| +|--------------|-------------------| +||The values set by the parameterless constructor of the class.| +||| +||The values set by the parameterless constructor of the class. All the filter values are set to `true`.| +||`false`| + + + +## Examples + The following code example creates a new . + + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/.ctor/class1.cs" id="Snippet1"::: + ]]> @@ -185,62 +185,62 @@ The location of the queue referenced by this . Initializes a new instance of the class that references the Message Queuing queue at the specified path. - instance to a particular Message Queuing queue, for which you know the path, format name, or label. If you want to grant exclusive access to the first application that references the queue, you must set the property to `true` or use the constructor that passes a read-access restriction parameter. - - The constructor instantiates a new instance of the class; it does not create a new Message Queuing queue. To create a new queue in Message Queuing, use . - - The syntax of the `path` parameter depends on the type of queue it references, as shown in the following table. - -|Queue type|Syntax| -|----------------|------------| -|Public queue|`MachineName`\\`QueueName`| -|Private queue|`MachineName`\\`Private$`\\`QueueName`| -|Journal queue|`MachineName`\\`QueueName`\\`Journal$`| -|Machine journal queue|`MachineName`\\`Journal$`| -|Machine dead-letter queue|`MachineName`\\`Deadletter$`| -|Machine transactional dead-letter queue|`MachineName`\\`XactDeadletter$`| - - Alternatively, you can use the or to describe the queue path, as shown in the following table. - -|Reference|Syntax|Example| -|---------------|------------|-------------| -|Format name|`FormatName:` [ *format name* ]|`FormatName:Public=` 5A5F7535-AE9A-41d4-935C-845C2AFF7112

`FormatName:DIRECT=SPX:` `NetworkNumber`; `HostNumber`\\`QueueName`

`FormatName:DIRECT=TCP:` `IPAddress`\\`QueueName`

`FormatName:DIRECT=OS:` `MachineName`\\`QueueName`| -|Label|`Label:` [ *label* ]|`Label:` TheLabel| - - To work offline, you must use the format name syntax, not the path name syntax for the constructor. Otherwise, an exception is thrown because the primary domain controller is not available to resolve the path to the format name. - - The following table shows initial property values for an instance of . These values are based on the properties of the Message Queuing queue with the path specified by the `path` parameter. - -|Property|Initial value| -|--------------|-------------------| -||`false`| -||0| -||| -||The values set by the parameterless constructor of the class.| -||`true`, if the Message Queuing queue's privacy level setting is "Body"; otherwise, `false`.| -||| -||| -||The value of the Message Queuing queue's computer name property.| -||| -||| -||The values set by the parameterless constructor of the class.| -||, if not set by the constructor.| -||, if not set by the constructor.| -||`false`| -||`true`, if the Message Queuing object's journal setting is enabled; otherwise, `false`.| - - - -## Examples - The following code example creates new objects using various path name syntax types. In each case, it sends a message to the queue whose path is defined in the constructor. - + instance to a particular Message Queuing queue, for which you know the path, format name, or label. If you want to grant exclusive access to the first application that references the queue, you must set the property to `true` or use the constructor that passes a read-access restriction parameter. + + The constructor instantiates a new instance of the class; it does not create a new Message Queuing queue. To create a new queue in Message Queuing, use . + + The syntax of the `path` parameter depends on the type of queue it references, as shown in the following table. + +|Queue type|Syntax| +|----------------|------------| +|Public queue|`MachineName`\\`QueueName`| +|Private queue|`MachineName`\\`Private$`\\`QueueName`| +|Journal queue|`MachineName`\\`QueueName`\\`Journal$`| +|Machine journal queue|`MachineName`\\`Journal$`| +|Machine dead-letter queue|`MachineName`\\`Deadletter$`| +|Machine transactional dead-letter queue|`MachineName`\\`XactDeadletter$`| + + Alternatively, you can use the or to describe the queue path, as shown in the following table. + +|Reference|Syntax|Example| +|---------------|------------|-------------| +|Format name|`FormatName:` [ *format name* ]|`FormatName:Public=` 5A5F7535-AE9A-41d4-935C-845C2AFF7112

`FormatName:DIRECT=SPX:` `NetworkNumber`; `HostNumber`\\`QueueName`

`FormatName:DIRECT=TCP:` `IPAddress`\\`QueueName`

`FormatName:DIRECT=OS:` `MachineName`\\`QueueName`| +|Label|`Label:` [ *label* ]|`Label:` TheLabel| + + To work offline, you must use the format name syntax, not the path name syntax for the constructor. Otherwise, an exception is thrown because the primary domain controller is not available to resolve the path to the format name. + + The following table shows initial property values for an instance of . These values are based on the properties of the Message Queuing queue with the path specified by the `path` parameter. + +|Property|Initial value| +|--------------|-------------------| +||`false`| +||0| +||| +||The values set by the parameterless constructor of the class.| +||`true`, if the Message Queuing queue's privacy level setting is "Body"; otherwise, `false`.| +||| +||| +||The value of the Message Queuing queue's computer name property.| +||| +||| +||The values set by the parameterless constructor of the class.| +||, if not set by the constructor.| +||, if not set by the constructor.| +||`false`| +||`true`, if the Message Queuing object's journal setting is enabled; otherwise, `false`.| + + + +## Examples + The following code example creates new objects using various path name syntax types. In each case, it sends a message to the queue whose path is defined in the constructor. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue.Path/CPP/mqpath.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/Overview/mqpath.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.Path/VB/mqpath.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.Path/VB/mqpath.vb" id="Snippet1"::: + ]]>
The property is not valid, possibly because it has not been set. @@ -274,66 +274,66 @@ to grant exclusive read access to the first application that accesses the queue; otherwise, . Initializes a new instance of the class that references the Message Queuing queue at the specified path and with the specified read-access restriction. - to a particular Message Queuing queue, for which you know the path, format name, or label. If you want to grant exclusive access to the first application that references the queue, set the `sharedModeDenyReceive` parameter to `true`. Otherwise, set `sharedModeDenyReceive` to `false` or use the constructor that has only a `path` parameter. - - Setting `sharedModeDenyReceive` to `true` affects all objects that access the Message Queuing queue, including other applications. The effects of the parameter are not restricted to this application. - - The constructor creates a new instance of the class; it does not create a new Message Queuing queue. To create a new queue in Message Queuing, use . - - The syntax of the `path` parameter depends on the type of queue. - -|Queue type|Syntax| -|----------------|------------| -|Public queue|`MachineName`\\`QueueName`| -|Private queue|`MachineName`\\`Private$`\\`QueueName`| -|Journal queue|`MachineName`\\`QueueName`\\`Journal$`| -|Machine journal queue|`MachineName`\\`Journal$`| -|Machine dead-letter queue|`MachineName`\\`Deadletter$`| -|Machine transactional dead-letter queue|`MachineName`\\`XactDeadletter$`| - - Alternatively, you can use the format name or label of a Message Queuing queue to describe the queue path. - -|Reference|Syntax|Example| -|---------------|------------|-------------| -|Format name|`FormatName:` [ *format name* ]|`FormatName:Public=` 5A5F7535-AE9A-41d4-935C-845C2AFF7112

`FormatName:DIRECT=SPX:` `NetworkNumber`; `HostNumber`\\`QueueName`

`FormatName:DIRECT=TCP:` `IPAddress`\\`QueueName`

`FormatName:DIRECT=OS:` `MachineName`\\`QueueName`| -|Label|`Label:` [ *label* ]|`Label:` TheLabel| - - To work offline, you must use the format name syntax, rather than the friendly name syntax. Otherwise, an exception is thrown because the primary domain controller (on which Active Directory resides) is not available to resolve the path to the format name. - - If a opens a queue with the `sharedModeDenyReceive` parameter set to `true`, any that subsequently tries to read from the queue generates a because of a sharing violation. A is also thrown if a tries to access the queue in exclusive mode while another already has non-exclusive access to the queue. - - The following table shows initial property values for an instance of . These values are based on the properties of the Message Queuing queue, with the path specified by the `path` parameter. - -|Property|Initial value| -|--------------|-------------------| -||`false`.| -||0.| -||.| -||The values set by the parameterless constructor of the class.| -||`true`, if the Message Queuing queue's privacy level setting is "Body"; otherwise, `false`.| -||.| -||.| -||The value of the Message Queuing queue's computer name property.| -||.| -||.| -||The values set by the parameterless constructor of the class.| -||, if not set by the constructor.| -||, if not set by the constructor.| -||The value of the `sharedModeDenyReceive` parameter.| -||`true`, if the Message Queuing object's journal setting is enabled; otherwise, `false`.| - - - -## Examples - The following code example creates a new with exclusive access, sets its path, and sends a message to the queue. - + to a particular Message Queuing queue, for which you know the path, format name, or label. If you want to grant exclusive access to the first application that references the queue, set the `sharedModeDenyReceive` parameter to `true`. Otherwise, set `sharedModeDenyReceive` to `false` or use the constructor that has only a `path` parameter. + + Setting `sharedModeDenyReceive` to `true` affects all objects that access the Message Queuing queue, including other applications. The effects of the parameter are not restricted to this application. + + The constructor creates a new instance of the class; it does not create a new Message Queuing queue. To create a new queue in Message Queuing, use . + + The syntax of the `path` parameter depends on the type of queue. + +|Queue type|Syntax| +|----------------|------------| +|Public queue|`MachineName`\\`QueueName`| +|Private queue|`MachineName`\\`Private$`\\`QueueName`| +|Journal queue|`MachineName`\\`QueueName`\\`Journal$`| +|Machine journal queue|`MachineName`\\`Journal$`| +|Machine dead-letter queue|`MachineName`\\`Deadletter$`| +|Machine transactional dead-letter queue|`MachineName`\\`XactDeadletter$`| + + Alternatively, you can use the format name or label of a Message Queuing queue to describe the queue path. + +|Reference|Syntax|Example| +|---------------|------------|-------------| +|Format name|`FormatName:` [ *format name* ]|`FormatName:Public=` 5A5F7535-AE9A-41d4-935C-845C2AFF7112

`FormatName:DIRECT=SPX:` `NetworkNumber`; `HostNumber`\\`QueueName`

`FormatName:DIRECT=TCP:` `IPAddress`\\`QueueName`

`FormatName:DIRECT=OS:` `MachineName`\\`QueueName`| +|Label|`Label:` [ *label* ]|`Label:` TheLabel| + + To work offline, you must use the format name syntax, rather than the friendly name syntax. Otherwise, an exception is thrown because the primary domain controller (on which Active Directory resides) is not available to resolve the path to the format name. + + If a opens a queue with the `sharedModeDenyReceive` parameter set to `true`, any that subsequently tries to read from the queue generates a because of a sharing violation. A is also thrown if a tries to access the queue in exclusive mode while another already has non-exclusive access to the queue. + + The following table shows initial property values for an instance of . These values are based on the properties of the Message Queuing queue, with the path specified by the `path` parameter. + +|Property|Initial value| +|--------------|-------------------| +||`false`.| +||0.| +||.| +||The values set by the parameterless constructor of the class.| +||`true`, if the Message Queuing queue's privacy level setting is "Body"; otherwise, `false`.| +||.| +||.| +||The value of the Message Queuing queue's computer name property.| +||.| +||.| +||The values set by the parameterless constructor of the class.| +||, if not set by the constructor.| +||, if not set by the constructor.| +||The value of the `sharedModeDenyReceive` parameter.| +||`true`, if the Message Queuing object's journal setting is enabled; otherwise, `false`.| + + + +## Examples + The following code example creates a new with exclusive access, sets its path, and sends a message to the queue. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue.ctor_PathSharedModeDenyReceive/CPP/mqctor_denysharedreceive.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/.ctor/mqctor_denysharedreceive.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.ctor_PathSharedModeDenyReceive/VB/mqctor_denysharedreceive.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.ctor_PathSharedModeDenyReceive/VB/mqctor_denysharedreceive.vb" id="Snippet1"::: + ]]>
The property is not valid, possibly because it has not been set. @@ -358,8 +358,8 @@ 4.0.0.0
- - + + The location of the queue referenced by this , which can be "." for the local computer. @@ -394,14 +394,14 @@ to create and use a connection cache; otherwise, . Initializes a new instance of the class. - with exclusive read access and with connection caching enabled. - + with exclusive read access and with connection caching enabled. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue4/cpp/class1.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/.ctor/class11.cs" id="Snippet1"::: - + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/.ctor/class11.cs" id="Snippet1"::: + ]]> @@ -456,11 +456,11 @@ Gets a value that indicates the access mode for the queue. One of the values. -
@@ -497,31 +497,31 @@ if the queue accepts only authenticated messages; otherwise, . The default is . - to `true`, you are restricting access to the queue on the server, not only to this instance. All clients working against the same Message Queuing queue will be affected. - - A queue that accepts only authenticated messages will reject a non-authenticated message. To request notification of message rejection, a sending application can set the property of the message. Because no other indication of message rejection exists, the sending application can lose the message unless you request that it be sent to the dead-letter queue. - - The following table shows whether this property is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|No| -|Remote computer and direct format name|No| - - - -## Examples - The following code example gets and sets the value of a message queue's property. - - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/.ctor/class1.cs" id="Snippet3"::: - + to `true`, you are restricting access to the queue on the server, not only to this instance. All clients working against the same Message Queuing queue will be affected. + + A queue that accepts only authenticated messages will reject a non-authenticated message. To request notification of message rejection, a sending application can set the property of the message. Because no other indication of message rejection exists, the sending application can lose the message unless you request that it be sent to the dead-letter queue. + + The following table shows whether this property is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|No| +|Remote computer and direct format name|No| + + + +## Examples + The following code example gets and sets the value of a message queue's property. + + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/.ctor/class1.cs" id="Snippet3"::: + ]]> An error occurred when accessing a Message Queuing method. @@ -560,31 +560,31 @@ Gets or sets the base priority Message Queuing uses to route a public queue's messages over the network. The single base priority for all messages sent to the (public) queue. The default is zero (0). - property to confer a higher or lower priority to all messages sent to the specified queue than those sent to other queues. Setting this property modifies the Message Queuing queue. Therefore, any other instances are affected by the change. - - A message queue's is not related to the property of a message, which specifies the order in which an incoming message is placed in the queue. - - applies only to public queues whose paths are specified using the format name. The base priority of a private queue is always zero (0). - - The following table shows whether this property is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|No| -|Remote computer and direct format name|No| - - - -## Examples - The following code example gets and sets the value of a message queue's property. - - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/.ctor/class1.cs" id="Snippet4"::: - + property to confer a higher or lower priority to all messages sent to the specified queue than those sent to other queues. Setting this property modifies the Message Queuing queue. Therefore, any other instances are affected by the change. + + A message queue's is not related to the property of a message, which specifies the order in which an incoming message is placed in the queue. + + applies only to public queues whose paths are specified using the format name. The base priority of a private queue is always zero (0). + + The following table shows whether this property is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|No| +|Remote computer and direct format name|No| + + + +## Examples + The following code example gets and sets the value of a message queue's property. + + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/.ctor/class1.cs" id="Snippet4"::: + ]]> The base priority was set to an invalid value. @@ -624,43 +624,43 @@ Initiates an asynchronous peek operation that has no time-out. The operation is not complete until a message becomes available in the queue. The that identifies the posted asynchronous request. - to raise the event when a message becomes available in the queue. - - is also raised if a message already exists in the queue. - - To use , create an event handler that processes the results of the asynchronous operation, and associate it with your event delegate. initiates an asynchronous peek operation; the is notified, through the raising of the event, when a message arrives in the queue. The can then access the message by calling or by retrieving the result using the . - - The method returns immediately, but the asynchronous operation is not completed until the event handler is called. - - Because is asynchronous, you can call it to peek the queue without blocking the current thread of execution. To synchronously peek the queue, use the method. - - Once an asynchronous operation completes, you can call or again in the event handler to keep receiving notifications. - - The that returns identifies the asynchronous operation that the method started. You can use this throughout the lifetime of the operation, although you generally do not use it until is called. However, if you start several asynchronous operations, you can place their values in an array and specify whether to wait for all operations or any operation to complete. In this case, you use the property of the to identify the completed operation. - - If is `false`, the completion event is raised, but an exception will be thrown when calling . - - The following table shows whether this method is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|No| -|Remote computer and direct format name|Yes| - - - -## Examples - The following code example creates an event handler named `MyPeekCompleted`, attaches it to the event handler delegate, and calls to initiate an asynchronous peek operation on the queue that is located at the path ".\myQueue". When a event is raised, the example peeks the message and writes its body to the screen. The example then calls again to initiate a new asynchronous peek operation. - + to raise the event when a message becomes available in the queue. + + is also raised if a message already exists in the queue. + + To use , create an event handler that processes the results of the asynchronous operation, and associate it with your event delegate. initiates an asynchronous peek operation; the is notified, through the raising of the event, when a message arrives in the queue. The can then access the message by calling or by retrieving the result using the . + + The method returns immediately, but the asynchronous operation is not completed until the event handler is called. + + Because is asynchronous, you can call it to peek the queue without blocking the current thread of execution. To synchronously peek the queue, use the method. + + Once an asynchronous operation completes, you can call or again in the event handler to keep receiving notifications. + + The that returns identifies the asynchronous operation that the method started. You can use this throughout the lifetime of the operation, although you generally do not use it until is called. However, if you start several asynchronous operations, you can place their values in an array and specify whether to wait for all operations or any operation to complete. In this case, you use the property of the to identify the completed operation. + + If is `false`, the completion event is raised, but an exception will be thrown when calling . + + The following table shows whether this method is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|No| +|Remote computer and direct format name|Yes| + + + +## Examples + The following code example creates an event handler named `MyPeekCompleted`, attaches it to the event handler delegate, and calls to initiate an asynchronous peek operation on the queue that is located at the path ".\myQueue". When a event is raised, the example peeks the message and writes its body to the screen. The example then calls again to initiate a new asynchronous peek operation. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue.BeginPeek_noparms/CPP/mqbeginpeek_noparms.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/BeginPeek/mqbeginpeek_noparms.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.BeginPeek_noparms/VB/mqbeginpeek_noparms.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.BeginPeek_noparms/VB/mqbeginpeek_noparms.vb" id="Snippet1"::: + ]]> An error occurred when accessing a Message Queuing method. @@ -696,45 +696,45 @@ Initiates an asynchronous peek operation that has a specified time-out. The operation is not complete until either a message becomes available in the queue or the time-out occurs. The that identifies the posted asynchronous request. - to raise the event when a message becomes available in the queue or when the specified interval of time has expired. - - is also raised if a message already exists in the queue. - - To use , create an event handler that processes the results of the asynchronous operation, and associate it with your event delegate. initiates an asynchronous peek operation; the is notified, through the raising of the event, when a message arrives in the queue. The can then access the message by calling or by retrieving the result using the . - - The method returns immediately, but the asynchronous operation is not completed until the event handler is called. - - Because is asynchronous, you can call it to peek the queue without blocking the current thread of execution. To synchronously peek the queue, use the method. - - Once an asynchronous operation completes, you can call or again in the event handler to keep receiving notifications. - - The that returns identifies the asynchronous operation that the method started. You can use this throughout the lifetime of the operation, although you generally do not use it until is called. However, if you start several asynchronous operations, you can place their values in an array and specify whether to wait for all operations or any operation to complete. In this case, you use the property of the to identify the completed operation. - - This overload specifies a time-out. If the interval specified by the `timeout` parameter expires, this component raises the event. Because no message exists, a subsequent call to will throw an exception. - - If is `false`, the completion event is raised, but an exception will be thrown when calling . - - The following table shows whether this method is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|No| -|Remote computer and direct format name|Yes| - - - -## Examples - The following code example creates an asynchronous peek operation, using the queue path ".\myQueue". It creates an event handler, `MyPeekCompleted`, and attaches it to the event handler delegate. is called with a time-out of one minute, to initiate the asynchronous peek operation. When a event is raised or the time-out expires, the message is retrieved if one exists, and its body is written to the screen. Then is called again to initiate a new asynchronous peek operation with the same time-out. - + to raise the event when a message becomes available in the queue or when the specified interval of time has expired. + + is also raised if a message already exists in the queue. + + To use , create an event handler that processes the results of the asynchronous operation, and associate it with your event delegate. initiates an asynchronous peek operation; the is notified, through the raising of the event, when a message arrives in the queue. The can then access the message by calling or by retrieving the result using the . + + The method returns immediately, but the asynchronous operation is not completed until the event handler is called. + + Because is asynchronous, you can call it to peek the queue without blocking the current thread of execution. To synchronously peek the queue, use the method. + + Once an asynchronous operation completes, you can call or again in the event handler to keep receiving notifications. + + The that returns identifies the asynchronous operation that the method started. You can use this throughout the lifetime of the operation, although you generally do not use it until is called. However, if you start several asynchronous operations, you can place their values in an array and specify whether to wait for all operations or any operation to complete. In this case, you use the property of the to identify the completed operation. + + This overload specifies a time-out. If the interval specified by the `timeout` parameter expires, this component raises the event. Because no message exists, a subsequent call to will throw an exception. + + If is `false`, the completion event is raised, but an exception will be thrown when calling . + + The following table shows whether this method is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|No| +|Remote computer and direct format name|Yes| + + + +## Examples + The following code example creates an asynchronous peek operation, using the queue path ".\myQueue". It creates an event handler, `MyPeekCompleted`, and attaches it to the event handler delegate. is called with a time-out of one minute, to initiate the asynchronous peek operation. When a event is raised or the time-out expires, the message is retrieved if one exists, and its body is written to the screen. Then is called again to initiate a new asynchronous peek operation with the same time-out. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue.BeginPeek_timeout/CPP/mqbeginpeek_timeout.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/BeginPeek/mqbeginpeek_timeout.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.BeginPeek_timeout/VB/mqbeginpeek_timeout.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.BeginPeek_timeout/VB/mqbeginpeek_timeout.vb" id="Snippet1"::: + ]]> The value specified for the parameter is not valid. @@ -774,51 +774,51 @@ Initiates an asynchronous peek operation that has a specified time-out and a specified state object, which provides associated information throughout the operation's lifetime. The operation is not complete until either a message becomes available in the queue or the time-out occurs. The that identifies the posted asynchronous request. - to raise the event when a message becomes available in the queue or when the specified interval of time has expired. - - is also raised if a message already exists in the queue. - - Use this overload to associate information with the operation that will be preserved throughout the operation's lifetime. The event handler can access this information by looking at the property of the that is associated with the operation. - - To use , create an event handler that processes the results of the asynchronous operation, and associate it with your event delegate. initiates an asynchronous peek operation; the is notified, through the raising of the event, when a message arrives in the queue. The can then access the message by calling or by retrieving the result using the . - - The method returns immediately, but the asynchronous operation is not completed until the event handler is called. - - Because is asynchronous, you can call it to peek the queue without blocking the current thread of execution. To synchronously peek the queue, use the method. - - Once an asynchronous operation completes, you can call or again in the event handler to keep receiving notifications. - - returns a that identifies the asynchronous operation that the method started. You can use this throughout the lifetime of the operation, although you generally do not use it until is called. However, if you start several asynchronous operations, you can place their values in an array and specify whether to wait for all operations or any operation to complete. In this case, you use the property of the to identify the completed operation. - - This overload specifies a time-out and a state object. If the interval specified by the `timeout` parameter expires, this component raises the event. Because no message exists, a subsequent call to will throw an exception. - - The state object associates state information with the operation. For example, if you call multiple times to initiate multiple operations, you can identify each operation through a separate state object that you define. For an illustration of this scenario, see the Example section. - - You can also use the state object to pass information across process threads. If a thread is started but the callback is on a different thread in an asynchronous scenario, the state object is marshaled and passed back along with information from the event. - - If is `false`, the completion event is raised, but an exception will be thrown when calling . - - The following table shows whether this method is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|No| -|Remote computer and direct format name|Yes| - - - -## Examples - The following code example creates an asynchronous peek operation, using the queue path ".\myQueue". It creates an event handler, `MyPeekCompleted`, and attaches it to the event handler delegate. is called, with a time-out of one minute. Each call to has a unique associated integer that identifies that particular operation. When a event is raised or the time-out expired, the message, if one exists, is retrieved and its body and the operation-specific integer identifier are written to the screen. Then is called again to initiate a new asynchronous peek operation with the same time-out and the associated integer of the just completed operation. - + to raise the event when a message becomes available in the queue or when the specified interval of time has expired. + + is also raised if a message already exists in the queue. + + Use this overload to associate information with the operation that will be preserved throughout the operation's lifetime. The event handler can access this information by looking at the property of the that is associated with the operation. + + To use , create an event handler that processes the results of the asynchronous operation, and associate it with your event delegate. initiates an asynchronous peek operation; the is notified, through the raising of the event, when a message arrives in the queue. The can then access the message by calling or by retrieving the result using the . + + The method returns immediately, but the asynchronous operation is not completed until the event handler is called. + + Because is asynchronous, you can call it to peek the queue without blocking the current thread of execution. To synchronously peek the queue, use the method. + + Once an asynchronous operation completes, you can call or again in the event handler to keep receiving notifications. + + returns a that identifies the asynchronous operation that the method started. You can use this throughout the lifetime of the operation, although you generally do not use it until is called. However, if you start several asynchronous operations, you can place their values in an array and specify whether to wait for all operations or any operation to complete. In this case, you use the property of the to identify the completed operation. + + This overload specifies a time-out and a state object. If the interval specified by the `timeout` parameter expires, this component raises the event. Because no message exists, a subsequent call to will throw an exception. + + The state object associates state information with the operation. For example, if you call multiple times to initiate multiple operations, you can identify each operation through a separate state object that you define. For an illustration of this scenario, see the Example section. + + You can also use the state object to pass information across process threads. If a thread is started but the callback is on a different thread in an asynchronous scenario, the state object is marshaled and passed back along with information from the event. + + If is `false`, the completion event is raised, but an exception will be thrown when calling . + + The following table shows whether this method is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|No| +|Remote computer and direct format name|Yes| + + + +## Examples + The following code example creates an asynchronous peek operation, using the queue path ".\myQueue". It creates an event handler, `MyPeekCompleted`, and attaches it to the event handler delegate. is called, with a time-out of one minute. Each call to has a unique associated integer that identifies that particular operation. When a event is raised or the time-out expired, the message, if one exists, is retrieved and its body and the operation-specific integer identifier are written to the screen. Then is called again to initiate a new asynchronous peek operation with the same time-out and the associated integer of the just completed operation. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue.BeginPeek_TimeSpanStateObject/CPP/mqbeginpeek_timeoutstateobject.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/BeginPeek/mqbeginpeek_timeoutstateobject.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.BeginPeek_TimeSpanStateObject/VB/mqbeginpeek_timeoutstateobject.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.BeginPeek_TimeSpanStateObject/VB/mqbeginpeek_timeoutstateobject.vb" id="Snippet1"::: + ]]> The value specified for the parameter is not valid. @@ -860,40 +860,40 @@ Initiates an asynchronous peek operation that has a specified time-out and a specified state object, which provides associated information throughout the operation's lifetime. This overload receives notification, through a callback, of the identity of the event handler for the operation. The operation is not complete until either a message becomes available in the queue or the time-out occurs. The that identifies the posted asynchronous request. - event is not raised. The other overloads of rely on this component to raise the event. - - is also raised if a message already exists in the queue. - - The method returns immediately, but the asynchronous operation is not completed until the event handler is called. - - Because is asynchronous, you can call it to peek the queue without blocking the current thread of execution. To synchronously peek the queue, use the method. - - Once an asynchronous operation completes, you can call or again in the event handler to keep receiving notifications. - - returns a that identifies the asynchronous operation that the method started. You can use this throughout the lifetime of the operation, although you generally do not use it until is called. However, if you start several asynchronous operations, you can place their values in an array and specify whether to wait for all operations or any operation to complete. In this case, you use the property of the to identify the completed operation. - - The state object associates state information with the operation. For example, if you call multiple times to initiate multiple operations, you can identify each operation through a separate state object that you define. - - The following table shows whether this method is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|No| -|Remote computer and direct format name|Yes| - - - -## Examples - The following code example creates an asynchronous peek operation. The code example sends a message to a local message queue, then calls , passing in: a time-out value of ten seconds; a unique integer that identifies that particular message; and a new instance of that identifies the event handler, `MyPeekCompleted`. When a event is raised, the event handler peeks at the message and writes the message body and the integer message identifier to the screen. - + event is not raised. The other overloads of rely on this component to raise the event. + + is also raised if a message already exists in the queue. + + The method returns immediately, but the asynchronous operation is not completed until the event handler is called. + + Because is asynchronous, you can call it to peek the queue without blocking the current thread of execution. To synchronously peek the queue, use the method. + + Once an asynchronous operation completes, you can call or again in the event handler to keep receiving notifications. + + returns a that identifies the asynchronous operation that the method started. You can use this throughout the lifetime of the operation, although you generally do not use it until is called. However, if you start several asynchronous operations, you can place their values in an array and specify whether to wait for all operations or any operation to complete. In this case, you use the property of the to identify the completed operation. + + The state object associates state information with the operation. For example, if you call multiple times to initiate multiple operations, you can identify each operation through a separate state object that you define. + + The following table shows whether this method is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|No| +|Remote computer and direct format name|Yes| + + + +## Examples + The following code example creates an asynchronous peek operation. The code example sends a message to a local message queue, then calls , passing in: a time-out value of ten seconds; a unique integer that identifies that particular message; and a new instance of that identifies the event handler, `MyPeekCompleted`. When a event is raised, the event handler peeks at the message and writes the message body and the integer message identifier to the screen. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueueBeginPeek/cpp/class1.cpp" id="Snippet0"::: - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/BeginPeek/class1.cs" id="Snippet0"::: - + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/BeginPeek/class1.cs" id="Snippet0"::: + ]]> The value specified for the parameter is not valid. @@ -939,32 +939,32 @@ Initiates an asynchronous peek operation that has a specified time-out and that uses a specified cursor, a specified peek action, and a specified state object. The state object provides associated information throughout the lifetime of the operation. This overload receives notification, through a callback, of the identity of the event handler for the operation. The operation is not complete until either a message becomes available in the queue or the time-out occurs. The that identifies the posted asynchronous request. - event is not raised. The other overloads of rely on this component to raise the event. - - is also raised if a message already exists in the queue. - - The method returns immediately, but the asynchronous operation is not completed until the event handler is called. - - Because is asynchronous, you can call it to peek the queue without blocking the current thread of execution. To synchronously peek the queue, use the method. - - Once an asynchronous operation completes, you can call or again in the event handler to keep receiving notifications. - - returns a that identifies the asynchronous operation started by the method. You can use this throughout the lifetime of the operation, although you generally do not use it until is called. However, if you start several asynchronous operations, you can place their values in an array and specify whether to wait for all operations or any operation to complete. In this case, use the property of the to identify the completed operation. - - The state object associates state information with the operation. For example, if you call multiple times to initiate multiple operations, you can identify each operation through a separate state object that you define. - - The following table shows whether this method is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|No| -|Remote computer and direct format name|Yes| - + event is not raised. The other overloads of rely on this component to raise the event. + + is also raised if a message already exists in the queue. + + The method returns immediately, but the asynchronous operation is not completed until the event handler is called. + + Because is asynchronous, you can call it to peek the queue without blocking the current thread of execution. To synchronously peek the queue, use the method. + + Once an asynchronous operation completes, you can call or again in the event handler to keep receiving notifications. + + returns a that identifies the asynchronous operation started by the method. You can use this throughout the lifetime of the operation, although you generally do not use it until is called. However, if you start several asynchronous operations, you can place their values in an array and specify whether to wait for all operations or any operation to complete. In this case, use the property of the to identify the completed operation. + + The state object associates state information with the operation. For example, if you call multiple times to initiate multiple operations, you can identify each operation through a separate state object that you define. + + The following table shows whether this method is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|No| +|Remote computer and direct format name|Yes| + ]]> A value other than or was specified for the parameter. @@ -1012,57 +1012,57 @@ Initiates an asynchronous receive operation that has no time-out. The operation is not complete until a message becomes available in the queue. The that identifies the posted asynchronous request. - to raise the event when a message has been removed from the queue. - - is also raised if a message already exists in the queue. - - To use , create an event handler that processes the results of the asynchronous operation and associate it with your event delegate. initiates an asynchronous receive operation; the is notified, through the raising of the event, when a message arrives in the queue. The can then access the message by calling . - - The method returns immediately, but the asynchronous operation is not completed until the event handler is called. - - Because is asynchronous, you can call it to receive a message from the queue without blocking the current thread of execution. To synchronously receive a message, use the method. - - Once an asynchronous operation completes, you can call or again in the event handler to keep receiving notifications. - - The that returns identifies the asynchronous operation that the method started. You can use this throughout the lifetime of the operation, although you generally do not use it until is called. However, if you start several asynchronous operations, you can place their values in an array and specify whether to wait for all operations or any operation to complete. In this case, you use the property of the to identify the completed operation. - - If is `false`, the completion event is raised, but an exception will be thrown when calling . - - Do not use the asynchronous call with transactions. If you want to perform a transactional asynchronous operation, call , and put the transaction and the (synchronous) method within the event handler you create for the peek operation. Your event handler might contain functionality as shown in the following C# code. - -```csharp -myMessageQueue.BeginTransaction(); - myMessageQueue.Receive(); - myMessageQueue.CommitTransaction(); -``` - - The following table shows whether this method is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|No| -|Remote computer and direct format name|Yes| - - - -## Examples - The following code example chains asynchronous requests. It assumes there is a queue on the local computer called "myQueue". The `Main` function begins the asynchronous operation that is handled by the `MyReceiveCompleted` routine. `MyReceiveCompleted` processes the current message and begins a new asynchronous receive operation. - + to raise the event when a message has been removed from the queue. + + is also raised if a message already exists in the queue. + + To use , create an event handler that processes the results of the asynchronous operation and associate it with your event delegate. initiates an asynchronous receive operation; the is notified, through the raising of the event, when a message arrives in the queue. The can then access the message by calling . + + The method returns immediately, but the asynchronous operation is not completed until the event handler is called. + + Because is asynchronous, you can call it to receive a message from the queue without blocking the current thread of execution. To synchronously receive a message, use the method. + + Once an asynchronous operation completes, you can call or again in the event handler to keep receiving notifications. + + The that returns identifies the asynchronous operation that the method started. You can use this throughout the lifetime of the operation, although you generally do not use it until is called. However, if you start several asynchronous operations, you can place their values in an array and specify whether to wait for all operations or any operation to complete. In this case, you use the property of the to identify the completed operation. + + If is `false`, the completion event is raised, but an exception will be thrown when calling . + + Do not use the asynchronous call with transactions. If you want to perform a transactional asynchronous operation, call , and put the transaction and the (synchronous) method within the event handler you create for the peek operation. Your event handler might contain functionality as shown in the following C# code. + +```csharp +myMessageQueue.BeginTransaction(); + myMessageQueue.Receive(); + myMessageQueue.CommitTransaction(); +``` + + The following table shows whether this method is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|No| +|Remote computer and direct format name|Yes| + + + +## Examples + The following code example chains asynchronous requests. It assumes there is a queue on the local computer called "myQueue". The `Main` function begins the asynchronous operation that is handled by the `MyReceiveCompleted` routine. `MyReceiveCompleted` processes the current message and begins a new asynchronous receive operation. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue.BeginReceive_noparms_combined/CPP/mqbeginreceive_noparms_mre.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/BeginReceive/mqbeginreceive_noparms_mre.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.BeginReceive_noparms_combined/VB/mqbeginreceive_noparms_mre.vb" id="Snippet1"::: - - The following code example queues asynchronous requests. The call to uses the in its return value. The `Main` routine waits for all asynchronous operations to be completed before exiting. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.BeginReceive_noparms_combined/VB/mqbeginreceive_noparms_mre.vb" id="Snippet1"::: + + The following code example queues asynchronous requests. The call to uses the in its return value. The `Main` routine waits for all asynchronous operations to be completed before exiting. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue.BeginReceive_noparms_combined/CPP/mqbeginreceive_noparms_wh.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/BeginReceive/mqbeginreceive_noparms_wh.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.BeginReceive_noparms_combined/VB/mqbeginreceive_noparms_wh.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.BeginReceive_noparms_combined/VB/mqbeginreceive_noparms_wh.vb" id="Snippet2"::: + ]]> An error occurred when accessing a Message Queuing method. @@ -1098,52 +1098,52 @@ myMessageQueue.BeginTransaction(); Initiates an asynchronous receive operation that has a specified time-out. The operation is not complete until either a message becomes available in the queue or the time-out occurs. The that identifies the posted asynchronous request. - to raise the event when a message becomes available in the queue or when the specified interval of time has expired. - - is also raised if a message already exists in the queue. - - To use , create an event handler that processes the results of the asynchronous operation and associate it with your event delegate. initiates an asynchronous receive operation; the is notified, through the raising of the event, when a message arrives in the queue. The can then access the message by calling or retrieving the result using the . - - The method returns immediately, but the asynchronous operation is not completed until the event handler is called. - - Because is asynchronous, you can call it to receive a message from the queue without blocking the current thread of execution. To synchronously receive a message, use the method. - - Once an asynchronous operation completes, you can call or again in the event handler to keep receiving notifications. - - If is `false`, the completion event is raised, but an exception will be thrown when calling . - - The that returns identifies the asynchronous operation that the method started. You can use this throughout the lifetime of the operation, although you generally do not use it until is called. However, if you start several asynchronous operations, you can place their values in an array and specify whether to wait for all operations or any operation to complete. In this case, you use the property of the to identify the completed operation. - - This overload specifies a time-out. If the interval specified by the `timeout` parameter expires, this component raises the event. Because no message exists, a subsequent call to will throw an exception. - - Do not use the asynchronous call with transactions. If you want to perform a transactional asynchronous operation, call , and put the transaction and the (synchronous) method within the event handler you create for the peek operation. Your event handler might contain functionality as shown in the following C# code. - -```csharp -myMessageQueue.BeginTransaction(); - myMessageQueue.Receive(); - myMessageQueue.CommitTransaction(); -``` - - The following table shows whether this method is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|No| -|Remote computer and direct format name|Yes| - - - -## Examples - The following code example creates an asynchronous receive operation. The code example creates an event handler, `MyReceiveCompleted`, and attaches it to the event handler delegate. The code example sends a message to a local message queue, then calls , passing in a time-out value of ten seconds. When a event is raised, the event handler receives the message and writes the message body to the screen. - + to raise the event when a message becomes available in the queue or when the specified interval of time has expired. + + is also raised if a message already exists in the queue. + + To use , create an event handler that processes the results of the asynchronous operation and associate it with your event delegate. initiates an asynchronous receive operation; the is notified, through the raising of the event, when a message arrives in the queue. The can then access the message by calling or retrieving the result using the . + + The method returns immediately, but the asynchronous operation is not completed until the event handler is called. + + Because is asynchronous, you can call it to receive a message from the queue without blocking the current thread of execution. To synchronously receive a message, use the method. + + Once an asynchronous operation completes, you can call or again in the event handler to keep receiving notifications. + + If is `false`, the completion event is raised, but an exception will be thrown when calling . + + The that returns identifies the asynchronous operation that the method started. You can use this throughout the lifetime of the operation, although you generally do not use it until is called. However, if you start several asynchronous operations, you can place their values in an array and specify whether to wait for all operations or any operation to complete. In this case, you use the property of the to identify the completed operation. + + This overload specifies a time-out. If the interval specified by the `timeout` parameter expires, this component raises the event. Because no message exists, a subsequent call to will throw an exception. + + Do not use the asynchronous call with transactions. If you want to perform a transactional asynchronous operation, call , and put the transaction and the (synchronous) method within the event handler you create for the peek operation. Your event handler might contain functionality as shown in the following C# code. + +```csharp +myMessageQueue.BeginTransaction(); + myMessageQueue.Receive(); + myMessageQueue.CommitTransaction(); +``` + + The following table shows whether this method is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|No| +|Remote computer and direct format name|Yes| + + + +## Examples + The following code example creates an asynchronous receive operation. The code example creates an event handler, `MyReceiveCompleted`, and attaches it to the event handler delegate. The code example sends a message to a local message queue, then calls , passing in a time-out value of ten seconds. When a event is raised, the event handler receives the message and writes the message body to the screen. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueueBeginReceive1/cpp/class1.cpp" id="Snippet0"::: - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/BeginReceive/class1.cs" id="Snippet0"::: - + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/BeginReceive/class1.cs" id="Snippet0"::: + ]]> The value specified for the parameter is not valid, possibly because it represents a negative number. @@ -1183,56 +1183,56 @@ myMessageQueue.BeginTransaction(); Initiates an asynchronous receive operation that has a specified time-out and a specified state object, which provides associated information throughout the operation's lifetime. The operation is not complete until either a message becomes available in the queue or the time-out occurs. The that identifies the posted asynchronous request. - to raise the event when a message becomes available in the queue or when the specified interval of time has expired. - - is also raised if a message already exists in the queue. - - Use this overload to associate information with the operation that will be preserved throughout the operation's lifetime. The event handler can detect this information by looking at the property of the that is associated with the operation. - - To use , create an event handler that processes the results of the asynchronous operation and associate it with your event delegate. initiates an asynchronous receive operation; the is notified, through the raising of the event, when a message arrives in the queue. The can then access the message by calling or retrieving the result using the . - - The method returns immediately, but the asynchronous operation is not completed until the event handler is called. - - Because is asynchronous, you can call it to receive a message from the queue without blocking the current thread of execution. To synchronously receive a message, use the method. - - Once an asynchronous operation completes, you can call or again in the event handler to keep receiving notifications. - - The that returns identifies the asynchronous operation that the method started. You can use this throughout the lifetime of the operation, although you generally do not use it until is called. However, if you start several asynchronous operations, you can place their values in an array and specify whether to wait for all operations or any operation to complete. In this case, you use the property of the to identify the completed operation. - - This overload specifies a time-out and a state object. If the interval specified by the `timeout` parameter expires, this component raises the event. Because no message exists, a subsequent call to will throw an exception. - - The state object associates state information with the operation. For example, if you call multiple times to initiate multiple operations, you can identify each operation through a separate state object that you define. - - You can also use the state object to pass information across process threads. If a thread is started but the callback is on a different thread in an asynchronous scenario, the state object is marshaled and passed back along with information from the event. - - Do not use the asynchronous call with transactions. If you want to perform a transactional asynchronous operation, call , and put the transaction and the (synchronous) method within the event handler you create for the peek operation. Your event handler might contain functionality as shown in the following C# code. - -```csharp -myMessageQueue.BeginTransaction(); - myMessageQueue.Receive(); - myMessageQueue.CommitTransaction(); -``` - - The following table shows whether this method is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|No| -|Remote computer and direct format name|Yes| - - - -## Examples - The following code example creates an asynchronous receive operation. The code example creates an event handler, `MyReceiveCompleted`, and attaches it to the event handler delegate. The code example sends a message to a local message queue, then calls , passing in a time-out value of ten seconds and a unique integer that identifies that particular message. When a event is raised, the event handler receives the message and writes the message body and the integer message identifier to the screen. - + to raise the event when a message becomes available in the queue or when the specified interval of time has expired. + + is also raised if a message already exists in the queue. + + Use this overload to associate information with the operation that will be preserved throughout the operation's lifetime. The event handler can detect this information by looking at the property of the that is associated with the operation. + + To use , create an event handler that processes the results of the asynchronous operation and associate it with your event delegate. initiates an asynchronous receive operation; the is notified, through the raising of the event, when a message arrives in the queue. The can then access the message by calling or retrieving the result using the . + + The method returns immediately, but the asynchronous operation is not completed until the event handler is called. + + Because is asynchronous, you can call it to receive a message from the queue without blocking the current thread of execution. To synchronously receive a message, use the method. + + Once an asynchronous operation completes, you can call or again in the event handler to keep receiving notifications. + + The that returns identifies the asynchronous operation that the method started. You can use this throughout the lifetime of the operation, although you generally do not use it until is called. However, if you start several asynchronous operations, you can place their values in an array and specify whether to wait for all operations or any operation to complete. In this case, you use the property of the to identify the completed operation. + + This overload specifies a time-out and a state object. If the interval specified by the `timeout` parameter expires, this component raises the event. Because no message exists, a subsequent call to will throw an exception. + + The state object associates state information with the operation. For example, if you call multiple times to initiate multiple operations, you can identify each operation through a separate state object that you define. + + You can also use the state object to pass information across process threads. If a thread is started but the callback is on a different thread in an asynchronous scenario, the state object is marshaled and passed back along with information from the event. + + Do not use the asynchronous call with transactions. If you want to perform a transactional asynchronous operation, call , and put the transaction and the (synchronous) method within the event handler you create for the peek operation. Your event handler might contain functionality as shown in the following C# code. + +```csharp +myMessageQueue.BeginTransaction(); + myMessageQueue.Receive(); + myMessageQueue.CommitTransaction(); +``` + + The following table shows whether this method is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|No| +|Remote computer and direct format name|Yes| + + + +## Examples + The following code example creates an asynchronous receive operation. The code example creates an event handler, `MyReceiveCompleted`, and attaches it to the event handler delegate. The code example sends a message to a local message queue, then calls , passing in a time-out value of ten seconds and a unique integer that identifies that particular message. When a event is raised, the event handler receives the message and writes the message body and the integer message identifier to the screen. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueueBeginReceive2/cpp/class1.cpp" id="Snippet0"::: - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/BeginReceive/class11.cs" id="Snippet0"::: - + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/BeginReceive/class11.cs" id="Snippet0"::: + ]]> The value specified for the parameter is not valid. @@ -1274,52 +1274,52 @@ myMessageQueue.BeginTransaction(); Initiates an asynchronous receive operation that has a specified time-out and a specified state object, which provides associated information throughout the operation's lifetime. This overload receives notification, through a callback, of the identity of the event handler for the operation. The operation is not complete until either a message becomes available in the queue or the time-out occurs. The that identifies the posted asynchronous request. - event is not raised. The other overloads of rely on this component to raise the event. - - is also raised if a message already exists in the queue. - - To use , create an event handler that processes the results of the asynchronous operation and associate it with your event delegate. initiates an asynchronous receive operation; the is notified, through the raising of the event, when a message arrives in the queue. The can then access the message by calling or retrieving the result using the . - - The method returns immediately, but the asynchronous operation is not completed until the event handler is called. - - Because is asynchronous, you can call it to receive a message from the queue without blocking the current thread of execution. To synchronously receive a message, use the method. - - Once an asynchronous operation completes, you can call or again in the event handler to keep receiving notifications. - - The that returns identifies the asynchronous operation that the method started. You can use this throughout the lifetime of the operation, although you generally do not use it until is called. However, if you start several asynchronous operations, you can place their values in an array and specify whether to wait for all operations or any operation to complete. In this case, you use the property of the to identify the completed operation. - - The state object associates state information with the operation. For example, if you call multiple times to initiate multiple operations, you can identify each operation through a separate state object that you define. - - You can also use the state object to pass information across process threads. If a thread is started but the callback is on a different thread in an asynchronous scenario, the state object is marshaled and passed back along with information from the event. - - Do not use the asynchronous call with transactions. If you want to perform a transactional asynchronous operation, call , and put the transaction and the (synchronous) method within the event handler you create for the peek operation. Your event handler might contain functionality as shown in the following C# code. - -```csharp -myMessageQueue.BeginTransaction(); - myMessageQueue.Receive(); - myMessageQueue.CommitTransaction(); -``` - - The following table shows whether this method is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|No| -|Remote computer and direct format name|Yes| - - - -## Examples - The following code example creates an asynchronous receive operation. The code example sends a message to a local message queue, then calls , passing in: a time-out value of ten seconds; a unique integer that identifies that particular message; and a new instance of that identifies the event handler, `MyReceiveCompleted`. When a event is raised, the event handler receives the message and writes the message body and the integer message identifier to the screen. - + event is not raised. The other overloads of rely on this component to raise the event. + + is also raised if a message already exists in the queue. + + To use , create an event handler that processes the results of the asynchronous operation and associate it with your event delegate. initiates an asynchronous receive operation; the is notified, through the raising of the event, when a message arrives in the queue. The can then access the message by calling or retrieving the result using the . + + The method returns immediately, but the asynchronous operation is not completed until the event handler is called. + + Because is asynchronous, you can call it to receive a message from the queue without blocking the current thread of execution. To synchronously receive a message, use the method. + + Once an asynchronous operation completes, you can call or again in the event handler to keep receiving notifications. + + The that returns identifies the asynchronous operation that the method started. You can use this throughout the lifetime of the operation, although you generally do not use it until is called. However, if you start several asynchronous operations, you can place their values in an array and specify whether to wait for all operations or any operation to complete. In this case, you use the property of the to identify the completed operation. + + The state object associates state information with the operation. For example, if you call multiple times to initiate multiple operations, you can identify each operation through a separate state object that you define. + + You can also use the state object to pass information across process threads. If a thread is started but the callback is on a different thread in an asynchronous scenario, the state object is marshaled and passed back along with information from the event. + + Do not use the asynchronous call with transactions. If you want to perform a transactional asynchronous operation, call , and put the transaction and the (synchronous) method within the event handler you create for the peek operation. Your event handler might contain functionality as shown in the following C# code. + +```csharp +myMessageQueue.BeginTransaction(); + myMessageQueue.Receive(); + myMessageQueue.CommitTransaction(); +``` + + The following table shows whether this method is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|No| +|Remote computer and direct format name|Yes| + + + +## Examples + The following code example creates an asynchronous receive operation. The code example sends a message to a local message queue, then calls , passing in: a time-out value of ten seconds; a unique integer that identifies that particular message; and a new instance of that identifies the event handler, `MyReceiveCompleted`. When a event is raised, the event handler receives the message and writes the message body and the integer message identifier to the screen. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueueBeginReceive3/cpp/class1.cpp" id="Snippet0"::: - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/BeginReceive/class12.cs" id="Snippet0"::: - + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/BeginReceive/class12.cs" id="Snippet0"::: + ]]> The value specified for the parameter is not valid. @@ -1363,44 +1363,44 @@ myMessageQueue.BeginTransaction(); Initiates an asynchronous receive operation that has a specified time-out and uses a specified cursor and a specified state object. The state object provides associated information throughout the lifetime of the operation. This overload receives notification, through a callback, of the identity of the event handler for the operation. The operation is not complete until either a message becomes available in the queue or the time-out occurs. The that identifies the posted asynchronous request. - event is not raised. The other overloads of rely on this component to raise the event. - - is also raised if a message already exists in the queue. - - To use , create an event handler that processes the results of the asynchronous operation and associate it with your event delegate. initiates an asynchronous receive operation; the is notified, through the raising of the event, when a message arrives in the queue. The can then access the message by calling or retrieving the result using the . - - The method returns immediately, but the asynchronous operation is not completed until the event handler is called. - - Because is asynchronous, you can call it to receive a message from the queue without blocking the current thread of execution. To synchronously receive a message, use the method. - - Once an asynchronous operation completes, you can call or again in the event handler to keep receiving notifications. - - The that returns identifies the asynchronous operation that the method started. You can use this throughout the lifetime of the operation, although you generally do not use it until is called. However, if you start several asynchronous operations, you can place their values in an array and specify whether to wait for all operations or any operation to complete. In this case, use the property of the to identify the completed operation. - - The state object associates state information with the operation. For example, if you call multiple times to initiate multiple operations, you can identify each operation through a separate state object that you define. - - You can also use the state object to pass information across process threads. If a thread is started but the callback is on a different thread in an asynchronous scenario, the state object is marshaled and passed back along with information from the event. - - Do not use the asynchronous call with transactions. If you want to perform a transactional asynchronous operation, call , and put the transaction and the (synchronous) method within the event handler you create for the peek operation. Your event handler might contain functionality as shown in the following C# code. - -```csharp -myMessageQueue.BeginTransaction(); - myMessageQueue.Receive(); - myMessageQueue.CommitTransaction(); -``` - - The following table shows whether this method is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|No| -|Remote computer and direct format name|Yes| - + event is not raised. The other overloads of rely on this component to raise the event. + + is also raised if a message already exists in the queue. + + To use , create an event handler that processes the results of the asynchronous operation and associate it with your event delegate. initiates an asynchronous receive operation; the is notified, through the raising of the event, when a message arrives in the queue. The can then access the message by calling or retrieving the result using the . + + The method returns immediately, but the asynchronous operation is not completed until the event handler is called. + + Because is asynchronous, you can call it to receive a message from the queue without blocking the current thread of execution. To synchronously receive a message, use the method. + + Once an asynchronous operation completes, you can call or again in the event handler to keep receiving notifications. + + The that returns identifies the asynchronous operation that the method started. You can use this throughout the lifetime of the operation, although you generally do not use it until is called. However, if you start several asynchronous operations, you can place their values in an array and specify whether to wait for all operations or any operation to complete. In this case, use the property of the to identify the completed operation. + + The state object associates state information with the operation. For example, if you call multiple times to initiate multiple operations, you can identify each operation through a separate state object that you define. + + You can also use the state object to pass information across process threads. If a thread is started but the callback is on a different thread in an asynchronous scenario, the state object is marshaled and passed back along with information from the event. + + Do not use the asynchronous call with transactions. If you want to perform a transactional asynchronous operation, call , and put the transaction and the (synchronous) method within the event handler you create for the peek operation. Your event handler might contain functionality as shown in the following C# code. + +```csharp +myMessageQueue.BeginTransaction(); + myMessageQueue.Receive(); + myMessageQueue.CommitTransaction(); +``` + + The following table shows whether this method is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|No| +|Remote computer and direct format name|Yes| + ]]> The parameter is . @@ -1452,29 +1452,29 @@ myMessageQueue.BeginTransaction(); if the exists and the application can read from it; otherwise, . - indicates whether the application is able to peek or receive messages from the queue. If is `true`, the can receive or peek messages from the queue. Otherwise, it cannot. - - is `false` if a queue is already open with exclusive read access (or if it's open with non-exclusive access and this requests exclusive access), or if the application does not have sufficient rights to access it. If your application tries to read from a queue when is `false`, access is denied. - - The following table shows whether this property is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|No| -|Remote computer and direct format name|Yes| - - - -## Examples - The following code example displays the value of a message queue's property. - - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/.ctor/class1.cs" id="Snippet5"::: - + indicates whether the application is able to peek or receive messages from the queue. If is `true`, the can receive or peek messages from the queue. Otherwise, it cannot. + + is `false` if a queue is already open with exclusive read access (or if it's open with non-exclusive access and this requests exclusive access), or if the application does not have sufficient rights to access it. If your application tries to read from a queue when is `false`, access is denied. + + The following table shows whether this property is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|No| +|Remote computer and direct format name|Yes| + + + +## Examples + The following code example displays the value of a message queue's property. + + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/.ctor/class1.cs" id="Snippet5"::: + ]]> @@ -1517,30 +1517,30 @@ myMessageQueue.BeginTransaction(); if the exists and the application can write to it; otherwise, . - indicates whether the application is able to send messages to the queue. If is `true`, the can send messages to the queue. Otherwise, it cannot. - - is `false` if a queue is already open with exclusive write access (or if it's open with non-exclusive access and this requests exclusive access), or if the application does not have sufficient rights to access it. If your application tries to write to a queue when is `false`, access is denied. - - The following table shows whether this property is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|No| -|Remote computer and direct format name|Yes| - - - -## Examples - The following code example displays the value of a message queue's property. - - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/.ctor/class1.cs" id="Snippet6"::: - - ]]> + indicates whether the application is able to send messages to the queue. If is `true`, the can send messages to the queue. Otherwise, it cannot. + + is `false` if a queue is already open with exclusive write access (or if it's open with non-exclusive access and this requests exclusive access), or if the application does not have sufficient rights to access it. If your application tries to write to a queue when is `false`, access is denied. + + The following table shows whether this property is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|No| +|Remote computer and direct format name|Yes| + + + +## Examples + The following code example displays the value of a message queue's property. + + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/.ctor/class1.cs" id="Snippet6"::: + + ]]> @@ -1577,33 +1577,33 @@ myMessageQueue.BeginTransaction(); Gets or sets the queue category. A that represents the queue category (Message Queuing type identifier), which allows an application to categorize its queues. The default is . - property provides access to the Message Queuing Type ID property (which is read/write), accessible through the **Queue Properties** dialog box in the Computer Management Console. You can define a new category. Although you can use to create a category value that is unique across all values, such an action is unnecessary. The category value needs to be distinct only from other categories, not from all other values. For example, you can assign {00000000-0000-0000-0000-000000000001} as the for one set of queues and {00000000-0000-0000-0000-000000000002} as the for another set. - - It is not necessary to set the . The value can be `null`. - - Setting this property modifies the Message Queuing queue. Therefore, any other instances are affected by the change. - - The following table shows whether this property is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|No| -|Remote computer and direct format name|No| - - - -## Examples - The following code example gets and sets the value of a message queue's property. - - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/.ctor/class1.cs" id="Snippet7"::: - + property provides access to the Message Queuing Type ID property (which is read/write), accessible through the **Queue Properties** dialog box in the Computer Management Console. You can define a new category. Although you can use to create a category value that is unique across all values, such an action is unnecessary. The category value needs to be distinct only from other categories, not from all other values. For example, you can assign {00000000-0000-0000-0000-000000000001} as the for one set of queues and {00000000-0000-0000-0000-000000000002} as the for another set. + + It is not necessary to set the . The value can be `null`. + + Setting this property modifies the Message Queuing queue. Therefore, any other instances are affected by the change. + + The following table shows whether this property is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|No| +|Remote computer and direct format name|No| + + + +## Examples + The following code example gets and sets the value of a message queue's property. + + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/.ctor/class1.cs" id="Snippet7"::: + ]]> The queue category was set to an invalid value. @@ -1634,27 +1634,27 @@ myMessageQueue.BeginTransaction(); Clears the connection cache. - , the format names stored in the cache are removed and handles opened and stored in the cache are closed. - - The following table shows whether this method is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|Yes| -|Remote computer and direct format name|Yes| - - - -## Examples - The following code example calls . - - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/.ctor/class1.cs" id="Snippet8"::: - + , the format names stored in the cache are removed and handles opened and stored in the cache are closed. + + The following table shows whether this method is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|Yes| +|Remote computer and direct format name|Yes| + + + +## Examples + The following code example calls . + + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/.ctor/class1.cs" id="Snippet8"::: + ]]> @@ -1680,47 +1680,47 @@ myMessageQueue.BeginTransaction(); Frees all resources allocated by the . - frees all resources associated with a , including shared resources if appropriate. The system re-acquires these resources automatically if they are still available, for example when you call the method, as in the following C# code. - -```csharp -myMessageQueue.Send("Text 1."); -myMessageQueue.Close(); -myMessageQueue.Send("Text 2."); //Resources are re-acquired. -``` - - When you call , all properties that directly access the Message Queuing queue are cleared out. The , , , and all remain as they were. - - does not always free the read and write handles to a queue, because they might be shared. You can take any of the following steps to ensure that frees the read and write handles to a queue: - -- Create the with exclusive access. To do so, call the or constructor, and set the `sharedModeDenyReceive` parameter to `true`. - -- Create the with connection caching disabled. To do so, call the constructor and set the `enableConnectionCache` parameter to `false`. - -- Disable connection caching. To do so, set the property to `false`. - - You should call for a queue before you delete the queue on the Message Queuing server. Otherwise, messages sent to the queue could throw exceptions or appear in the dead-letter queue. - - The following table shows whether this method is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|Yes| -|Remote computer and direct format name|Yes| - - - -## Examples - The following code example closes a Message Queuing queue. - + frees all resources associated with a , including shared resources if appropriate. The system re-acquires these resources automatically if they are still available, for example when you call the method, as in the following C# code. + +```csharp +myMessageQueue.Send("Text 1."); +myMessageQueue.Close(); +myMessageQueue.Send("Text 2."); //Resources are re-acquired. +``` + + When you call , all properties that directly access the Message Queuing queue are cleared out. The , , , and all remain as they were. + + does not always free the read and write handles to a queue, because they might be shared. You can take any of the following steps to ensure that frees the read and write handles to a queue: + +- Create the with exclusive access. To do so, call the or constructor, and set the `sharedModeDenyReceive` parameter to `true`. + +- Create the with connection caching disabled. To do so, call the constructor and set the `enableConnectionCache` parameter to `false`. + +- Disable connection caching. To do so, set the property to `false`. + + You should call for a queue before you delete the queue on the Message Queuing server. Otherwise, messages sent to the queue could throw exceptions or appear in the dead-letter queue. + + The following table shows whether this method is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|Yes| +|Remote computer and direct format name|Yes| + + + +## Examples + The following code example closes a Message Queuing queue. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue.Close/CPP/mqclose.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/Close/mqclose.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.Close/VB/mqclose.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.Close/VB/mqclose.vb" id="Snippet1"::: + ]]> @@ -1759,47 +1759,47 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. Creates a non-transactional Message Queuing queue at the specified path. A that represents the new queue. - class in your application and bind it to an existing queue, use the constructor. To create a new queue in Message Queuing, call . - - The syntax for the `path` parameter depends on the type of queue it references, as shown in the following table. - -|Queue type|Syntax| -|----------------|------------| -|Public queue|`MachineName`\\`QueueName`| -|Private queue|`MachineName`\\`Private$`\\`QueueName`| - - Use "." for the local computer. For more syntax, see the property. - - The following table shows whether this method is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|No| -|Remote computer and direct format name|No| - - - -## Examples - The following code example creates public and private queues. It sends a message to selected queues. - + class in your application and bind it to an existing queue, use the constructor. To create a new queue in Message Queuing, call . + + The syntax for the `path` parameter depends on the type of queue it references, as shown in the following table. + +|Queue type|Syntax| +|----------------|------------| +|Public queue|`MachineName`\\`QueueName`| +|Private queue|`MachineName`\\`Private$`\\`QueueName`| + + Use "." for the local computer. For more syntax, see the property. + + The following table shows whether this method is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|No| +|Remote computer and direct format name|No| + + + +## Examples + The following code example creates public and private queues. It sends a message to selected queues. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue.Create_path/CPP/mqcreate.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/Create/mqcreate.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.Create_path/VB/mqcreate.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.Create_path/VB/mqcreate.vb" id="Snippet1"::: + ]]> The parameter is or is an empty string (""). - A queue already exists at the specified path. - - -or- - + A queue already exists at the specified path. + + -or- + An error occurred when accessing a Message Queuing method. @@ -1833,47 +1833,47 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. Creates a transactional or non-transactional Message Queuing queue at the specified path. A that represents the new queue. - . - - To create a new instance of the class in your application and bind it to an existing queue, use the constructor. To create a new queue in Message Queuing, call . - - The syntax for the `path` parameter depends on the type of queue it references, as shown in the following table. - -|Queue type|Syntax| -|----------------|------------| -|Public queue|`MachineName`\\`QueueName`| -|Private queue|`MachineName`\\`Private$`\\`QueueName`| - - Use "." for the local computer. For more syntax, see the property. - - The following table shows whether this method is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|No| -|Remote computer and direct format name|No| - - - -## Examples - The following code example creates public and private transactional queues. It sends a message to selected queues. - + . + + To create a new instance of the class in your application and bind it to an existing queue, use the constructor. To create a new queue in Message Queuing, call . + + The syntax for the `path` parameter depends on the type of queue it references, as shown in the following table. + +|Queue type|Syntax| +|----------------|------------| +|Public queue|`MachineName`\\`QueueName`| +|Private queue|`MachineName`\\`Private$`\\`QueueName`| + + Use "." for the local computer. For more syntax, see the property. + + The following table shows whether this method is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|No| +|Remote computer and direct format name|No| + + + +## Examples + The following code example creates public and private transactional queues. It sends a message to selected queues. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue.Create_PathTransactional/CPP/mqcreate_transactional.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/Create/mqcreate_transactional.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.Create_PathTransactional/VB/mqcreate_transactional.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.Create_PathTransactional/VB/mqcreate_transactional.vb" id="Snippet1"::: + ]]> The parameter is or is an empty string (""). - A queue already exists at the specified path. - - -or- - + A queue already exists at the specified path. + + -or- + An error occurred when accessing a Message Queuing method. @@ -1935,29 +1935,29 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. Gets the time and date that the queue was created in Message Queuing. A that represents the date and time at which the queue was created. - refers to the queue on the Message Queuing server, not the instance. - - If the queue exists, this property represents the time the queue was created, adjusted to the local time of the server on which the queue exists. - - The following table shows whether this property is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|No| -|Remote computer and direct format name|No| - - - -## Examples - The following code example displays the value of a message queue's property. - - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/.ctor/class1.cs" id="Snippet9"::: - + refers to the queue on the Message Queuing server, not the instance. + + If the queue exists, this property represents the time the queue was created, adjusted to the local time of the server on which the queue exists. + + The following table shows whether this property is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|No| +|Remote computer and direct format name|No| + + + +## Examples + The following code example displays the value of a message queue's property. + + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/.ctor/class1.cs" id="Snippet9"::: + ]]> An error occurred when accessing a Message Queuing method. @@ -1999,55 +1999,55 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. Gets or sets the message property values to be used by default when the application sends messages to the queue. A that contains the default Message Queuing message property values used when the application sends objects other than instances to the queue. - to the queue, the inserts the object into a Message Queuing message. At that time, the applies to the message the property values you specify in the property. Conversely, if you send a to the queue, these properties are already specified for the instance itself, so is ignored for the . - - Although you set the properties through the object, the refers to the properties of the messages that are sent to the queue, not the queue itself. - - The default values for the properties are shown in the following table. - -|Property|Default value| -|--------------|-------------------| -||`AcknowledgeType.None`| -||`null`| -||Zero (0)| -||`true`| -||`EncryptionAlgorithm.RC2`| -||A zero-length array of bytes| -||`HashAlgorithm.MD5`| -||Empty string ("")| -||`MessagePriority.Normal`| -||`false`| -||`null`| -||`Message.InfiniteTimeout`| -||`Message.InfiniteTimeout`| -||`null`| -||`false`| -||`false`| -||`false`| -||`false`| -||`false`| - - The following table shows whether this property is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|Yes| -|Remote computer and direct format name|Yes| - - - -## Examples - The following code example uses the priority of a message to determine default properties to send for the message. - + to the queue, the inserts the object into a Message Queuing message. At that time, the applies to the message the property values you specify in the property. Conversely, if you send a to the queue, these properties are already specified for the instance itself, so is ignored for the . + + Although you set the properties through the object, the refers to the properties of the messages that are sent to the queue, not the queue itself. + + The default values for the properties are shown in the following table. + +|Property|Default value| +|--------------|-------------------| +||`AcknowledgeType.None`| +||`null`| +||Zero (0)| +||`true`| +||`EncryptionAlgorithm.RC2`| +||A zero-length array of bytes| +||`HashAlgorithm.MD5`| +||Empty string ("")| +||`MessagePriority.Normal`| +||`false`| +||`null`| +||`Message.InfiniteTimeout`| +||`Message.InfiniteTimeout`| +||`null`| +||`false`| +||`false`| +||`false`| +||`false`| +||`false`| + + The following table shows whether this property is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|Yes| +|Remote computer and direct format name|Yes| + + + +## Examples + The following code example uses the priority of a message to determine default properties to send for the message. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue.DefaultPropertiesToSend/CPP/mqdefaultpropertiestosend.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/DefaultPropertiesToSend/Overview/mqdefaultpropertiestosend.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.DefaultPropertiesToSend/VB/mqdefaultpropertiestosend.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.DefaultPropertiesToSend/VB/mqdefaultpropertiestosend.vb" id="Snippet1"::: + ]]> The default properties could not be set for the queue, possibly because one of the properties is not valid. @@ -2082,50 +2082,50 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. The location of the queue to be deleted. Deletes a queue on a Message Queuing server. - property. - - Alternatively, you can use the or to describe the queue path. - -|Reference|Syntax| -|---------------|------------| -|Format name|FormatName:[ *format name* ]| -|Label|Label:[ *label* ]| - - The following table shows whether this method is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|No| -|Remote computer and direct format name|No| - - - -## Examples - The following code example deletes a Message Queuing queue, if it exists. - + property. + + Alternatively, you can use the or to describe the queue path. + +|Reference|Syntax| +|---------------|------------| +|Format name|FormatName:[ *format name* ]| +|Label|Label:[ *label* ]| + + The following table shows whether this method is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|No| +|Remote computer and direct format name|No| + + + +## Examples + The following code example deletes a Message Queuing queue, if it exists. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue.ExistsDelete/CPP/mqexistsdelete.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/Delete/mqexistsdelete.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.ExistsDelete/VB/mqexistsdelete.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.ExistsDelete/VB/mqexistsdelete.vb" id="Snippet1"::: + ]]> The parameter is or is an empty string (""). - The syntax for the parameter is not valid. - - -or- - + The syntax for the parameter is not valid. + + -or- + An error occurred when accessing a Message Queuing method. @@ -2167,29 +2167,29 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. if this has exclusive rights to receive messages from the queue; otherwise, . The default is . - specifies the shared mode of the queue referenced by this . Set to `true` to indicate that only this should have access to peek or receive messages from the queue with the specified . If another or another application is associated with the same queue resource, that instance or application will not be able to peek or receive messages, but it can still send them. - - If is `false`, the queue is available to multiple applications for sending, peeking, or receiving messages. - - The following table shows whether this property is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|Yes| -|Remote computer and direct format name|Yes| - - - -## Examples - The following code example gets and sets the value of a message queue's property. - - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/.ctor/class1.cs" id="Snippet10"::: - + specifies the shared mode of the queue referenced by this . Set to `true` to indicate that only this should have access to peek or receive messages from the queue with the specified . If another or another application is associated with the same queue resource, that instance or application will not be able to peek or receive messages, but it can still send them. + + If is `false`, the queue is available to multiple applications for sending, peeking, or receiving messages. + + The following table shows whether this property is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|Yes| +|Remote computer and direct format name|Yes| + + + +## Examples + The following code example gets and sets the value of a message queue's property. + + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/.ctor/class1.cs" id="Snippet10"::: + ]]> @@ -2221,13 +2221,13 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. to release both managed and unmanaged resources; to release only unmanaged resources. Disposes of the resources (other than memory) used by the . - 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 memory it was occupying can be reclaimed by garbage collection. - - You should call before you release your last reference to the . Otherwise, the resources the is using will not be freed until garbage collection calls the object's destructor. - + 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 memory it was occupying can be reclaimed by garbage collection. + + You should call before you release your last reference to the . Otherwise, the resources the is using will not be freed until garbage collection calls the object's destructor. + ]]> @@ -2261,29 +2261,29 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. to create and use a connection cache; otherwise, . - is `true`, the borrows handles from the cache each time you call , , or , rather than open new handles. This can improve performance. Using a connection cache also insulates the from changes in the network topology. - - If you create a new connection to a queue when the connection cache is full, the overwrites the least recently accessed structure with the new connection. You can clear the cache entirely by calling , for example, if the format names of the queues you are working with have changed so that the previous read and write handles are no longer valid. - - The following table shows whether this property is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|Yes| -|Remote computer and direct format name|Yes| - - - -## Examples - The following code example gets and sets the value of a message queue's property. - - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/.ctor/class1.cs" id="Snippet11"::: - + is `true`, the borrows handles from the cache each time you call , , or , rather than open new handles. This can improve performance. Using a connection cache also insulates the from changes in the network topology. + + If you create a new connection to a queue when the connection cache is full, the overwrites the least recently accessed structure with the new connection. You can clear the cache entirely by calling , for example, if the format names of the queues you are working with have changed so that the previous read and write handles are no longer valid. + + The following table shows whether this property is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|Yes| +|Remote computer and direct format name|Yes| + + + +## Examples + The following code example gets and sets the value of a message queue's property. + + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/.ctor/class1.cs" id="Snippet11"::: + ]]> @@ -2320,31 +2320,31 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. Gets or sets a value that indicates whether the queue accepts only non-private (non-encrypted) messages. One of the values. The default is . - and properties) cannot be encrypted. - - Setting this property modifies the Message Queuing queue. Therefore, any other instances are affected by the change. - - Encrypting a message makes the message private. You can specify the queue's encryption requirement to be `None`, `Body`, or `Optional` by setting the property appropriately. The setting of the message must correspond to the encryption requirement of the queue. If the message is not encrypted but the queue specifies `Body`, or if the message is encrypted but the queue specifies `None`, the message is rejected by the queue. If the sending application requests a negative acknowledgment message in this event, Message Queuing indicates the message's rejection to the sending application. If the property is `true`, a message that fails encryption is sent to the dead-letter queue. Otherwise, the message is lost. - - The following table shows whether this property is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|No| -|Remote computer and direct format name|No| - - - -## Examples - The following code example gets and sets the value of a message queue's property. - - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/.ctor/class1.cs" id="Snippet12"::: - + and properties) cannot be encrypted. + + Setting this property modifies the Message Queuing queue. Therefore, any other instances are affected by the change. + + Encrypting a message makes the message private. You can specify the queue's encryption requirement to be `None`, `Body`, or `Optional` by setting the property appropriately. The setting of the message must correspond to the encryption requirement of the queue. If the message is not encrypted but the queue specifies `Body`, or if the message is encrypted but the queue specifies `None`, the message is rejected by the queue. If the sending application requests a negative acknowledgment message in this event, Message Queuing indicates the message's rejection to the sending application. If the property is `true`, a message that fails encryption is sent to the dead-letter queue. Otherwise, the message is lost. + + The following table shows whether this property is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|No| +|Remote computer and direct format name|No| + + + +## Examples + The following code example gets and sets the value of a message queue's property. + + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/.ctor/class1.cs" id="Snippet12"::: + ]]> An error occurred when accessing a Message Queuing method. @@ -2377,35 +2377,35 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. Completes the specified asynchronous peek operation. The associated with the completed asynchronous operation. - event is raised, completes the operation that was initiated by the call. To do so, peeks the message. - - can specify a time-out, which causes the event to be raised if the time-out occurs before a message appears in the queue. When a time-out occurs without a message arriving in the queue, a subsequent call to throws an exception. - - is used to read the message that caused the event to be raised. - - If you want to continue to asynchronously peek messages, you can again call after calling . - - The following table shows whether this method is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|No| -|Remote computer and direct format name|Yes| - - - -## Examples - The following code example creates an event handler named `MyPeekCompleted`, attaches it to the event handler delegate, and calls to initiate an asynchronous peek operation on the queue that is located at the path ".\myQueue". When a event is raised, the example peeks the message and writes its body to the screen. The example then calls again to initiate a new asynchronous peek operation. - + event is raised, completes the operation that was initiated by the call. To do so, peeks the message. + + can specify a time-out, which causes the event to be raised if the time-out occurs before a message appears in the queue. When a time-out occurs without a message arriving in the queue, a subsequent call to throws an exception. + + is used to read the message that caused the event to be raised. + + If you want to continue to asynchronously peek messages, you can again call after calling . + + The following table shows whether this method is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|No| +|Remote computer and direct format name|Yes| + + + +## Examples + The following code example creates an event handler named `MyPeekCompleted`, attaches it to the event handler delegate, and calls to initiate an asynchronous peek operation on the queue that is located at the path ".\myQueue". When a event is raised, the example peeks the message and writes its body to the screen. The example then calls again to initiate a new asynchronous peek operation. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue.BeginPeek_noparms/CPP/mqbeginpeek_noparms.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/BeginPeek/mqbeginpeek_noparms.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.BeginPeek_noparms/VB/mqbeginpeek_noparms.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.BeginPeek_noparms/VB/mqbeginpeek_noparms.vb" id="Snippet1"::: + ]]> The parameter is . @@ -2440,35 +2440,35 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. Completes the specified asynchronous receive operation. The associated with the completed asynchronous operation. - event is raised, completes the operation that was initiated by the call. To do so, receives the message. - - can specify a time-out, which causes the event to be raised if the time-out occurs before a message appears in the queue. When a time-out occurs without a message arriving in the queue, a subsequent call to throws an exception. - - is used to read (removing from the queue) the message that caused the event to be raised. - - If you want to continue to asynchronously receive messages, you can again call after calling . - - The following table shows whether this method is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|No| -|Remote computer and direct format name|Yes| - - - -## Examples - The following code example chains asynchronous requests. It assumes there is a queue on the local computer called "myQueue". The `Main` function begins the asynchronous operation that is handled by the `MyReceiveCompleted` routine. `MyReceiveCompleted` processes the current message and begins a new asynchronous receive operation. - + event is raised, completes the operation that was initiated by the call. To do so, receives the message. + + can specify a time-out, which causes the event to be raised if the time-out occurs before a message appears in the queue. When a time-out occurs without a message arriving in the queue, a subsequent call to throws an exception. + + is used to read (removing from the queue) the message that caused the event to be raised. + + If you want to continue to asynchronously receive messages, you can again call after calling . + + The following table shows whether this method is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|No| +|Remote computer and direct format name|Yes| + + + +## Examples + The following code example chains asynchronous requests. It assumes there is a queue on the local computer called "myQueue". The `Main` function begins the asynchronous operation that is handled by the `MyReceiveCompleted` routine. `MyReceiveCompleted` processes the current message and begins a new asynchronous receive operation. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue.BeginReceive_noparms_combined/CPP/mqbeginreceive_noparms_mre.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/BeginReceive/mqbeginreceive_noparms_mre.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.BeginReceive_noparms_combined/VB/mqbeginreceive_noparms_mre.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.BeginReceive_noparms_combined/VB/mqbeginreceive_noparms_mre.vb" id="Snippet1"::: + ]]> The parameter is . @@ -2504,57 +2504,57 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. if a queue with the specified path exists; otherwise, . - method determines whether a Message Queuing queue exists at a specified path. No method exists to determine whether a queue with a specified format name exists. For more information about the format name syntax and other path syntax forms, see the property.) - - is an expensive operation. Use it only when it is necessary within the application. - + method determines whether a Message Queuing queue exists at a specified path. No method exists to determine whether a queue with a specified format name exists. For more information about the format name syntax and other path syntax forms, see the property.) + + is an expensive operation. Use it only when it is necessary within the application. + > [!NOTE] -> The method does not support the prefix. - - The syntax for the `path` parameter depends on the type of queue, as shown in the following table. - -|Queue type|Syntax| -|----------------|------------| -|Public queue|`MachineName`\\`QueueName`| - - cannot be called to verify the existence of a remote private queue. - - For more syntax, see the property. - - Alternatively, you can use the to describe the queue path. - -|Reference|Syntax| -|---------------|------------| -|Label|Label:[ `label` ]| - - The following table shows whether this method is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|No| -|Remote computer|No| -|Remote computer and direct format name|No| - - - -## Examples - The following code example verifies whether a Message Queuing queue exists, and then deletes it. - +> The method does not support the prefix. + + The syntax for the `path` parameter depends on the type of queue, as shown in the following table. + +|Queue type|Syntax| +|----------------|------------| +|Public queue|`MachineName`\\`QueueName`| + + cannot be called to verify the existence of a remote private queue. + + For more syntax, see the property. + + Alternatively, you can use the to describe the queue path. + +|Reference|Syntax| +|---------------|------------| +|Label|Label:[ `label` ]| + + The following table shows whether this method is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|No| +|Remote computer|No| +|Remote computer and direct format name|No| + + + +## Examples + The following code example verifies whether a Message Queuing queue exists, and then deletes it. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue.ExistsDelete/CPP/mqexistsdelete.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/Delete/mqexistsdelete.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.ExistsDelete/VB/mqexistsdelete.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.ExistsDelete/VB/mqexistsdelete.vb" id="Snippet1"::: + ]]> The syntax is not valid. - An error occurred when accessing a Message Queuing method. - - -or- - + An error occurred when accessing a Message Queuing method. + + -or- + The method is being called on a remote private queue The application used format name syntax when verifying queue existence. @@ -2591,35 +2591,35 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. Gets the unique queue name that Message Queuing generated at the time of the queue's creation. The name for the queue, which is unique on the network. - property contains the format name of the queue. Message Queuing uses the format name to identify which queue to open and how to access it. Unlike most of a queue's characteristics, the format name is not a Message Queuing application queue property, so you cannot access it through the Message Queuing management tool. The format name is simply a unique name for the queue, which Message Queuing generates when it creates the queue or which the application generates later. - - If you specify a path using the path name syntax (such as `myComputer\myQueue`) rather than using the format name syntax when you read or write to the queue, the primary domain controller (which uses Active Directory) translates the into the associated before accessing the queue. If your application is working offline, you must use the format name syntax; otherwise, the primary domain controller will not be available to perform the path translation. - - The following table shows whether this property is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|Yes| -|Remote computer and direct format name|Yes| - - - -## Examples - The following code example displays the value of a message queue's property. - - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/.ctor/class1.cs" id="Snippet13"::: - + property contains the format name of the queue. Message Queuing uses the format name to identify which queue to open and how to access it. Unlike most of a queue's characteristics, the format name is not a Message Queuing application queue property, so you cannot access it through the Message Queuing management tool. The format name is simply a unique name for the queue, which Message Queuing generates when it creates the queue or which the application generates later. + + If you specify a path using the path name syntax (such as `myComputer\myQueue`) rather than using the format name syntax when you read or write to the queue, the primary domain controller (which uses Active Directory) translates the into the associated before accessing the queue. If your application is working offline, you must use the format name syntax; otherwise, the primary domain controller will not be available to perform the path translation. + + The following table shows whether this property is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|Yes| +|Remote computer and direct format name|Yes| + + + +## Examples + The following code example displays the value of a message queue's property. + + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/.ctor/class1.cs" id="Snippet13"::: + ]]> - The is not set. - - -or- - + The is not set. + + -or- + An error occurred when accessing a Message Queuing method. @@ -2665,42 +2665,42 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. Gets or sets the formatter used to serialize an object into or deserialize an object from the body of a message read from or written to the queue. The that produces a stream to be written to or read from the message body. The default is . - property contains an instance of a formatter object, which transforms messages when your application reads or writes to the queue. - - When the application sends message to the queue, the formatter serializes the object into a stream and inserts it into the message body. When reading from a queue, the formatter deserializes the message data into the property of a . - - The is loosely coupled, so it is not necessary to have the same object type on the sender and receiver when using this format. The and serialize the data into binary representation. The is used when sending or receiving COM components. - - and provide faster throughput than the . The allows interoperability with Visual Basic 6.0 Message Queuing applications. - - When your application sends messages to the queue, the applies only to those messages that use the default message properties, . If you send a to the queue, Message Queuing uses the formatter defined in the property to serialize the body instead. - - The class will always use a to receive or peek a message from the queue. The message is deserialized using the property. - - The following table shows whether this property is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|No| -|Remote computer and direct format name|Yes| - -## Examples - The following code example demonstrates formatting a message body using . - + property contains an instance of a formatter object, which transforms messages when your application reads or writes to the queue. + + When the application sends message to the queue, the formatter serializes the object into a stream and inserts it into the message body. When reading from a queue, the formatter deserializes the message data into the property of a . + + The is loosely coupled, so it is not necessary to have the same object type on the sender and receiver when using this format. The and serialize the data into binary representation. The is used when sending or receiving COM components. + + and provide faster throughput than the . The allows interoperability with Visual Basic 6.0 Message Queuing applications. + + When your application sends messages to the queue, the applies only to those messages that use the default message properties, . If you send a to the queue, Message Queuing uses the formatter defined in the property to serialize the body instead. + + The class will always use a to receive or peek a message from the queue. The message is deserialized using the property. + + The following table shows whether this property is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|No| +|Remote computer and direct format name|Yes| + +## Examples + The following code example demonstrates formatting a message body using . + :::code language="csharp" source="~/snippets/csharp/System.Messaging/BinaryMessageFormatter/Overview/message_binaryformatter.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/MessagingBinaryFormatter/VB/message_binaryformatter.vb" id="Snippet1"::: - - The following code example demonstrates formatting a message body using . - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/MessagingBinaryFormatter/VB/message_binaryformatter.vb" id="Snippet1"::: + + The following code example demonstrates formatting a message body using . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/Message.Body/CPP/message_sendreceive.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/Message/Overview/message_sendreceive.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Message.Body/VB/message_sendreceive.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Message.Body/VB/message_sendreceive.vb" id="Snippet1"::: + ]]> @@ -2731,32 +2731,32 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. Returns all the messages that are in the queue. An array of type that represents all the messages in the queue, in the same order as they appear in the Message Queuing queue. - returns a static snapshot of the messages in the queue, not dynamic links to those messages. Therefore, you cannot use the array to modify the messages in the queue. If you want real-time, dynamic interaction with the queue (such as the ability to delete messages), call the method, which returns a dynamic list of the messages in the queue. - - Because returns a copy of the messages in the queue at the time the method was called, the array does not reflect new messages that arrive in the queue or messages that are removed from the queue. - - retrieves only those properties not filtered out by the property. - - The following table shows whether this method is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|No| -|Remote computer and direct format name|Yes| - - - -## Examples - The following code example demonstrates the use of . - + returns a static snapshot of the messages in the queue, not dynamic links to those messages. Therefore, you cannot use the array to modify the messages in the queue. If you want real-time, dynamic interaction with the queue (such as the ability to delete messages), call the method, which returns a dynamic list of the messages in the queue. + + Because returns a copy of the messages in the queue at the time the method was called, the array does not reflect new messages that arrive in the queue or messages that are removed from the queue. + + retrieves only those properties not filtered out by the property. + + The following table shows whether this method is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|No| +|Remote computer and direct format name|Yes| + + + +## Examples + The following code example demonstrates the use of . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue2/cpp/class1.cpp" id="Snippet21"::: - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet21"::: - + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet21"::: + ]]> An error occurred when accessing a Message Queuing method. @@ -2795,26 +2795,26 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. Enumerates the messages in a queue. is deprecated. should be used instead. A that provides a dynamic connection to the messages in the queue. - . - + . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue2/cpp/class1.cpp" id="Snippet22"::: - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet22"::: - + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet22"::: + ]]> @@ -2845,37 +2845,37 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. Gets the identifier of the computer on which the queue referenced by this is located. A that represents a unique identifier for the computer on which the queue is located. - for a remote computer when you are working offline because the application must have access to the directory service on the domain controller. - - The computer identifier (or machine identifier) is a that Message Queuing creates when a computer is added to the enterprise. Message Queuing combines the computer identifier with the `Machine` and `Journal` keywords to create the machine journal's format name, which has the syntax `Machine=;Journal`. The machine journal, which is also known as the journal queue, is a system queue that stores copies of application-generated messages when the property is `true`. - - This syntax for the journal is only valid when constructing the format name for the queue. The path name syntax is `MachineName`\\`Journal$`. - - The following table shows whether this method is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|No| -|Local computer and direct format name|No| -|Remote computer|No| -|Remote computer and direct format name|No| - - - -## Examples - The following code example calls . - - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/.ctor/class1.cs" id="Snippet14"::: - + for a remote computer when you are working offline because the application must have access to the directory service on the domain controller. + + The computer identifier (or machine identifier) is a that Message Queuing creates when a computer is added to the enterprise. Message Queuing combines the computer identifier with the `Machine` and `Journal` keywords to create the machine journal's format name, which has the syntax `Machine=;Journal`. The machine journal, which is also known as the journal queue, is a system queue that stores copies of application-generated messages when the property is `true`. + + This syntax for the journal is only valid when constructing the format name for the queue. The path name syntax is `MachineName`\\`Journal$`. + + The following table shows whether this method is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|No| +|Local computer and direct format name|No| +|Remote computer|No| +|Remote computer and direct format name|No| + + + +## Examples + The following code example calls . + + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/.ctor/class1.cs" id="Snippet14"::: + ]]> - The computer identifier could not be retrieved, possibly because the directory service is not available; for example, if you are working offline. - - -or- - + The computer identifier could not be retrieved, possibly because the directory service is not available; for example, if you are working offline. + + -or- + An error occurred when accessing a Message Queuing method. @@ -2909,35 +2909,35 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. Creates an enumerator object for all the messages in the queue. is deprecated. should be used instead. The holding the messages that are contained in the queue. - creates a dynamic list of all the messages in a queue. You can remove from the queue the message at the enumerator's current position by calling for the that returns. - - Because the cursor is associated with the dynamic list of messages in the queue, the enumeration reflects any modification you make to the messages in the queue, if the message is beyond the current cursor position. For example, the enumerator can automatically access a lower-priority message placed beyond the cursor's current position, but not a higher-priority message inserted before that position. However, you can reset the enumeration, thereby moving the cursor back to the beginning of the list, by calling for the . - - The order of the messages in the enumeration reflects their order in the queue, so higher-priority messages will appear before lower-priority ones. - - If you want a static snapshot of the messages in the queue rather than a dynamic connection to them, call . This method returns an array of objects, which represent the messages at the time the method was called. - - The following table shows whether this method is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|Yes| -|Remote computer and direct format name|Yes| - - - -## Examples - The following code example gets a dynamic list of messages in a queue and counts all messages with the property set to . - + creates a dynamic list of all the messages in a queue. You can remove from the queue the message at the enumerator's current position by calling for the that returns. + + Because the cursor is associated with the dynamic list of messages in the queue, the enumeration reflects any modification you make to the messages in the queue, if the message is beyond the current cursor position. For example, the enumerator can automatically access a lower-priority message placed beyond the cursor's current position, but not a higher-priority message inserted before that position. However, you can reset the enumeration, thereby moving the cursor back to the beginning of the list, by calling for the . + + The order of the messages in the enumeration reflects their order in the queue, so higher-priority messages will appear before lower-priority ones. + + If you want a static snapshot of the messages in the queue rather than a dynamic connection to them, call . This method returns an array of objects, which represent the messages at the time the method was called. + + The following table shows whether this method is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|Yes| +|Remote computer and direct format name|Yes| + + + +## Examples + The following code example gets a dynamic list of messages in a queue and counts all messages with the property set to . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue.GetMessageEnumerator/CPP/mqgetmessageenumerator.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageEnumerator/Overview/mqgetmessageenumerator.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.GetMessageEnumerator/VB/mqgetmessageenumerator.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.GetMessageEnumerator/VB/mqgetmessageenumerator.vb" id="Snippet1"::: + ]]> @@ -2966,26 +2966,26 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. Creates an enumerator object for all the messages in the queue. The holding the messages that are contained in the queue. - creates a dynamic list of all the messages in a queue. You can remove from the queue the message at the enumerator's current position by calling for the that returns. - - Because the cursor is associated with the dynamic list of messages in the queue, the enumeration reflects any modification you make to the messages in the queue, if the message is beyond the current cursor position. For example, the enumerator can automatically access a lower-priority message placed beyond the cursor's current position, but not a higher-priority message inserted before that position. However, you can reset the enumeration, thereby moving the cursor back to the beginning of the list, by calling for the . - - The order of the messages in the enumeration reflects their order in the queue, so higher-priority messages will appear before lower-priority ones. - - If you want a static snapshot of the messages in the queue rather than a dynamic connection to them, call . This method returns an array of objects, which represent the messages at the time the method was called. - - The following table shows whether this method is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|Yes| -|Remote computer and direct format name|Yes| - + creates a dynamic list of all the messages in a queue. You can remove from the queue the message at the enumerator's current position by calling for the that returns. + + Because the cursor is associated with the dynamic list of messages in the queue, the enumeration reflects any modification you make to the messages in the queue, if the message is beyond the current cursor position. For example, the enumerator can automatically access a lower-priority message placed beyond the cursor's current position, but not a higher-priority message inserted before that position. However, you can reset the enumeration, thereby moving the cursor back to the beginning of the list, by calling for the . + + The order of the messages in the enumeration reflects their order in the queue, so higher-priority messages will appear before lower-priority ones. + + If you want a static snapshot of the messages in the queue rather than a dynamic connection to them, call . This method returns an array of objects, which represent the messages at the time the method was called. + + The following table shows whether this method is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|Yes| +|Remote computer and direct format name|Yes| + ]]> @@ -3023,40 +3023,40 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. Provides forward-only cursor semantics to enumerate through all public queues on the network. A that provides a dynamic listing of all the public message queues on the network. - returns an enumeration of all the public queues that are on the network. - - Because the cursor is associated with a dynamic listing, the enumeration reflects any modification you make to a queue list for queues deleted or added beyond the cursor's current position. Additions or deletion of queues located before the cursor's current position are not reflected. For example, the enumerator can automatically access a queue appended beyond the cursor position but not one inserted before that position. However, you can reset the enumeration, thereby moving the cursor back to the beginning of the list, by calling for the . - - There is no defined ordering of queues in a network. An enumerator does not order them, for example, by computer, label, public or private status, or any other accessible criteria. - - If you want a static snapshot of the queues on the network rather than a dynamic connection to them, call or . Each of these two methods returns an array of objects, which represent the queues at the time the method was called. - - The following table shows whether this method is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|No| -|Local computer and direct format name|No| -|Remote computer|No| -|Remote computer and direct format name|No| - - - -## Examples - The following code example iterates through all the message queues in the network, and examines the path for each queue. Finally, it displays the number of public queues on the network. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue.GetMessageQueueEnumerator_noparms/CPP/mqgetmessagequeueenumerator.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetMessageQueueEnumerator/mqgetmessagequeueenumerator.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.GetMessageQueueEnumerator_noparms/VB/mqgetmessagequeueenumerator.vb" id="Snippet1"::: - - ]]> - - - -
+ returns an enumeration of all the public queues that are on the network. + + Because the cursor is associated with a dynamic listing, the enumeration reflects any modification you make to a queue list for queues deleted or added beyond the cursor's current position. Additions or deletion of queues located before the cursor's current position are not reflected. For example, the enumerator can automatically access a queue appended beyond the cursor position but not one inserted before that position. However, you can reset the enumeration, thereby moving the cursor back to the beginning of the list, by calling for the . + + There is no defined ordering of queues in a network. An enumerator does not order them, for example, by computer, label, public or private status, or any other accessible criteria. + + If you want a static snapshot of the queues on the network rather than a dynamic connection to them, call or . Each of these two methods returns an array of objects, which represent the queues at the time the method was called. + + The following table shows whether this method is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|No| +|Local computer and direct format name|No| +|Remote computer|No| +|Remote computer and direct format name|No| + + + +## Examples + The following code example iterates through all the message queues in the network, and examines the path for each queue. Finally, it displays the number of public queues on the network. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue.GetMessageQueueEnumerator_noparms/CPP/mqgetmessagequeueenumerator.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetMessageQueueEnumerator/mqgetmessagequeueenumerator.cs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.GetMessageQueueEnumerator_noparms/VB/mqgetmessagequeueenumerator.vb" id="Snippet1"::: + + ]]> +
+ + +
@@ -3083,35 +3083,35 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. Provides forward-only cursor semantics to enumerate through all public queues on the network that meet the specified criteria. A that provides a dynamic listing of the public message queues on the network that satisfy the restrictions specified by the parameter. - returns a listing of all the public queues on the network that satisfy criteria defined in the application criteria. You can specify the criteria to include, for example, queue creation or modification time, computer name, label, category, or any combination of these. - - Because the cursor is associated with a dynamic listing, the enumeration reflects any modification you make to a queue that occurs beyond the cursor's current position. Changes to queues located before the cursor's current position are not reflected. For example, the enumerator can automatically access a queue appended beyond the cursor position but not one inserted before that position. However, you can reset the enumeration, thereby moving the cursor back to the beginning of the list, by calling for the . - - There is no defined ordering of queues in a network. An enumerator does not order them, for example, by computer, label, public or private status, or any other accessible criteria. - - If you want a static snapshot of the queues on the network rather than a dynamic connection to them, specify criteria for or call . Each of these two methods returns an array of objects, which represent the queues at the time the method was called. Calling , , or provides the same results as calling with the filtering criteria of , , and , respectively. - - The following table shows whether this method is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|No| -|Local computer and direct format name|No| -|Remote computer|No| -|Remote computer and direct format name|No| - - - -## Examples - The following code example iterates through message queues and displays the path of each queue that was created in the last day and that exists on the computer "MyComputer". - + returns a listing of all the public queues on the network that satisfy criteria defined in the application criteria. You can specify the criteria to include, for example, queue creation or modification time, computer name, label, category, or any combination of these. + + Because the cursor is associated with a dynamic listing, the enumeration reflects any modification you make to a queue that occurs beyond the cursor's current position. Changes to queues located before the cursor's current position are not reflected. For example, the enumerator can automatically access a queue appended beyond the cursor position but not one inserted before that position. However, you can reset the enumeration, thereby moving the cursor back to the beginning of the list, by calling for the . + + There is no defined ordering of queues in a network. An enumerator does not order them, for example, by computer, label, public or private status, or any other accessible criteria. + + If you want a static snapshot of the queues on the network rather than a dynamic connection to them, specify criteria for or call . Each of these two methods returns an array of objects, which represent the queues at the time the method was called. Calling , , or provides the same results as calling with the filtering criteria of , , and , respectively. + + The following table shows whether this method is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|No| +|Local computer and direct format name|No| +|Remote computer|No| +|Remote computer and direct format name|No| + + + +## Examples + The following code example iterates through message queues and displays the path of each queue that was created in the last day and that exists on the computer "MyComputer". + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue.GetMessageQueueEnumerator_criteria/CPP/mqgetmessagequeueenumerator_criteria.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetMessageQueueEnumerator/mqgetmessagequeueenumerator_criteria.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.GetMessageQueueEnumerator_criteria/VB/mqgetmessagequeueenumerator_criteria.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.GetMessageQueueEnumerator_criteria/VB/mqgetmessagequeueenumerator_criteria.vb" id="Snippet1"::: + ]]> @@ -3143,29 +3143,29 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. Retrieves all the private queues on the specified computer. An array of objects that reference the retrieved private queues. - retrieves a static snapshot of the queues on a specified computer. - - The following table shows whether this method is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|Yes| -|Remote computer and direct format name|Yes| - - - -## Examples - The following code example retrieves lists of queues. - + retrieves a static snapshot of the queues on a specified computer. + + The following table shows whether this method is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|Yes| +|Remote computer and direct format name|Yes| + + + +## Examples + The following code example retrieves lists of queues. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue.GetQueueLists/CPP/mqgetqueuelists.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetPrivateQueuesByMachine/mqgetqueuelists.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.GetQueueLists/VB/mqgetqueuelists.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.GetQueueLists/VB/mqgetqueuelists.vb" id="Snippet1"::: + ]]> The parameter is or an empty string (""). @@ -3206,31 +3206,31 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. Retrieves all the public queues on the network. An array of objects that reference the retrieved public queues. - , , or last modified time use another overload of this method. (Alternatively, you can use , , or .) - - retrieves a static snapshot of the queues. To interact with a dynamic list of the queues, use . - - The following table shows whether this method is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|No| -|Local computer and direct format name|No| -|Remote computer|No| -|Remote computer and direct format name|No| - - - -## Examples - The following code example retrieves lists of queues. - + , , or last modified time use another overload of this method. (Alternatively, you can use , , or .) + + retrieves a static snapshot of the queues. To interact with a dynamic list of the queues, use . + + The following table shows whether this method is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|No| +|Local computer and direct format name|No| +|Remote computer|No| +|Remote computer and direct format name|No| + + + +## Examples + The following code example retrieves lists of queues. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue.GetQueueLists/CPP/mqgetqueuelists.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetPrivateQueuesByMachine/mqgetqueuelists.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.GetQueueLists/VB/mqgetqueuelists.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.GetQueueLists/VB/mqgetqueuelists.vb" id="Snippet1"::: + ]]> An error occurred when accessing a Message Queuing method. @@ -3262,31 +3262,31 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. Retrieves all the public queues on the network that meet the specified criteria. An array of objects that reference the retrieved public queues. - class contains specific methods that provide that functionality (, , and , respectively). Use this overload to get a list of all the public queues on the network that meet more than one of these criteria (for example, if you want to specify both a label and a category). You can also filter by message criteria other than , , and . For example, you use this overload to filter by a queue's last-modified time. Simply create a new instance of the class, set the appropriate properties in the instance, and pass the instance as the `criteria` parameter. - - retrieves a static snapshot of the queues. To interact with a dynamic list of the queues, use . - - The following table shows whether this method is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|No| -|Local computer and direct format name|No| -|Remote computer|No| -|Remote computer and direct format name|No| - - - -## Examples - The following code example retrieves lists of queues. - + class contains specific methods that provide that functionality (, , and , respectively). Use this overload to get a list of all the public queues on the network that meet more than one of these criteria (for example, if you want to specify both a label and a category). You can also filter by message criteria other than , , and . For example, you use this overload to filter by a queue's last-modified time. Simply create a new instance of the class, set the appropriate properties in the instance, and pass the instance as the `criteria` parameter. + + retrieves a static snapshot of the queues. To interact with a dynamic list of the queues, use . + + The following table shows whether this method is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|No| +|Local computer and direct format name|No| +|Remote computer|No| +|Remote computer and direct format name|No| + + + +## Examples + The following code example retrieves lists of queues. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue.GetQueueLists/CPP/mqgetqueuelists.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetPrivateQueuesByMachine/mqgetqueuelists.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.GetQueueLists/VB/mqgetqueuelists.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.GetQueueLists/VB/mqgetqueuelists.vb" id="Snippet1"::: + ]]> An error occurred when accessing a Message Queuing method. @@ -3319,31 +3319,31 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. Retrieves all the public queues on the network that belong to the specified category. An array of objects that reference the retrieved public queues. - property provides access to the Message Queuing type ID property (which is read/write) of a particular queue. Although you can use to create a category value that is unique across all values, it is not necessary. The category value needs to be distinct only from other categories, not from all other values. For example, you can assign {00000000-0000-0000-0000-000000000001} as the for one set of queues and {00000000-0000-0000-0000-000000000002} as the for another set. - - retrieves a static snapshot of the queues. To interact with a dynamic list of the queues, use . You can specify the category as part of the you pass into the method. - - The following table shows whether this method is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|No| -|Local computer and direct format name|No| -|Remote computer|No| -|Remote computer and direct format name|No| - - - -## Examples - The following code example retrieves lists of queues. - + property provides access to the Message Queuing type ID property (which is read/write) of a particular queue. Although you can use to create a category value that is unique across all values, it is not necessary. The category value needs to be distinct only from other categories, not from all other values. For example, you can assign {00000000-0000-0000-0000-000000000001} as the for one set of queues and {00000000-0000-0000-0000-000000000002} as the for another set. + + retrieves a static snapshot of the queues. To interact with a dynamic list of the queues, use . You can specify the category as part of the you pass into the method. + + The following table shows whether this method is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|No| +|Local computer and direct format name|No| +|Remote computer|No| +|Remote computer and direct format name|No| + + + +## Examples + The following code example retrieves lists of queues. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue.GetQueueLists/CPP/mqgetqueuelists.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetPrivateQueuesByMachine/mqgetqueuelists.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.GetQueueLists/VB/mqgetqueuelists.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.GetQueueLists/VB/mqgetqueuelists.vb" id="Snippet1"::: + ]]> An error occurred when accessing a Message Queuing method. @@ -3377,31 +3377,31 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. Retrieves all the public queues on the network that carry the specified label. An array of objects that reference the retrieved public queues. - retrieves a static snapshot of the queues. To interact with a dynamic list of the queues, use . You can specify the label as part of the you pass into the method. - - The following table shows whether this method is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|No| -|Local computer and direct format name|No| -|Remote computer|No| -|Remote computer and direct format name|No| - - - -## Examples - The following code example retrieves lists of queues. - + retrieves a static snapshot of the queues. To interact with a dynamic list of the queues, use . You can specify the label as part of the you pass into the method. + + The following table shows whether this method is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|No| +|Local computer and direct format name|No| +|Remote computer|No| +|Remote computer and direct format name|No| + + + +## Examples + The following code example retrieves lists of queues. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue.GetQueueLists/CPP/mqgetqueuelists.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetPrivateQueuesByMachine/mqgetqueuelists.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.GetQueueLists/VB/mqgetqueuelists.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.GetQueueLists/VB/mqgetqueuelists.vb" id="Snippet1"::: + ]]> An error occurred when accessing a Message Queuing method. @@ -3436,31 +3436,31 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. Retrieves all the public queues that reside on the specified computer. An array of objects that reference the public queues on the computer. - retrieves a static snapshot of the queues. To interact with a dynamic list of the queues, use . You can specify the computer name as part of the you pass into the method. - - The following table shows whether this method is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|No| -|Local computer and direct format name|No| -|Remote computer|No| -|Remote computer and direct format name|No| - - - -## Examples - The following code example retrieves lists of queues. - + retrieves a static snapshot of the queues. To interact with a dynamic list of the queues, use . You can specify the computer name as part of the you pass into the method. + + The following table shows whether this method is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|No| +|Local computer and direct format name|No| +|Remote computer|No| +|Remote computer and direct format name|No| + + + +## Examples + The following code example retrieves lists of queues. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue.GetQueueLists/CPP/mqgetqueuelists.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetPrivateQueuesByMachine/mqgetqueuelists.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.GetQueueLists/VB/mqgetqueuelists.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.GetQueueLists/VB/mqgetqueuelists.vb" id="Snippet1"::: + ]]> The parameter has incorrect syntax. @@ -3525,27 +3525,27 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. Gets the unique Message Queuing identifier of the queue. A that represents the message identifier generated by the Message Queuing application. - property when it creates the queue. This property is only available for public queues. - - The following table shows whether this property is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|No| -|Remote computer and direct format name|No| - - - -## Examples - The following code example displays the value of a message queue's property. - - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/.ctor/class1.cs" id="Snippet15"::: - + property when it creates the queue. This property is only available for public queues. + + The following table shows whether this property is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|No| +|Remote computer and direct format name|No| + + + +## Examples + The following code example displays the value of a message queue's property. + + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/.ctor/class1.cs" id="Snippet15"::: + ]]> An error occurred when accessing a Message Queuing method. @@ -3572,18 +3572,18 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. Specifies that no size restriction exists for a queue. - or . - - - -## Examples - The following code example demonstrates the use of the member. - - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/.ctor/class1.cs" id="Snippet16"::: - + or . + + + +## Examples + The following code example demonstrates the use of the member. + + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/.ctor/class1.cs" id="Snippet16"::: + ]]> @@ -3610,18 +3610,18 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. Specifies that no time-out exists for methods that peek or receive messages. - supports two types of message retrieval: synchronous and asynchronous. The synchronous methods, and , cause the process thread to wait a specified time interval for a new message to arrive in the queue. If the specified time interval is , the process thread remains blocked until a new message is available. On the other hand, and (the asynchronous methods), allow the main application tasks to continue in a separate thread until a message arrives in the queue. - - - -## Examples - The following code example demonstrates the use of the member. - - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/.ctor/class1.cs" id="Snippet17"::: - + supports two types of message retrieval: synchronous and asynchronous. The synchronous methods, and , cause the process thread to wait a specified time interval for a new message to arrive in the queue. If the specified time interval is , the process thread remains blocked until a new message is available. On the other hand, and (the asynchronous methods), allow the main application tasks to continue in a separate thread until a message arrives in the queue. + + + +## Examples + The following code example demonstrates the use of the member. + + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/.ctor/class1.cs" id="Snippet17"::: + ]]> @@ -3661,29 +3661,29 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. Gets or sets the queue description. The label for the message queue. The default is an empty string (""). - property does not need to be unique across all queues. However, if multiple queues share the same , you cannot use the method to broadcast a message to all of them. If you use the label syntax for the property when you send the message, an exception will be thrown if the is not unique. - - The following table shows whether this property is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|No| -|Remote computer and direct format name|No| - - - -## Examples - The following code example gets and sets the value of a message queue's property. - - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/.ctor/class1.cs" id="Snippet18"::: - + property does not need to be unique across all queues. However, if multiple queues share the same , you cannot use the method to broadcast a message to all of them. If you use the label syntax for the property when you send the message, an exception will be thrown if the is not unique. + + The following table shows whether this property is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|No| +|Remote computer and direct format name|No| + + + +## Examples + The following code example gets and sets the value of a message queue's property. + + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/.ctor/class1.cs" id="Snippet18"::: + ]]> The label was set to an invalid value. @@ -3725,29 +3725,29 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. Gets the last time the properties of a queue were modified. A that indicates when the queue properties were last modified. - property that modifies the Message Queuing queue, such as . The value of the property represents the system time of the local computer. - - You must call before getting the property; otherwise, the modification time associated with this might not be current. - - The following table shows whether this property is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|No| -|Remote computer and direct format name|No| - - - -## Examples - The following code example displays the value of a message queue's property. - - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/.ctor/class1.cs" id="Snippet19"::: - + property that modifies the Message Queuing queue, such as . The value of the property represents the system time of the local computer. + + You must call before getting the property; otherwise, the modification time associated with this might not be current. + + The following table shows whether this property is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|No| +|Remote computer and direct format name|No| + + + +## Examples + The following code example displays the value of a message queue's property. + + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/.ctor/class1.cs" id="Snippet19"::: + ]]> An error occurred when accessing a Message Queuing method. @@ -3790,45 +3790,45 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. Gets or sets the name of the computer where the Message Queuing queue is located. The name of the computer where the queue is located. The Message Queuing default is ".", the local computer. - is an integral component of the friendly name syntax of the queue . The following table shows the syntax you should use for a queue of a specified type when you want to identify the queue path using its friendly name. - -|Queue type|Syntax| -|----------------|------------| -|Public queue|`MachineName`\\`QueueName`| -|Private queue|`MachineName`\\`Private$`\\`QueueName`| -|Journal queue|`MachineName`\\`QueueName`\\`Journal$`| -|Machine journal queue|`MachineName`\\`Journal$`| -|Machine dead-letter queue|`MachineName`\\`Deadletter$`| -|Machine transactional dead-letter queue|`MachineName`\\`XactDeadletter$`| - - Use "." for the local computer when specifying the . Only the computer name is recognized for this property, for example, `Server0`. The property does not support the IP address format. - - If you define the in terms of the , the application throws an exception when working offline because the domain controller is required for path translation. Therefore, you must use the for the syntax when working offline. - - The , , and properties are related. Changing the property causes the property to change. It is built from the new and the . Changing the (for example, to use the format name syntax) resets the and properties to refer to the new queue. If the property is empty, the is set to the Journal queue of the computer you specify. - - The following table shows whether this property is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|Yes| -|Remote computer and direct format name|No| - - - -## Examples - The following code example gets and sets the value of a message queue's property. - - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/.ctor/class1.cs" id="Snippet20"::: - + is an integral component of the friendly name syntax of the queue . The following table shows the syntax you should use for a queue of a specified type when you want to identify the queue path using its friendly name. + +|Queue type|Syntax| +|----------------|------------| +|Public queue|`MachineName`\\`QueueName`| +|Private queue|`MachineName`\\`Private$`\\`QueueName`| +|Journal queue|`MachineName`\\`QueueName`\\`Journal$`| +|Machine journal queue|`MachineName`\\`Journal$`| +|Machine dead-letter queue|`MachineName`\\`Deadletter$`| +|Machine transactional dead-letter queue|`MachineName`\\`XactDeadletter$`| + + Use "." for the local computer when specifying the . Only the computer name is recognized for this property, for example, `Server0`. The property does not support the IP address format. + + If you define the in terms of the , the application throws an exception when working offline because the domain controller is required for path translation. Therefore, you must use the for the syntax when working offline. + + The , , and properties are related. Changing the property causes the property to change. It is built from the new and the . Changing the (for example, to use the format name syntax) resets the and properties to refer to the new queue. If the property is empty, the is set to the Journal queue of the computer you specify. + + The following table shows whether this property is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|Yes| +|Remote computer and direct format name|No| + + + +## Examples + The following code example gets and sets the value of a message queue's property. + + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/.ctor/class1.cs" id="Snippet20"::: + ]]> - The is . + The is . -or- The name of the computer is not valid, possibly because the syntax is incorrect. @@ -3875,29 +3875,29 @@ The name of the computer is not valid, possibly because the syntax is incorrect. Gets or sets the maximum size of the journal queue. The maximum size, in kilobytes, of the journal queue. The Message Queuing default specifies that no limit exists. - provides access to the Message Queuing journal storage limit. It is relevant only when is `true`. Setting this property modifies the Message Queuing queue. Therefore, any other instances are affected by the change - - If you store messages in a journal or dead-letter queue, you should periodically clear the queue to remove messages that are no longer needed. Messages in such a queue count toward the message quota for the computer where the queue resides. (The administrator sets the computer quota.) - - The following table shows whether this property is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|No| -|Remote computer and direct format name|No| - - - -## Examples - The following code example gets and sets the value of a message queue's property. - - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/.ctor/class1.cs" id="Snippet21"::: - + provides access to the Message Queuing journal storage limit. It is relevant only when is `true`. Setting this property modifies the Message Queuing queue. Therefore, any other instances are affected by the change + + If you store messages in a journal or dead-letter queue, you should periodically clear the queue to remove messages that are no longer needed. Messages in such a queue count toward the message quota for the computer where the queue resides. (The administrator sets the computer quota.) + + The following table shows whether this property is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|No| +|Remote computer and direct format name|No| + + + +## Examples + The following code example gets and sets the value of a message queue's property. + + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/.ctor/class1.cs" id="Snippet21"::: + ]]> The maximum journal queue size was set to an invalid value. @@ -3942,31 +3942,31 @@ The name of the computer is not valid, possibly because the syntax is incorrect. Gets or sets the maximum size of the queue. The maximum size, in kilobytes, of the queue. The Message Queuing default specifies that no limit exists. - provides access to the Message Queuing message storage limit, which is separate from the computer's message quota that the administrator defines. For more information about the message quota, see . - - Setting this property modifies the Message Queuing queue. Therefore, any other instances are affected by the change - - If an attempt is made to exceed either the maximum queue size or the computer message quota, messages might be lost. When the queue quota is reached, Message Queuing notifies the administration queue of the sending application to indicate that the queue is full, by returning a negative acknowledgment message. Message Queuing continues to send negative acknowledgments until the total size of the messages in the queue drops below the limit. - - The following table shows whether this property is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|No| -|Remote computer and direct format name|No| - - - -## Examples - The following code example gets and sets the value of a message queue's property. - - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/.ctor/class1.cs" id="Snippet22"::: - + provides access to the Message Queuing message storage limit, which is separate from the computer's message quota that the administrator defines. For more information about the message quota, see . + + Setting this property modifies the Message Queuing queue. Therefore, any other instances are affected by the change + + If an attempt is made to exceed either the maximum queue size or the computer message quota, messages might be lost. When the queue quota is reached, Message Queuing notifies the administration queue of the sending application to indicate that the queue is full, by returning a negative acknowledgment message. Message Queuing continues to send negative acknowledgments until the total size of the messages in the queue drops below the limit. + + The following table shows whether this property is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|No| +|Remote computer and direct format name|No| + + + +## Examples + The following code example gets and sets the value of a message queue's property. + + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/.ctor/class1.cs" id="Snippet22"::: + ]]> The maximum queue size contains a negative value. @@ -4010,77 +4010,77 @@ The name of the computer is not valid, possibly because the syntax is incorrect. Gets or sets the property filter for receiving or peeking messages. The used by the queue to filter the set of properties it receives or peeks for each message. - receives or peeks. When the receives or peeks a message from the server queue, it retrieves only those properties for which the value is `true`. - - The following shows initial property values for the property. These settings are identical to calling on a . - -|Property|Default value| -|--------------|-------------------| -||`false`| -||`false`| -||`true`| -||`false`| -||`true`| -||`false`| -||`false`| -||`false`| -||`false`| -||`true`| -||`false`| -||`true`| -||1024 bytes| -||255 bytes| -||255 bytes| -||`false`| -||`false`| -||`false`| -||`false`| -||`false`| -||`false`| -||`true`| -||`false`| -||`false`| -||`true`| -||`false`| -||`false`| -||`false`| -||`true`| -||`false`| -||`false`| -||`false`| -||`true`| -||`false`| -||`false`| -||`false`| -||`false`| -||`false`| -||`false`| -||`false`| -||`false`| -||`false`| -||`false`| - - The following table shows whether this property is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|Yes| -|Remote computer and direct format name|Yes| - - - -## Examples - The following code example uses the to restrict the message properties received. - + receives or peeks. When the receives or peeks a message from the server queue, it retrieves only those properties for which the value is `true`. + + The following shows initial property values for the property. These settings are identical to calling on a . + +|Property|Default value| +|--------------|-------------------| +||`false`| +||`false`| +||`true`| +||`false`| +||`true`| +||`false`| +||`false`| +||`false`| +||`false`| +||`true`| +||`false`| +||`true`| +||1024 bytes| +||255 bytes| +||255 bytes| +||`false`| +||`false`| +||`false`| +||`false`| +||`false`| +||`false`| +||`true`| +||`false`| +||`false`| +||`true`| +||`false`| +||`false`| +||`false`| +||`true`| +||`false`| +||`false`| +||`false`| +||`true`| +||`false`| +||`false`| +||`false`| +||`false`| +||`false`| +||`false`| +||`false`| +||`false`| +||`false`| +||`false`| + + The following table shows whether this property is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|Yes| +|Remote computer and direct format name|Yes| + + + +## Examples + The following code example uses the to restrict the message properties received. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue.MessageReadPropertyFilter/CPP/mqmessagereadpropertyfilter.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/MessageReadPropertyFilter/mqmessagereadpropertyfilter.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.MessageReadPropertyFilter/VB/mqmessagereadpropertyfilter.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.MessageReadPropertyFilter/VB/mqmessagereadpropertyfilter.vb" id="Snippet1"::: + ]]> The filter is . @@ -4122,33 +4122,33 @@ The name of the computer is not valid, possibly because the syntax is incorrect. Introduced in MSMQ 3.0. Gets or sets the multicast address associated with the queue. - A that contains a valid multicast address (in the form shown below) or , which indicates that the queue is not associated with a multicast address. - -``` -<address>:<port> + A that contains a valid multicast address (in the form shown below) or , which indicates that the queue is not associated with a multicast address. + +``` +<address>:<port> ``` - property is used to associate a non-transactional queue with a multicast address that can be used when sending messages. You cannot associate a transactional queue with a multicast address. When the sending application sends messages to a multicast address, Message Queuing sends a copy of the message to every queue associated with that address. - - IP multicast addresses must be in the class D range from 224.0.0.0 to 239.255.255.255, which corresponds to setting the first four high-order bits equal to 1110. However, only certain ranges of addresses in this range are unreserved and available for sending multicast messages. For the latest list of reserved multicast addresses, see the [Internet Assigned Number Authority (IANA) Internet Multicast Addresses](https://go.microsoft.com/fwlink/?linkid=3859) Web page. There are no restrictions on the port number. - - If several source computers are sending multicast messages and you want a specific queue to receive messages from only one source computer, each source computer must send messages to a different combination of IP address and port number. - - To dissociate a queue from a multicast address, set the property to a zero-length string. Do not set it to `null`, as this will result in a . - - The following table shows whether this property is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|No| -|Remote computer and direct format name|No| - + property is used to associate a non-transactional queue with a multicast address that can be used when sending messages. You cannot associate a transactional queue with a multicast address. When the sending application sends messages to a multicast address, Message Queuing sends a copy of the message to every queue associated with that address. + + IP multicast addresses must be in the class D range from 224.0.0.0 to 239.255.255.255, which corresponds to setting the first four high-order bits equal to 1110. However, only certain ranges of addresses in this range are unreserved and available for sending multicast messages. For the latest list of reserved multicast addresses, see the [Internet Assigned Number Authority (IANA) Internet Multicast Addresses](https://go.microsoft.com/fwlink/?linkid=3859) Web page. There are no restrictions on the port number. + + If several source computers are sending multicast messages and you want a specific queue to receive messages from only one source computer, each source computer must send messages to a different combination of IP address and port number. + + To dissociate a queue from a multicast address, set the property to a zero-length string. Do not set it to `null`, as this will result in a . + + The following table shows whether this property is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|No| +|Remote computer and direct format name|No| + ]]> MSMQ 3.0 is not installed. @@ -4225,58 +4225,58 @@ The name of the computer is not valid, possibly because the syntax is incorrect. Gets or sets the queue's path. Setting the causes the to point to a new queue. The queue that is referenced by the . The default depends on which constructor you use; it is either or is specified by the constructor's parameter. - property depends on the type of queue it points to, as shown in the following table. - -|Queue type|Syntax| -|----------------|------------| -|Public queue|`MachineName`\\`QueueName`| -|Private queue|`MachineName`\\`Private$`\\`QueueName`| -|Journal queue|`MachineName`\\`QueueName`\\`Journal$`| -|Machine journal queue|`MachineName`\\`Journal$`| -|Machine dead-letter queue|`MachineName`\\`Deadletter$`| -|Machine transactional dead-letter queue|`MachineName`\\`XactDeadletter$`| - - Use "." to represent the local computer. - - The , , and properties are related. Changing the property causes the property to change. It is built from the new and the . Changing the (for example, to use the format name syntax) resets the and properties to refer to the new queue. - - Alternatively, you can use the or to describe the queue path, as shown in the following table. - -|Reference|Syntax|Example| -|---------------|------------|-------------| -|Format name|`FormatName:` [ *format name* ]|`FormatName:Public=` 5A5F7535-AE9A-41d4-935C-845C2AFF7112| -|Label|`Label:` [ *label* ]|`Label:` TheLabel| - - If you use the label syntax for the property when you send the message, an exception will be thrown if the is not unique. - - To work offline, you must use the format name syntax, rather than the friendly name syntax in the first table. Otherwise, an exception is thrown because the primary domain controller (on which Active Directory resides) is not available to resolve the path to the format name. - - Setting a new path closes the message queue and releases all handles. - - The following table shows whether this property is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|Yes| -|Remote computer and direct format name|Yes| - + property depends on the type of queue it points to, as shown in the following table. + +|Queue type|Syntax| +|----------------|------------| +|Public queue|`MachineName`\\`QueueName`| +|Private queue|`MachineName`\\`Private$`\\`QueueName`| +|Journal queue|`MachineName`\\`QueueName`\\`Journal$`| +|Machine journal queue|`MachineName`\\`Journal$`| +|Machine dead-letter queue|`MachineName`\\`Deadletter$`| +|Machine transactional dead-letter queue|`MachineName`\\`XactDeadletter$`| + + Use "." to represent the local computer. + + The , , and properties are related. Changing the property causes the property to change. It is built from the new and the . Changing the (for example, to use the format name syntax) resets the and properties to refer to the new queue. + + Alternatively, you can use the or to describe the queue path, as shown in the following table. + +|Reference|Syntax|Example| +|---------------|------------|-------------| +|Format name|`FormatName:` [ *format name* ]|`FormatName:Public=` 5A5F7535-AE9A-41d4-935C-845C2AFF7112| +|Label|`Label:` [ *label* ]|`Label:` TheLabel| + + If you use the label syntax for the property when you send the message, an exception will be thrown if the is not unique. + + To work offline, you must use the format name syntax, rather than the friendly name syntax in the first table. Otherwise, an exception is thrown because the primary domain controller (on which Active Directory resides) is not available to resolve the path to the format name. + + Setting a new path closes the message queue and releases all handles. + + The following table shows whether this property is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|Yes| +|Remote computer and direct format name|Yes| + > [!NOTE] -> In workgroup mode you can only use private queues. You specify the path using the private queue syntax `MachineName`\\`Private$`\\`QueueName`. - - - -## Examples - The following code example creates new objects using various path name syntax types. In each case, it sends a message to the queue whose path is defined in the constructor. - +> In workgroup mode you can only use private queues. You specify the path using the private queue syntax `MachineName`\\`Private$`\\`QueueName`. + + + +## Examples + The following code example creates new objects using various path name syntax types. In each case, it sends a message to the queue whose path is defined in the constructor. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue.Path/CPP/mqpath.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/Overview/mqpath.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.Path/VB/mqpath.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.Path/VB/mqpath.vb" id="Snippet1"::: + ]]> The path is not valid, possibly because the syntax is not valid. @@ -4320,39 +4320,39 @@ The name of the computer is not valid, possibly because the syntax is incorrect. Returns without removing (peeks) the first message in the queue referenced by this . The method is synchronous, so it blocks the current thread until a message becomes available. The that represents the first message in the queue. - method reads, but does not remove, the first message from the queue. Therefore, repeated calls to return the same message, unless a higher priority message arrives in the queue. The method, on the other hand, both reads and removes the first message from the queue. Repeated calls to , therefore, return different messages. - - Message Queuing orders messages in the queue according to priority and arrival time. A newer message is placed before an older one only if it is of a higher priority. - - Use when it is acceptable for the current thread to be blocked while it waits for a message to arrive in the queue. Because this overload does not specify a time-out, the application might wait indefinitely. If you need the application processing to continue without waiting, use the asynchronous method. Alternatively, you can specify a time-out for a message to arrive in the queue by using the overload of that specifies a time-out. - - The following table shows whether this method is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|No| -|Remote computer and direct format name|Yes| - - - -## Examples - The following examples use the method on a queue. - - In the first example, the application waits until a message becomes available in the queue. Note that the first example does not access the message that arrives; it merely pauses processing until a message arrives. If a message already exists in the queue, it will return immediately. - - In the second example, a message that contains an application-defined `Order` class is sent to the queue, and then peeked from the queue. - + method reads, but does not remove, the first message from the queue. Therefore, repeated calls to return the same message, unless a higher priority message arrives in the queue. The method, on the other hand, both reads and removes the first message from the queue. Repeated calls to , therefore, return different messages. + + Message Queuing orders messages in the queue according to priority and arrival time. A newer message is placed before an older one only if it is of a higher priority. + + Use when it is acceptable for the current thread to be blocked while it waits for a message to arrive in the queue. Because this overload does not specify a time-out, the application might wait indefinitely. If you need the application processing to continue without waiting, use the asynchronous method. Alternatively, you can specify a time-out for a message to arrive in the queue by using the overload of that specifies a time-out. + + The following table shows whether this method is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|No| +|Remote computer and direct format name|Yes| + + + +## Examples + The following examples use the method on a queue. + + In the first example, the application waits until a message becomes available in the queue. Note that the first example does not access the message that arrives; it merely pauses processing until a message arrives. If a message already exists in the queue, it will return immediately. + + In the second example, a message that contains an application-defined `Order` class is sent to the queue, and then peeked from the queue. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue.Peek_noparms/CPP/mqpeek_noparms.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/Peek/mqpeek_noparms.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.Peek_noparms/VB/mqpeek_noparms.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.Peek_noparms/VB/mqpeek_noparms.vb" id="Snippet1"::: + ]]> An error occurred when accessing a Message Queuing method. @@ -4386,35 +4386,35 @@ The name of the computer is not valid, possibly because the syntax is incorrect. Returns without removing (peeks) the first message in the queue referenced by this . The method is synchronous, so it blocks the current thread until a message becomes available or the specified time-out occurs. The that represents the first message in the queue. - method reads, but does not remove, the first message from the queue. Therefore, repeated calls to return the same message, unless a higher priority message arrives in the queue. The method, on the other hand, both reads and removes the first message from the queue. Repeated calls to , therefore, return different messages. - - Message Queuing orders messages in the queue according to priority and arrival time. A newer message is placed before an older one only if it is of a higher priority. - - Use when it is acceptable for the current thread to be blocked while it waits for a message to arrive in the queue. The thread will be blocked up to the specified period of time, or indefinitely if you indicated . If you need the application processing to continue without waiting, use the asynchronous method. - - The following table shows whether this method is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|No| -|Remote computer and direct format name|Yes| - - - -## Examples - The following code example uses the method with a time-out of zero to check whether the queue is empty. - + method reads, but does not remove, the first message from the queue. Therefore, repeated calls to return the same message, unless a higher priority message arrives in the queue. The method, on the other hand, both reads and removes the first message from the queue. Repeated calls to , therefore, return different messages. + + Message Queuing orders messages in the queue according to priority and arrival time. A newer message is placed before an older one only if it is of a higher priority. + + Use when it is acceptable for the current thread to be blocked while it waits for a message to arrive in the queue. The thread will be blocked up to the specified period of time, or indefinitely if you indicated . If you need the application processing to continue without waiting, use the asynchronous method. + + The following table shows whether this method is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|No| +|Remote computer and direct format name|Yes| + + + +## Examples + The following code example uses the method with a time-out of zero to check whether the queue is empty. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue.Peek_timeout/CPP/mqpeek_timeout.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/Peek/mqpeek_timeout.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.Peek_timeout/VB/mqpeek_timeout.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.Peek_timeout/VB/mqpeek_timeout.vb" id="Snippet1"::: + ]]> The value specified for the parameter is not valid, possibly is less than or greater than . @@ -4453,24 +4453,24 @@ The name of the computer is not valid, possibly because the syntax is incorrect. Returns without removing (peeks) the current or next message in the queue, using the specified cursor. The method is synchronous, so it blocks the current thread until a message becomes available or the specified time-out occurs. A that represents a message in the queue. - method reads, but does not remove, a message from the queue. The method, on the other hand, both reads and removes a message from the queue. - - Use when it is acceptable for the current thread to be blocked while it waits for a message to arrive in the queue. The thread is blocked up to the specified period of time, or indefinitely if you indicated . If you need the application processing to continue without waiting, use the asynchronous method. - - The following table shows whether this method is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|No| -|Remote computer and direct format name|Yes| - + method reads, but does not remove, a message from the queue. The method, on the other hand, both reads and removes a message from the queue. + + Use when it is acceptable for the current thread to be blocked while it waits for a message to arrive in the queue. The thread is blocked up to the specified period of time, or indefinitely if you indicated . If you need the application processing to continue without waiting, use the asynchronous method. + + The following table shows whether this method is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|No| +|Remote computer and direct format name|Yes| + ]]> A value other than or was specified for the parameter. @@ -4519,33 +4519,33 @@ The name of the computer is not valid, possibly because the syntax is incorrect. Peeks the message that matches the given correlation identifier and immediately raises an exception if no message with the specified correlation identifier currently exists in the queue. The whose matches the parameter passed in. - for a message whose matches the specified `correlationId` parameter. If no message is found that matches the `correlationID` parameter, an exception is thrown. - - The property is used to tie a message sent to the queue to associated response, report, or acknowledgment messages. - - Two other methods allow you to peek messages in a queue. The method returns the first message in the queue, and the method is used to retrieve a message by specifying its unique identifier. - - The following table shows whether this method is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|No| -|Remote computer and direct format name|Yes| - - - -## Examples - The following code example sends and receives a message that contains an order to and from a queue. It specifically requests a positive acknowledgment when the original message reaches or is retrieved from the queue. - + for a message whose matches the specified `correlationId` parameter. If no message is found that matches the `correlationID` parameter, an exception is thrown. + + The property is used to tie a message sent to the queue to associated response, report, or acknowledgment messages. + + Two other methods allow you to peek messages in a queue. The method returns the first message in the queue, and the method is used to retrieve a message by specifying its unique identifier. + + The following table shows whether this method is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|No| +|Remote computer and direct format name|Yes| + + + +## Examples + The following code example sends and receives a message that contains an order to and from a queue. It specifically requests a positive acknowledgment when the original message reaches or is retrieved from the queue. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/Message.Acknowledgment/CPP/message_acknowledgment.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/AcknowledgeTypes/Overview/message_acknowledgment.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Message.Acknowledgment/VB/message_acknowledgment.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Message.Acknowledgment/VB/message_acknowledgment.vb" id="Snippet1"::: + ]]> The parameter is . @@ -4583,43 +4583,43 @@ The name of the computer is not valid, possibly because the syntax is incorrect. Peeks the message that matches the given correlation identifier and waits until either a message with the specified correlation identifier is available in the queue, or the time-out expires. The whose matches the parameter passed in. - for a message whose matches the specified `correlationId` parameter. If no message is found that matches the `correlationID` parameter, and no new message arrives in the queue within the period specified by the `timeout` parameter, an exception is thrown. - - The `timeout` parameter does not specify the total running time for this method. Rather, it specifies the time to wait for a new message to arrive in the queue. Each time a new message arrives, this method examines the of the new message to see if it matches the `correlationId` parameter. If not, this method starts the time-out period over and waits for another new message to arrive. Therefore, if new messages continue to arrive within the time-out period, it is possible for this method to continue running indefinitely, either until the time-out period expires without any new messages arriving, or until a message arrives whose matches the `correlationId` parameter. - - The property is used to tie a message sent to the queue to associated response, report, or acknowledgment messages. - - Two other methods allow you to peek messages in a queue. The method returns the first message in the queue, and the method is used to retrieve a message by specifying its unique identifier. - - The following table shows whether this method is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|No| -|Remote computer and direct format name|Yes| - - - -## Examples - The following code example demonstrates the use of . - + for a message whose matches the specified `correlationId` parameter. If no message is found that matches the `correlationID` parameter, and no new message arrives in the queue within the period specified by the `timeout` parameter, an exception is thrown. + + The `timeout` parameter does not specify the total running time for this method. Rather, it specifies the time to wait for a new message to arrive in the queue. Each time a new message arrives, this method examines the of the new message to see if it matches the `correlationId` parameter. If not, this method starts the time-out period over and waits for another new message to arrive. Therefore, if new messages continue to arrive within the time-out period, it is possible for this method to continue running indefinitely, either until the time-out period expires without any new messages arriving, or until a message arrives whose matches the `correlationId` parameter. + + The property is used to tie a message sent to the queue to associated response, report, or acknowledgment messages. + + Two other methods allow you to peek messages in a queue. The method returns the first message in the queue, and the method is used to retrieve a message by specifying its unique identifier. + + The following table shows whether this method is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|No| +|Remote computer and direct format name|Yes| + + + +## Examples + The following code example demonstrates the use of . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue2/cpp/class1.cpp" id="Snippet5"::: - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet5"::: - + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet5"::: + ]]> The parameter is . The value specified for the parameter is not valid, possibly is less than or greater than . The message with the specified does not exist in the queue and did not arrive before the time-out expired. - A message did not arrive before the time-out expired. - - -or- - + A message did not arrive before the time-out expired. + + -or- + An error occurred when accessing a Message Queuing method. @@ -4661,30 +4661,30 @@ The name of the computer is not valid, possibly because the syntax is incorrect. Peeks the message whose message identifier matches the parameter. The whose property matches the parameter. - to read, without removing from the queue, a message that has a known message identifier. The identifier of a message is unique across the Message Queuing enterprise, so there will be at most one message in the queue that matches the given `id` parameter. This overload throws an exception if the queue does not currently contain the message. - - Two additional methods allow you to peek messages in a queue: and . The method returns the first message in the queue; returns an acknowledgment, report, or application-generated response message that was created as a result of a message sent to the queue. - - The following table shows whether this method is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|No| -|Remote computer and direct format name|Yes| - - - -## Examples - The following code example demonstrates the use of . - + to read, without removing from the queue, a message that has a known message identifier. The identifier of a message is unique across the Message Queuing enterprise, so there will be at most one message in the queue that matches the given `id` parameter. This overload throws an exception if the queue does not currently contain the message. + + Two additional methods allow you to peek messages in a queue: and . The method returns the first message in the queue; returns an acknowledgment, report, or application-generated response message that was created as a result of a message sent to the queue. + + The following table shows whether this method is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|No| +|Remote computer and direct format name|Yes| + + + +## Examples + The following code example demonstrates the use of . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue2/cpp/class1.cpp" id="Snippet6"::: - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet6"::: - + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet6"::: + ]]> The parameter is . @@ -4722,38 +4722,38 @@ The name of the computer is not valid, possibly because the syntax is incorrect. Peeks the message whose message identifier matches the parameter. Waits until the message appears in the queue or a time-out occurs. The whose property matches the parameter. - to read, without removing from the queue, a message that has a known message identifier. The identifier of a message is unique across the Message Queuing enterprise, so there will be at most one message in the queue that matches the given `id` parameter. This overload throws an exception if the queue does not currently contain the message and a new message does not arrive before the time-out occurs. - - The `timeout` parameter does not specify the total running time for this method. Rather, it specifies the time to wait for a new message to arrive in the queue. Each time a new message arrives, this method examines the of the new message to see if it matches the `id` parameter. If not, this method starts the time-out period over and waits for another new message to arrive. Therefore, if new messages continue to arrive within the time-out period, it is possible for this method to continue running indefinitely, either until the time-out period expires without any new messages arriving, or until a message arrives whose matches the `id` parameter. - - Two additional methods allow you to peek messages in a queue: and . The method returns the first message in the queue; returns an acknowledgment, report, or application-generated response message that was created as a result of a message sent to the queue. - - The following table shows whether this method is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|No| -|Remote computer and direct format name|Yes| - - - -## Examples - The following code example demonstrates the use of . - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue2/cpp/class1.cpp" id="Snippet7"::: - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet7"::: - - ]]> - - The parameter is . - The value specified for the parameter is not valid, possibly is less than or greater than . - The message with the specified does not exist in the queue and did not arrive before the period specified by the parameter expired. - An error occurred when accessing a Message Queuing method. + to read, without removing from the queue, a message that has a known message identifier. The identifier of a message is unique across the Message Queuing enterprise, so there will be at most one message in the queue that matches the given `id` parameter. This overload throws an exception if the queue does not currently contain the message and a new message does not arrive before the time-out occurs. + + The `timeout` parameter does not specify the total running time for this method. Rather, it specifies the time to wait for a new message to arrive in the queue. Each time a new message arrives, this method examines the of the new message to see if it matches the `id` parameter. If not, this method starts the time-out period over and waits for another new message to arrive. Therefore, if new messages continue to arrive within the time-out period, it is possible for this method to continue running indefinitely, either until the time-out period expires without any new messages arriving, or until a message arrives whose matches the `id` parameter. + + Two additional methods allow you to peek messages in a queue: and . The method returns the first message in the queue; returns an acknowledgment, report, or application-generated response message that was created as a result of a message sent to the queue. + + The following table shows whether this method is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|No| +|Remote computer and direct format name|Yes| + + + +## Examples + The following code example demonstrates the use of . + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue2/cpp/class1.cpp" id="Snippet7"::: + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet7"::: + + ]]> + + The parameter is . + The value specified for the parameter is not valid, possibly is less than or greater than . + The message with the specified does not exist in the queue and did not arrive before the period specified by the parameter expired. + An error occurred when accessing a Message Queuing method. @@ -4793,24 +4793,24 @@ The name of the computer is not valid, possibly because the syntax is incorrect. Introduced in MSMQ 3.0. Peeks at the message that matches the given lookup identifier from a non-transactional queue. The whose property matches the parameter passed in. - property of a message is unique to the queue where the message resides, so there will be at most one message in the queue that matches the given `lookupId` parameter. - - To read a message with a specified lookup identifier and remove it from the queue, use the method. - - The following table shows whether this method is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|No| -|Remote computer and direct format name|Yes| - + property of a message is unique to the queue where the message resides, so there will be at most one message in the queue that matches the given `lookupId` parameter. + + To read a message with a specified lookup identifier and remove it from the queue, use the method. + + The following table shows whether this method is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|No| +|Remote computer and direct format name|Yes| + ]]> MSMQ 3.0 is not installed. @@ -4841,39 +4841,39 @@ The name of the computer is not valid, possibly because the syntax is incorrect.
- One of the values, specifying how the message is read in the queue. Specify one of the following: - - : Peeks at the message specified by . - - : Peeks at the message following the message specified by . - - : Peeks at the message preceding the message specified by . - - : Peeks at the first message in the queue. The parameter must be set to 0. - + One of the values, specifying how the message is read in the queue. Specify one of the following: + + : Peeks at the message specified by . + + : Peeks at the message following the message specified by . + + : Peeks at the message preceding the message specified by . + + : Peeks at the first message in the queue. The parameter must be set to 0. + : Peeks at the last message in the queue. The parameter must be set to 0. The of the message to peek at, or 0. 0 is used when accessing the first or last message in the queue. Introduced in MSMQ 3.0. Peeks at a specific message from the queue. The message can be specified by a lookup identifier or by its position at the front or end of the queue. The specified by the and parameters passed in. - property of a message is unique to the queue where the message resides, so there will be at most one message in the queue that matches the given `lookupId` parameter. - - To read a message with a specified identifier and remove it from the queue, use the method. - - The following table shows whether this method is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|No| -|Remote computer and direct format name|Yes| - + property of a message is unique to the queue where the message resides, so there will be at most one message in the queue that matches the given `lookupId` parameter. + + To read a message with a specified identifier and remove it from the queue, use the method. + + The following table shows whether this method is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|No| +|Remote computer and direct format name|Yes| + ]]> MSMQ 3.0 is not installed. @@ -4910,24 +4910,24 @@ The name of the computer is not valid, possibly because the syntax is incorrect. Occurs when a message is read without being removed from the queue. This is a result of the asynchronous operation, . - is used in asynchronous processing to raise the event when a message is available in the queue. - - is used to complete the operation initiated by a call to and peek the message when the event is raised. - - 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 code example creates an event handler named `MyPeekCompleted`, attaches it to the event handler delegate, and calls to initiate an asynchronous peek operation on the queue that is located at the path ".\myQueue". When a event is raised, the example peeks the message and writes its body to the screen. The example then calls again to initiate a new asynchronous peek operation - + is used in asynchronous processing to raise the event when a message is available in the queue. + + is used to complete the operation initiated by a call to and peek the message when the event is raised. + + 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 code example creates an event handler named `MyPeekCompleted`, attaches it to the event handler delegate, and calls to initiate an asynchronous peek operation on the queue that is located at the path ".\myQueue". When a event is raised, the example peeks the message and writes its body to the screen. The example then calls again to initiate a new asynchronous peek operation + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue.BeginPeek_noparms/CPP/mqbeginpeek_noparms.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/BeginPeek/mqbeginpeek_noparms.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.BeginPeek_noparms/VB/mqbeginpeek_noparms.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.BeginPeek_noparms/VB/mqbeginpeek_noparms.vb" id="Snippet1"::: + ]]> @@ -4958,28 +4958,28 @@ The name of the computer is not valid, possibly because the syntax is incorrect. Deletes all the messages contained in the queue. - property. Messages that are purged from the queue are lost; they are not sent to the dead-letter queue or the journal queue. - - The following table shows whether this method is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|No| -|Remote computer and direct format name|Yes| - - - -## Examples - The following code example demonstrates the use of . - + property. Messages that are purged from the queue are lost; they are not sent to the dead-letter queue or the journal queue. + + The following table shows whether this method is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|No| +|Remote computer and direct format name|Yes| + + + +## Examples + The following code example demonstrates the use of . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue2/cpp/class1.cpp" id="Snippet29"::: - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet29"::: - + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet29"::: + ]]> An error occurred when accessing a Message Queuing method. @@ -5022,37 +5022,37 @@ The name of the computer is not valid, possibly because the syntax is incorrect. Gets or sets the friendly name that identifies the queue. The name that identifies the queue referenced by this . The value cannot be . - with the to create a friendly name for the queue. The syntax for the friendly name variation of the property depends on the type of queue, as shown in the following table. - -|Queue type|Syntax| -|----------------|------------| -|Public queue|`MachineName`\\`QueueName`| -|Private queue|`MachineName`\\`Private$`\\`QueueName`| -|Journal queue|`MachineName`\\`QueueName`\\`Journal$`| - - Use "." to represent the local computer. - - Changing the property affects the property. If you set the without setting the property, the property becomes .\\`QueueName`. Otherwise, the becomes `MachineName`\\`QueueName`. - - The following table shows whether this property is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|Yes| -|Remote computer and direct format name|No| - - - -## Examples - The following code example gets and sets the value of a message queue's property. - - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/.ctor/class1.cs" id="Snippet24"::: - + with the to create a friendly name for the queue. The syntax for the friendly name variation of the property depends on the type of queue, as shown in the following table. + +|Queue type|Syntax| +|----------------|------------| +|Public queue|`MachineName`\\`QueueName`| +|Private queue|`MachineName`\\`Private$`\\`QueueName`| +|Journal queue|`MachineName`\\`QueueName`\\`Journal$`| + + Use "." to represent the local computer. + + Changing the property affects the property. If you set the without setting the property, the property becomes .\\`QueueName`. Otherwise, the becomes `MachineName`\\`QueueName`. + + The following table shows whether this property is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|Yes| +|Remote computer and direct format name|No| + + + +## Examples + The following code example gets and sets the value of a message queue's property. + + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/.ctor/class1.cs" id="Snippet24"::: + ]]> The queue name is . @@ -5095,20 +5095,20 @@ The name of the computer is not valid, possibly because the syntax is incorrect. Gets the native handle used to read messages from the message queue. A handle to the native queue object that you use for peeking and receiving messages from the queue. - provides a native Windows handle to the message queue object that is used for peeking and receiving messages from the queue. If you change the path of the queue, the handle is closed and reopened with a new value. - - The following table shows whether this property is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|No| -|Remote computer and direct format name|Yes| - + provides a native Windows handle to the message queue object that is used for peeking and receiving messages from the queue. If you change the path of the queue, the handle is closed and reopened with a new value. + + The following table shows whether this property is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|No| +|Remote computer and direct format name|Yes| + ]]> An error occurred when accessing a Message Queuing method. @@ -5148,35 +5148,35 @@ The name of the computer is not valid, possibly because the syntax is incorrect. Receives the first message available in the queue referenced by the . This call is synchronous, and blocks the current thread of execution until a message is available. A that references the first message available in the queue. - method allows for the synchronous reading of a message, thereby removing it from the queue. Subsequent calls to will return the messages that follow in the queue, or new, higher priority messages. - - To read the first message in a queue without removing it from the queue, use the method. The method always returns the first message in the queue, so subsequent calls to the method return the same message unless a higher priority message arrives in the queue. - - Use a call to when it is acceptable for the current thread to be blocked while it waits for a message to arrive in the queue. Because this overload of the method specifies an infinite time-out, the application might wait indefinitely. If the application processing should continue without waiting for the message, consider using the asynchronous method, . - - The following table shows whether this method is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|No| -|Remote computer and direct format name|Yes| - - - -## Examples - The following code example receives a message from a queue and outputs information about that message to the screen. - + method allows for the synchronous reading of a message, thereby removing it from the queue. Subsequent calls to will return the messages that follow in the queue, or new, higher priority messages. + + To read the first message in a queue without removing it from the queue, use the method. The method always returns the first message in the queue, so subsequent calls to the method return the same message unless a higher priority message arrives in the queue. + + Use a call to when it is acceptable for the current thread to be blocked while it waits for a message to arrive in the queue. Because this overload of the method specifies an infinite time-out, the application might wait indefinitely. If the application processing should continue without waiting for the message, consider using the asynchronous method, . + + The following table shows whether this method is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|No| +|Remote computer and direct format name|Yes| + + + +## Examples + The following code example receives a message from a queue and outputs information about that message to the screen. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue.Receive_noparms/CPP/mqreceive_noparms.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/Overview/mqreceive_noparms.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.Receive_noparms/VB/mqreceive_noparms.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.Receive_noparms/VB/mqreceive_noparms.vb" id="Snippet1"::: + ]]> An error occurred when accessing a Message Queuing method. @@ -5209,43 +5209,43 @@ The name of the computer is not valid, possibly because the syntax is incorrect. Receives the first message available in the transactional queue referenced by the . This call is synchronous, and blocks the current thread of execution until a message is available. A that references the first message available in the queue. - method allows for the synchronous reading of a message, thereby removing it from the queue. Subsequent calls to will return the messages that follow in the queue. - - Because this method is called on a transactional queue, the message that is received would be returned to the queue if the transaction is aborted. The message is not permanently removed from the queue until the transaction is committed. - - To read the first message in a queue without removing it from the queue, use the method. The method always returns the first message in the queue, so subsequent calls to the method return the same message unless a higher priority message arrives in the queue. There is no transaction context associated with a message returned by a call to . Because does not remove any messages in the queue, there would be nothing to roll back by a call to . - - Use a call to when it is acceptable for the current thread to be blocked while it waits for a message to arrive in the queue. Because this overload of the method specifies an infinite time-out, the application might wait indefinitely. If the application processing should continue without waiting for the message, consider using the asynchronous method, . - - The following table shows whether this method is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|No| -|Remote computer and direct format name|Yes| - - - -## Examples - The following code example connects to a transactional queue on the local computer and sends a message to the queue. It then receives the message that contains an order. If it encounters a non-transactional queue, it will throw and exception and rollback the transaction. - + method allows for the synchronous reading of a message, thereby removing it from the queue. Subsequent calls to will return the messages that follow in the queue. + + Because this method is called on a transactional queue, the message that is received would be returned to the queue if the transaction is aborted. The message is not permanently removed from the queue until the transaction is committed. + + To read the first message in a queue without removing it from the queue, use the method. The method always returns the first message in the queue, so subsequent calls to the method return the same message unless a higher priority message arrives in the queue. There is no transaction context associated with a message returned by a call to . Because does not remove any messages in the queue, there would be nothing to roll back by a call to . + + Use a call to when it is acceptable for the current thread to be blocked while it waits for a message to arrive in the queue. Because this overload of the method specifies an infinite time-out, the application might wait indefinitely. If the application processing should continue without waiting for the message, consider using the asynchronous method, . + + The following table shows whether this method is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|No| +|Remote computer and direct format name|Yes| + + + +## Examples + The following code example connects to a transactional queue on the local computer and sends a message to the queue. It then receives the message that contains an order. If it encounters a non-transactional queue, it will throw and exception and rollback the transaction. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue.Receive_transaction/CPP/mqreceive_transaction.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/Receive/mqreceive_transaction.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.Receive_transaction/VB/mqreceive_transaction.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.Receive_transaction/VB/mqreceive_transaction.vb" id="Snippet1"::: + ]]> - An error occurred when accessing a Message Queuing method. - - -or- - + An error occurred when accessing a Message Queuing method. + + -or- + The queue is non-transactional. The method is not thread safe. @@ -5279,38 +5279,38 @@ The name of the computer is not valid, possibly because the syntax is incorrect. Receives the first message available in the queue referenced by the . This call is synchronous, and blocks the current thread of execution until a message is available. A that references the first message available in the queue. - method allows for the synchronous reading of a message, thereby removing it from the queue. Subsequent calls to will return the messages that follow in the queue. - - If this method is called to receive a message from a transactional queue, the message that is received would be returned to the queue if the transaction is aborted. The message is not permanently removed from the queue until the transaction is committed. - - To read the first message in a queue without removing it from the queue, use the method. The method always returns the first message in the queue, so subsequent calls to the method return the same message unless a higher priority message arrives in the queue. There is no transaction context associated with a message returned by a call to . Because does not remove any messages in the queue, there would be nothing to roll back by a call to . - - Use a call to when it is acceptable for the current thread to be blocked while it waits for a message to arrive in the queue. Because this overload of the method specifies an infinite time-out, the application might wait indefinitely. If the application processing should continue without waiting for the message, consider using the asynchronous method, . - - The following table shows whether this method is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|No| -|Remote computer and direct format name|Yes| - - - -## Examples - The following code example demonstrates the use of . - + method allows for the synchronous reading of a message, thereby removing it from the queue. Subsequent calls to will return the messages that follow in the queue. + + If this method is called to receive a message from a transactional queue, the message that is received would be returned to the queue if the transaction is aborted. The message is not permanently removed from the queue until the transaction is committed. + + To read the first message in a queue without removing it from the queue, use the method. The method always returns the first message in the queue, so subsequent calls to the method return the same message unless a higher priority message arrives in the queue. There is no transaction context associated with a message returned by a call to . Because does not remove any messages in the queue, there would be nothing to roll back by a call to . + + Use a call to when it is acceptable for the current thread to be blocked while it waits for a message to arrive in the queue. Because this overload of the method specifies an infinite time-out, the application might wait indefinitely. If the application processing should continue without waiting for the message, consider using the asynchronous method, . + + The following table shows whether this method is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|No| +|Remote computer and direct format name|Yes| + + + +## Examples + The following code example demonstrates the use of . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue2/cpp/class1.cpp" id="Snippet9"::: - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet9"::: - + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet9"::: + ]]> An error occurred when accessing a Message Queuing method. @@ -5347,42 +5347,42 @@ The name of the computer is not valid, possibly because the syntax is incorrect. Receives the first message available in the queue referenced by the and waits until either a message is available in the queue, or the time-out expires. A that references the first message available in the queue. - method allows for the synchronous reading of a message, removing it from the queue. Subsequent calls to will return the messages that follow in the queue, or new, higher priority messages. - - To read the first message in a queue without removing it from the queue, use the method. The method always returns the first message in the queue, so subsequent calls to the method return the same message unless a higher priority message arrives in the queue. - - Use a call to when it is acceptable for the current thread to be blocked while it waits for a message to arrive in the queue. The thread will be blocked for the given period of time, or indefinitely if you specified the value for the `timeout` parameter. If the application processing should continue without waiting for a message, consider using the asynchronous method, . - - The following table shows whether this method is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|No| -|Remote computer and direct format name|Yes| - - - -## Examples - The following code example receives a message from a queue and outputs information about that message to the screen. The example pauses execution for up to five seconds while waiting for a message to arrive in the queue. - + method allows for the synchronous reading of a message, removing it from the queue. Subsequent calls to will return the messages that follow in the queue, or new, higher priority messages. + + To read the first message in a queue without removing it from the queue, use the method. The method always returns the first message in the queue, so subsequent calls to the method return the same message unless a higher priority message arrives in the queue. + + Use a call to when it is acceptable for the current thread to be blocked while it waits for a message to arrive in the queue. The thread will be blocked for the given period of time, or indefinitely if you specified the value for the `timeout` parameter. If the application processing should continue without waiting for a message, consider using the asynchronous method, . + + The following table shows whether this method is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|No| +|Remote computer and direct format name|Yes| + + + +## Examples + The following code example receives a message from a queue and outputs information about that message to the screen. The example pauses execution for up to five seconds while waiting for a message to arrive in the queue. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue.Receive_timeout/CPP/mqreceive_timeout.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/Receive/mqreceive_timeout.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.Receive_timeout/VB/mqreceive_timeout.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.Receive_timeout/VB/mqreceive_timeout.vb" id="Snippet1"::: + ]]> The value specified for the parameter is not valid, possibly is less than or greater than . - A message did not arrive in the queue before the time-out expired. - - -or- - + A message did not arrive in the queue before the time-out expired. + + -or- + An error occurred when accessing a Message Queuing method The method is not thread safe. @@ -5417,12 +5417,12 @@ The name of the computer is not valid, possibly because the syntax is incorrect. A that references the first message available in the queue. To be added. The value specified for the parameter is not valid, possibly is less than or greater than . - A message did not arrive in the queue before the time-out expired. - - -or- - - An error occurred when accessing a Message Queuing method - + A message did not arrive in the queue before the time-out expired. + + -or- + + An error occurred when accessing a Message Queuing method + Use this overload to receive a message and return in a specified period of time if there are no messages in the queue. The method is not thread safe. @@ -5454,48 +5454,48 @@ The name of the computer is not valid, possibly because the syntax is incorrect. Receives the first message available in the transactional queue referenced by the and waits until either a message is available in the queue, or the time-out expires. A that references the first message available in the queue. - method allows for the synchronous reading of a message, thereby removing it from the queue. Subsequent calls to will return the messages that follow in the queue. - - Because this method is called on a transactional queue, the message that is received would be returned to the queue if the transaction is aborted. The message is not permanently removed from the queue until the transaction is committed. - - To read the first message in a queue without removing it from the queue, use the method. The method always returns the first message in the queue, so subsequent calls to the method return the same message unless a higher priority message arrives in the queue. There is no transaction context associated with a message returned by a call to . Because does not remove any messages in the queue, there would be nothing to roll back by a call to . - - Use a call to when it is acceptable for the current thread to be blocked while it waits for a message to arrive in the queue. The thread will be blocked for the given period of time, or indefinitely if you specified the value for the `timeout` parameter. If the application processing should continue without waiting for a message, consider using the asynchronous method, . - - The following table shows whether this method is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|No| -|Remote computer and direct format name|Yes| - - - -## Examples - The following code example demonstrates the use of this method. - + method allows for the synchronous reading of a message, thereby removing it from the queue. Subsequent calls to will return the messages that follow in the queue. + + Because this method is called on a transactional queue, the message that is received would be returned to the queue if the transaction is aborted. The message is not permanently removed from the queue until the transaction is committed. + + To read the first message in a queue without removing it from the queue, use the method. The method always returns the first message in the queue, so subsequent calls to the method return the same message unless a higher priority message arrives in the queue. There is no transaction context associated with a message returned by a call to . Because does not remove any messages in the queue, there would be nothing to roll back by a call to . + + Use a call to when it is acceptable for the current thread to be blocked while it waits for a message to arrive in the queue. The thread will be blocked for the given period of time, or indefinitely if you specified the value for the `timeout` parameter. If the application processing should continue without waiting for a message, consider using the asynchronous method, . + + The following table shows whether this method is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|No| +|Remote computer and direct format name|Yes| + + + +## Examples + The following code example demonstrates the use of this method. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue.Receive_TimeoutTransaction/CPP/mqreceive_timeouttransaction.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/Receive/mqreceive_timeouttransaction.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.Receive_TimeoutTransaction/VB/mqreceive_timeouttransaction.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.Receive_TimeoutTransaction/VB/mqreceive_timeouttransaction.vb" id="Snippet1"::: + ]]> The value specified for the parameter is not valid, possibly is less than or greater than . - A message did not arrive in the queue before the time-out expired. - - -or- - - The queue is non-transactional. - - -or- - + A message did not arrive in the queue before the time-out expired. + + -or- + + The queue is non-transactional. + + -or- + An error occurred when accessing a Message Queuing method. The method is not thread safe. @@ -5532,46 +5532,46 @@ The name of the computer is not valid, possibly because the syntax is incorrect. Receives the first message available in the queue referenced by the . This call is synchronous, and waits until either a message is available in the queue, or the time-out expires. A that references the first message available in the queue. - method allows for the synchronous reading of a message, thereby removing it from the queue. Subsequent calls to will return the messages that follow in the queue. - - If this method is called to receive a message from a transactional queue, the message that is received would be returned to the queue if the transaction is aborted. The message is not permanently removed from the queue until the transaction is committed. - - To read the first message in a queue without removing it from the queue, use the method. The method always returns the first message in the queue, so subsequent calls to the method return the same message unless a higher priority message arrives in the queue. There is no transaction context associated with a message returned by a call to . Because does not remove any messages in the queue, there would be nothing to roll back by a call to . - - Use a call to when it is acceptable for the current thread to be blocked while it waits for a message to arrive in the queue. The thread will be blocked for the given period of time, or indefinitely if you specified the value for the `timeout` parameter. If the application processing should continue without waiting for a message, consider using the asynchronous method, . - - The following table shows whether this method is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|No| -|Remote computer and direct format name|Yes| - - - -## Examples - The following code example demonstrates the use of this method. - + method allows for the synchronous reading of a message, thereby removing it from the queue. Subsequent calls to will return the messages that follow in the queue. + + If this method is called to receive a message from a transactional queue, the message that is received would be returned to the queue if the transaction is aborted. The message is not permanently removed from the queue until the transaction is committed. + + To read the first message in a queue without removing it from the queue, use the method. The method always returns the first message in the queue, so subsequent calls to the method return the same message unless a higher priority message arrives in the queue. There is no transaction context associated with a message returned by a call to . Because does not remove any messages in the queue, there would be nothing to roll back by a call to . + + Use a call to when it is acceptable for the current thread to be blocked while it waits for a message to arrive in the queue. The thread will be blocked for the given period of time, or indefinitely if you specified the value for the `timeout` parameter. If the application processing should continue without waiting for a message, consider using the asynchronous method, . + + The following table shows whether this method is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|No| +|Remote computer and direct format name|Yes| + + + +## Examples + The following code example demonstrates the use of this method. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue2/cpp/class1.cpp" id="Snippet8"::: - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet8"::: - + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet8"::: + ]]> The value specified for the parameter is not valid, possibly is less than or greater than . The parameter is not one of the members. - A message did not arrive in the queue before the time-out expired. - - -or- - + A message did not arrive in the queue before the time-out expired. + + -or- + An error occurred when accessing a Message Queuing method. The method is not thread safe. @@ -5608,44 +5608,44 @@ The name of the computer is not valid, possibly because the syntax is incorrect. Receives the current message in the queue, using a specified cursor. If no message is available, this method waits until either a message is available, or the time-out expires. A that references a message in the queue. - method allows for the synchronous reading of a message, thereby removing it from the queue. Subsequent calls to return the messages that follow in the queue. - - Because this method is called on a transactional queue, the message that is received is returned to the queue if the transaction is aborted. The message is not permanently removed from the queue until the transaction is committed. - - To read a message in a queue without removing it from the queue, use the method. There is no transaction context associated with a message returned by a call to . Because does not remove any messages in the queue, there is nothing to roll back by a call to . - - Use a call to when it is acceptable for the current thread to be blocked while it waits for a message to arrive in the queue. The thread is blocked for the given period of time, or indefinitely if you specified the value for the `timeout` parameter. If the application processing should continue without waiting for a message, consider using the asynchronous method, . - - The following table shows whether this method is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|No| -|Remote computer and direct format name|Yes| - + method allows for the synchronous reading of a message, thereby removing it from the queue. Subsequent calls to return the messages that follow in the queue. + + Because this method is called on a transactional queue, the message that is received is returned to the queue if the transaction is aborted. The message is not permanently removed from the queue until the transaction is committed. + + To read a message in a queue without removing it from the queue, use the method. There is no transaction context associated with a message returned by a call to . Because does not remove any messages in the queue, there is nothing to roll back by a call to . + + Use a call to when it is acceptable for the current thread to be blocked while it waits for a message to arrive in the queue. The thread is blocked for the given period of time, or indefinitely if you specified the value for the `timeout` parameter. If the application processing should continue without waiting for a message, consider using the asynchronous method, . + + The following table shows whether this method is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|No| +|Remote computer and direct format name|Yes| + ]]> - The parameter is . - - -or- - + The parameter is . + + -or- + The parameter is . The value specified for the parameter is not valid. Possibly is less than or greater than . - A message did not arrive in the queue before the time-out expired. - - -or- - - The queue is non-transactional. - - -or- - + A message did not arrive in the queue before the time-out expired. + + -or- + + The queue is non-transactional. + + -or- + An error occurred when accessing a Message Queuing method. The method is not thread safe. @@ -5684,39 +5684,39 @@ The name of the computer is not valid, possibly because the syntax is incorrect. Receives the current message in the queue, using a specified cursor. If no message is available, this method waits until either a message is available, or the time-out expires. A that references a message in the queue. - method allows for the synchronous reading of a message, thereby removing it from the queue. Subsequent calls to return the messages that follow in the queue. - - If this method is called to receive a message from a transactional queue, the message that is received is returned to the queue if the transaction is aborted. The message is not permanently removed from the queue until the transaction is committed. - - To read a message in a queue without removing it from the queue, use the method. There is no transaction context associated with a message returned by a call to . Because does not remove any messages in the queue, there is nothing to roll back by a call to . - - Use a call to when it is acceptable for the current thread to be blocked while it waits for a message to arrive in the queue. The thread is blocked for the given period of time, or indefinitely if you specified the value for the `timeout` parameter. If the application processing should continue without waiting for a message, consider using the asynchronous method, . - - The following table shows whether this method is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|No| -|Remote computer and direct format name|Yes| - + method allows for the synchronous reading of a message, thereby removing it from the queue. Subsequent calls to return the messages that follow in the queue. + + If this method is called to receive a message from a transactional queue, the message that is received is returned to the queue if the transaction is aborted. The message is not permanently removed from the queue until the transaction is committed. + + To read a message in a queue without removing it from the queue, use the method. There is no transaction context associated with a message returned by a call to . Because does not remove any messages in the queue, there is nothing to roll back by a call to . + + Use a call to when it is acceptable for the current thread to be blocked while it waits for a message to arrive in the queue. The thread is blocked for the given period of time, or indefinitely if you specified the value for the `timeout` parameter. If the application processing should continue without waiting for a message, consider using the asynchronous method, . + + The following table shows whether this method is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|No| +|Remote computer and direct format name|Yes| + ]]> The parameter is . The value specified for the parameter is not valid. Possibly is less than or greater than . The parameter is not one of the members. - A message did not arrive in the queue before the time-out expired. - - -or- - + A message did not arrive in the queue before the time-out expired. + + -or- + An error occurred when accessing a Message Queuing method. The method is not thread safe. @@ -5760,35 +5760,35 @@ The name of the computer is not valid, possibly because the syntax is incorrect. Receives the message that matches the given correlation identifier (from a non-transactional queue) and immediately raises an exception if no message with the specified correlation identifier currently exists in the queue. The whose matches the parameter passed in. - for a message whose matches the specified `correlationId` parameter. If no message is found that matches the `correlationID` parameter, an exception is thrown. Otherwise, the message is removed from the queue and returned to the application. - - The property is used to tie a message sent to the queue to associated response, report, or acknowledgment messages. - - Two other methods allow you to receive messages from a queue. The method returns the first message in the queue, and the method retrieves a message by specifying its unique identifier. - - To read a message with a specified correlation identifier without removing it from the queue, use the method. The method always returns the first message in the queue, so subsequent calls to the method return the same message unless a higher priority message arrives in the queue. - - The following table shows whether this method is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|No| -|Remote computer and direct format name|Yes| - - - -## Examples - The following code example sends and receives a message that contains an order to and from a queue. It specifically requests a positive acknowledgment when the original message reaches or is retrieved from the queue. - + for a message whose matches the specified `correlationId` parameter. If no message is found that matches the `correlationID` parameter, an exception is thrown. Otherwise, the message is removed from the queue and returned to the application. + + The property is used to tie a message sent to the queue to associated response, report, or acknowledgment messages. + + Two other methods allow you to receive messages from a queue. The method returns the first message in the queue, and the method retrieves a message by specifying its unique identifier. + + To read a message with a specified correlation identifier without removing it from the queue, use the method. The method always returns the first message in the queue, so subsequent calls to the method return the same message unless a higher priority message arrives in the queue. + + The following table shows whether this method is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|No| +|Remote computer and direct format name|Yes| + + + +## Examples + The following code example sends and receives a message that contains an order to and from a queue. It specifically requests a positive acknowledgment when the original message reaches or is retrieved from the queue. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/Message.Acknowledgment/CPP/message_acknowledgment.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/AcknowledgeTypes/Overview/message_acknowledgment.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Message.Acknowledgment/VB/message_acknowledgment.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Message.Acknowledgment/VB/message_acknowledgment.vb" id="Snippet1"::: + ]]> The parameter is . @@ -5826,48 +5826,48 @@ The name of the computer is not valid, possibly because the syntax is incorrect. Receives the message that matches the given correlation identifier (from a transactional queue) and immediately raises an exception if no message with the specified correlation identifier currently exists in the queue. The whose matches the parameter passed in. - for a message whose matches the specified `correlationId` parameter. If no message is found that matches the `correlationID` parameter, an exception is thrown. Otherwise, the message is removed from the queue and returned to the application using the internal transaction context defined by the `transaction` parameter. - - Because this method is called on a transactional queue, the message that is received would be returned to the queue if the transaction is aborted. The message is not permanently removed from the queue until the transaction is committed. - - The property is used to tie a message sent to the queue to associated response, report, or acknowledgment messages. - - Two other methods allow you to receive messages from a queue. The method returns the first message in the queue, and the method is used to retrieve a message by specifying its unique identifier. - - To read a message with a specified correlation identifier without removing it from the queue, use the method. The method always returns the first message in the queue, so subsequent calls to the method return the same message unless a higher priority message arrives in the queue. There is no transaction context associated with a message returned by a call to . Because does not remove any messages in the queue, there would be nothing to roll back if the transaction were aborted. - - The following table shows whether this method is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|No| -|Remote computer and direct format name|Yes| - - - -## Examples - The following code example demonstrates the use of . - + for a message whose matches the specified `correlationId` parameter. If no message is found that matches the `correlationID` parameter, an exception is thrown. Otherwise, the message is removed from the queue and returned to the application using the internal transaction context defined by the `transaction` parameter. + + Because this method is called on a transactional queue, the message that is received would be returned to the queue if the transaction is aborted. The message is not permanently removed from the queue until the transaction is committed. + + The property is used to tie a message sent to the queue to associated response, report, or acknowledgment messages. + + Two other methods allow you to receive messages from a queue. The method returns the first message in the queue, and the method is used to retrieve a message by specifying its unique identifier. + + To read a message with a specified correlation identifier without removing it from the queue, use the method. The method always returns the first message in the queue, so subsequent calls to the method return the same message unless a higher priority message arrives in the queue. There is no transaction context associated with a message returned by a call to . Because does not remove any messages in the queue, there would be nothing to roll back if the transaction were aborted. + + The following table shows whether this method is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|No| +|Remote computer and direct format name|Yes| + + + +## Examples + The following code example demonstrates the use of . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue2/cpp/class1.cpp" id="Snippet14"::: - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet14"::: - + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet14"::: + ]]> - The parameter is . - - -or- - + The parameter is . + + -or- + The parameter is . The message with the specified could not be found. - The queue is non-transactional. - - -or- - + The queue is non-transactional. + + -or- + An error occurred when accessing a Message Queuing method. @@ -5903,38 +5903,38 @@ The name of the computer is not valid, possibly because the syntax is incorrect. Receives the message that matches the given correlation identifier and immediately raises an exception if no message with the specified correlation identifier currently exists in the queue. The whose matches the parameter passed in. - for a message whose matches the specified `correlationId` parameter. If no message is found that matches the `correlationID` parameter, an exception is thrown. Otherwise, the message is removed from the queue and returned to the application using a transaction context defined by the `transactionType` parameter. - - Specify `Automatic` for the `transactionType` parameter if there is already an external transaction context attached to the thread that you want to use to receive the message. Specify `Single` if you want to receive the message as a single internal transaction. You can specify `None` if you want to receive a message from a transactional queue outside of a transaction context. - - If this method is called to receive a message from a transactional queue, the message that is received would be returned to the queue if the transaction is aborted. The message is not permanently removed from the queue until the transaction is committed. - - The property is used to tie a message sent to the queue to associated response, report, or acknowledgment messages. - - Two other methods allow you to receive messages from a queue. The method returns the first message in the queue, and the method is used to retrieve a message by specifying its unique identifier. - - To read a message with a specified correlation identifier without removing it from the queue, use the method. The method always returns the first message in the queue, so subsequent calls to the method return the same message unless a higher priority message arrives in the queue. There is no transaction context associated with a message returned by a call to . Because does not remove any messages in the queue, there would be nothing to roll back if the transaction were aborted. - - The following table shows whether this method is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|No| -|Remote computer and direct format name|Yes| - - - -## Examples - The following code example demonstrates the use of . - + for a message whose matches the specified `correlationId` parameter. If no message is found that matches the `correlationID` parameter, an exception is thrown. Otherwise, the message is removed from the queue and returned to the application using a transaction context defined by the `transactionType` parameter. + + Specify `Automatic` for the `transactionType` parameter if there is already an external transaction context attached to the thread that you want to use to receive the message. Specify `Single` if you want to receive the message as a single internal transaction. You can specify `None` if you want to receive a message from a transactional queue outside of a transaction context. + + If this method is called to receive a message from a transactional queue, the message that is received would be returned to the queue if the transaction is aborted. The message is not permanently removed from the queue until the transaction is committed. + + The property is used to tie a message sent to the queue to associated response, report, or acknowledgment messages. + + Two other methods allow you to receive messages from a queue. The method returns the first message in the queue, and the method is used to retrieve a message by specifying its unique identifier. + + To read a message with a specified correlation identifier without removing it from the queue, use the method. The method always returns the first message in the queue, so subsequent calls to the method return the same message unless a higher priority message arrives in the queue. There is no transaction context associated with a message returned by a call to . Because does not remove any messages in the queue, there would be nothing to roll back if the transaction were aborted. + + The following table shows whether this method is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|No| +|Remote computer and direct format name|Yes| + + + +## Examples + The following code example demonstrates the use of . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue2/cpp/class1.cpp" id="Snippet11"::: - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet11"::: - + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet11"::: + ]]> The parameter is . @@ -5975,44 +5975,44 @@ The name of the computer is not valid, possibly because the syntax is incorrect. Receives the message that matches the given correlation identifier (from a non-transactional queue) and waits until either a message with the specified correlation identifier is available in the queue, or the time-out expires. The whose matches the parameter passed in. - for a message whose matches the specified `correlationId` parameter. This method returns immediately if the message with the correlation identifier specified by the `correlationId` parameter is in the queue. Otherwise, the method waits the given period of time for a new message to arrive. If a new message does not arrive before the time-out expires, an exception is thrown. - - The `timeout` parameter does not specify the total running time for this method. Rather, it specifies the time to wait for a new message to arrive in the queue. Each time a new message arrives, this method examines the of the new message to see if it matches the `correlationId` parameter. If not, this method starts the time-out period over and waits for another new message to arrive. Therefore, if new messages continue to arrive within the time-out period, it is possible for this method to continue running indefinitely, either until the time-out period expires without any new messages arriving, or until a message arrives whose matches the `correlationId` parameter. - - The property is used to tie a message sent to the queue to associated response, report, or acknowledgment messages. - - Two other methods allow you to receive messages from a queue. The method returns the first message in the queue, and the method is used to retrieve a message by specifying its unique identifier. - - To read a message with a specified correlation identifier without removing it from the queue, use the method. The method always returns the first message in the queue, so subsequent calls to the method return the same message unless a higher priority message arrives in the queue. - - The following table shows whether this method is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|No| -|Remote computer and direct format name|Yes| - - - -## Examples - The following code example demonstrates the use of . - + for a message whose matches the specified `correlationId` parameter. This method returns immediately if the message with the correlation identifier specified by the `correlationId` parameter is in the queue. Otherwise, the method waits the given period of time for a new message to arrive. If a new message does not arrive before the time-out expires, an exception is thrown. + + The `timeout` parameter does not specify the total running time for this method. Rather, it specifies the time to wait for a new message to arrive in the queue. Each time a new message arrives, this method examines the of the new message to see if it matches the `correlationId` parameter. If not, this method starts the time-out period over and waits for another new message to arrive. Therefore, if new messages continue to arrive within the time-out period, it is possible for this method to continue running indefinitely, either until the time-out period expires without any new messages arriving, or until a message arrives whose matches the `correlationId` parameter. + + The property is used to tie a message sent to the queue to associated response, report, or acknowledgment messages. + + Two other methods allow you to receive messages from a queue. The method returns the first message in the queue, and the method is used to retrieve a message by specifying its unique identifier. + + To read a message with a specified correlation identifier without removing it from the queue, use the method. The method always returns the first message in the queue, so subsequent calls to the method return the same message unless a higher priority message arrives in the queue. + + The following table shows whether this method is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|No| +|Remote computer and direct format name|Yes| + + + +## Examples + The following code example demonstrates the use of . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue2/cpp/class1.cpp" id="Snippet10"::: - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet10"::: - + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet10"::: + ]]> The parameter is . The value specified for the parameter is not valid, possibly is less than or greater than . - The message with the specified does not exist in the queue and did not arrive before the time-out expired. - - -or- - + The message with the specified does not exist in the queue and did not arrive before the time-out expired. + + -or- + An error occurred when accessing a Message Queuing method. @@ -6049,54 +6049,54 @@ The name of the computer is not valid, possibly because the syntax is incorrect. Receives the message that matches the given correlation identifier (from a transactional queue) and waits until either a message with the specified correlation identifier is available in the queue, or the time-out expires. The whose matches the parameter passed in. - for a message whose matches the specified `correlationId` parameter. This method returns immediately if the message with the correlation identifier specified by the `correlationId` parameter is in the queue, using the internal transaction context defined by the `transaction` parameter. Otherwise, the method waits the given period of time for a new message to arrive. If a new message does not arrive before the time-out expires, an exception is thrown. - - The `timeout` parameter does not specify the total running time for this method. Rather, it specifies the time to wait for a new message to arrive in the queue. Each time a new message arrives, this method examines the of the new message to see if it matches the `correlationId` parameter. If not, this method starts the time-out period over and waits for another new message to arrive. Therefore, if new messages continue to arrive within the time-out period, it is possible for this method to continue running indefinitely, either until the time-out period expires without any new messages arriving, or until a message arrives whose matches the `correlationId` parameter. - - Because this method is called on a transactional queue, the message that is received would be returned to the queue if the transaction is aborted. The message is not permanently removed from the queue until the transaction is committed. - - The property is used to tie a message sent to the queue to associated response, report, or acknowledgment messages. - - Two other methods allow you to receive messages from a queue. The method returns the first message in the queue, and the method is used to retrieve a message by specifying its unique identifier. - - To read a message with a specified correlation identifier without removing it from the queue, use the method. The method always returns the first message in the queue, so subsequent calls to the method return the same message unless a higher priority message arrives in the queue. There is no transaction context associated with a message returned by a call to . Because does not remove any messages in the queue, there would be nothing to roll back if the transaction were aborted. - - The following table shows whether this method is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|No| -|Remote computer and direct format name|Yes| - - - -## Examples - The following code example demonstrates the use of . - + for a message whose matches the specified `correlationId` parameter. This method returns immediately if the message with the correlation identifier specified by the `correlationId` parameter is in the queue, using the internal transaction context defined by the `transaction` parameter. Otherwise, the method waits the given period of time for a new message to arrive. If a new message does not arrive before the time-out expires, an exception is thrown. + + The `timeout` parameter does not specify the total running time for this method. Rather, it specifies the time to wait for a new message to arrive in the queue. Each time a new message arrives, this method examines the of the new message to see if it matches the `correlationId` parameter. If not, this method starts the time-out period over and waits for another new message to arrive. Therefore, if new messages continue to arrive within the time-out period, it is possible for this method to continue running indefinitely, either until the time-out period expires without any new messages arriving, or until a message arrives whose matches the `correlationId` parameter. + + Because this method is called on a transactional queue, the message that is received would be returned to the queue if the transaction is aborted. The message is not permanently removed from the queue until the transaction is committed. + + The property is used to tie a message sent to the queue to associated response, report, or acknowledgment messages. + + Two other methods allow you to receive messages from a queue. The method returns the first message in the queue, and the method is used to retrieve a message by specifying its unique identifier. + + To read a message with a specified correlation identifier without removing it from the queue, use the method. The method always returns the first message in the queue, so subsequent calls to the method return the same message unless a higher priority message arrives in the queue. There is no transaction context associated with a message returned by a call to . Because does not remove any messages in the queue, there would be nothing to roll back if the transaction were aborted. + + The following table shows whether this method is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|No| +|Remote computer and direct format name|Yes| + + + +## Examples + The following code example demonstrates the use of . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue2/cpp/class1.cpp" id="Snippet13"::: - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet13"::: - + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet13"::: + ]]> - The parameter is . - - -or- - + The parameter is . + + -or- + The parameter is . The value specified for the parameter is not valid, possibly is less than or greater than . - The message with the specified does not exist in the queue and did not arrive before the time-out expired. - - -or- - - The queue is non-transactional. - - -or- - + The message with the specified does not exist in the queue and did not arrive before the time-out expired. + + -or- + + The queue is non-transactional. + + -or- + An error occurred when accessing a Message Queuing method. @@ -6135,49 +6135,49 @@ The name of the computer is not valid, possibly because the syntax is incorrect. Receives the message that matches the given correlation identifier and waits until either a message with the specified correlation identifier is available in the queue, or the time-out expires. The whose matches the parameter passed in. - for a message whose matches the specified `correlationId` parameter. This method returns immediately if the message with the correlation identifier specified by the `correlationId` parameter is in the queue, using a transaction context defined by the `transactionType` parameter. Otherwise, the method waits the given period of time for a new message to arrive. If a new message does not arrive before the time-out expires, an exception is thrown. - - The `timeout` parameter does not specify the total running time for this method. Rather, it specifies the time to wait for a new message to arrive in the queue. Each time a new message arrives, this method examines the of the new message to see if it matches the `correlationId` parameter. If not, this method starts the time-out period over and waits for another new message to arrive. Therefore, if new messages continue to arrive within the time-out period, it is possible for this method to continue running indefinitely, either until the time-out period expires without any new messages arriving, or until a message arrives whose matches the `correlationId` parameter. Specify `Automatic` for the `transactionType` parameter if there is already an external transaction context attached to the thread that you want to use to receive the message. Specify `Single` if you want to receive the message as a single internal transaction. You can specify `None` if you want to receive a message from a transactional queue outside of a transaction context. - - If this method is called to receive a message from a transactional queue, the message that is received would be returned to the queue if the transaction is aborted. The message is not permanently removed from the queue until the transaction is committed. - - The property is used to tie a message sent to the queue to associated response, report, or acknowledgment messages. - - Two other methods allow you to receive messages from a queue. The method returns the first message in the queue, and the method is used to retrieve a message by specifying its unique identifier. - - To read a message with a specified correlation identifier without removing it from the queue, use the method. The method always returns the first message in the queue, so subsequent calls to the method return the same message unless a higher priority message arrives in the queue. There is no transaction context associated with a message returned by a call to . Because does not remove any messages in the queue, there would be nothing to roll back if the transaction were aborted. - - The following table shows whether this method is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|No| -|Remote computer and direct format name|Yes| - - - -## Examples - The following code example demonstrates the use of . - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue2/cpp/class1.cpp" id="Snippet12"::: - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet12"::: - - ]]> - - The parameter is . - The message with the specified could not be found. - The value specified for the parameter is not valid, possibly is less than or greater than . - The parameter is not one of the members. - The message with the specified does not exist in the queue and did not arrive before the time-out expired. - - -or- - - An error occurred when accessing a Message Queuing method. + for a message whose matches the specified `correlationId` parameter. This method returns immediately if the message with the correlation identifier specified by the `correlationId` parameter is in the queue, using a transaction context defined by the `transactionType` parameter. Otherwise, the method waits the given period of time for a new message to arrive. If a new message does not arrive before the time-out expires, an exception is thrown. + + The `timeout` parameter does not specify the total running time for this method. Rather, it specifies the time to wait for a new message to arrive in the queue. Each time a new message arrives, this method examines the of the new message to see if it matches the `correlationId` parameter. If not, this method starts the time-out period over and waits for another new message to arrive. Therefore, if new messages continue to arrive within the time-out period, it is possible for this method to continue running indefinitely, either until the time-out period expires without any new messages arriving, or until a message arrives whose matches the `correlationId` parameter. Specify `Automatic` for the `transactionType` parameter if there is already an external transaction context attached to the thread that you want to use to receive the message. Specify `Single` if you want to receive the message as a single internal transaction. You can specify `None` if you want to receive a message from a transactional queue outside of a transaction context. + + If this method is called to receive a message from a transactional queue, the message that is received would be returned to the queue if the transaction is aborted. The message is not permanently removed from the queue until the transaction is committed. + + The property is used to tie a message sent to the queue to associated response, report, or acknowledgment messages. + + Two other methods allow you to receive messages from a queue. The method returns the first message in the queue, and the method is used to retrieve a message by specifying its unique identifier. + + To read a message with a specified correlation identifier without removing it from the queue, use the method. The method always returns the first message in the queue, so subsequent calls to the method return the same message unless a higher priority message arrives in the queue. There is no transaction context associated with a message returned by a call to . Because does not remove any messages in the queue, there would be nothing to roll back if the transaction were aborted. + + The following table shows whether this method is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|No| +|Remote computer and direct format name|Yes| + + + +## Examples + The following code example demonstrates the use of . + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue2/cpp/class1.cpp" id="Snippet12"::: + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet12"::: + + ]]> + + The parameter is . + The message with the specified could not be found. + The value specified for the parameter is not valid, possibly is less than or greater than . + The parameter is not one of the members. + The message with the specified does not exist in the queue and did not arrive before the time-out expired. + + -or- + + An error occurred when accessing a Message Queuing method. @@ -6219,34 +6219,34 @@ The name of the computer is not valid, possibly because the syntax is incorrect. Receives the message that matches the given identifier from a non-transactional queue and immediately raises an exception if no message with the specified identifier currently exists in the queue. The whose property matches the parameter passed in. - property of a message is unique across the Message Queuing enterprise, so there will be at most one message in the queue that matches the given `id` parameter. - - Two other methods allow you to receive messages from a queue. The method returns the first message in the queue, and the method is used to retrieve an acknowledgment, report, or application-generated response message that was created as a result of a message sent to the queue. - - To read a message with a specified identifier without removing it from the queue, use the method. The method always returns the first message in the queue, so subsequent calls to the method return the same message unless a higher priority message arrives in the queue. - - The following table shows whether this method is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|No| -|Remote computer and direct format name|Yes| - - - -## Examples - The following code example demonstrates the use of . - + property of a message is unique across the Message Queuing enterprise, so there will be at most one message in the queue that matches the given `id` parameter. + + Two other methods allow you to receive messages from a queue. The method returns the first message in the queue, and the method is used to retrieve an acknowledgment, report, or application-generated response message that was created as a result of a message sent to the queue. + + To read a message with a specified identifier without removing it from the queue, use the method. The method always returns the first message in the queue, so subsequent calls to the method return the same message unless a higher priority message arrives in the queue. + + The following table shows whether this method is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|No| +|Remote computer and direct format name|Yes| + + + +## Examples + The following code example demonstrates the use of . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue2/cpp/class1.cpp" id="Snippet16"::: - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet16"::: - + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet16"::: + ]]> The parameter is . @@ -6284,48 +6284,48 @@ The name of the computer is not valid, possibly because the syntax is incorrect. Receives the message that matches the given identifier (from a transactional queue) and immediately raises an exception if no message with the specified identifier currently exists in the queue. The whose property matches the parameter passed in. - property of a message is unique across the Message Queuing enterprise, so there will be at most one message in the queue that matches the given `id` parameter. - - Because this method is called on a transactional queue, the message that is received would be returned to the queue if the transaction is aborted. The message is not permanently removed from the queue until the transaction is committed. - - Two other methods allow you to receive messages from a queue. The method returns the first message in the queue, and the method is used to retrieve an acknowledgment, report, or application-generated response message that was created as a result of a message sent to the queue. - - To read a message with a specified identifier without removing it from the queue, use the method. The method always returns the first message in the queue, so subsequent calls to the method return the same message unless a higher priority message arrives in the queue. There is no transaction context associated with a message returned by a call to . Because does not remove any messages in the queue, there would be nothing to roll back if the transaction were aborted. - - The following table shows whether this method is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|No| -|Remote computer and direct format name|Yes| - - - -## Examples - The following code example demonstrates the use of . - + property of a message is unique across the Message Queuing enterprise, so there will be at most one message in the queue that matches the given `id` parameter. + + Because this method is called on a transactional queue, the message that is received would be returned to the queue if the transaction is aborted. The message is not permanently removed from the queue until the transaction is committed. + + Two other methods allow you to receive messages from a queue. The method returns the first message in the queue, and the method is used to retrieve an acknowledgment, report, or application-generated response message that was created as a result of a message sent to the queue. + + To read a message with a specified identifier without removing it from the queue, use the method. The method always returns the first message in the queue, so subsequent calls to the method return the same message unless a higher priority message arrives in the queue. There is no transaction context associated with a message returned by a call to . Because does not remove any messages in the queue, there would be nothing to roll back if the transaction were aborted. + + The following table shows whether this method is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|No| +|Remote computer and direct format name|Yes| + + + +## Examples + The following code example demonstrates the use of . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue2/cpp/class1.cpp" id="Snippet17"::: - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet17"::: - + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet17"::: + ]]> - The parameter is . - - -or- - + The parameter is . + + -or- + The parameter is . The message with the specified could not be found. - The queue is non-transactional. - - -or- - + The queue is non-transactional. + + -or- + An error occurred when accessing a Message Queuing method. @@ -6361,38 +6361,38 @@ The name of the computer is not valid, possibly because the syntax is incorrect. Receives the message that matches the given identifier and immediately raises an exception if no message with the specified identifier currently exists in the queue. The whose property matches the parameter passed in. - property of a message is unique across the Message Queuing enterprise, so there will be at most one message in the queue that matches the given `id` parameter. If the message with the specified identifier is in a queue other than the one associated with this instance, the message will not be found. - - If this method is called to receive a message from a transactional queue, the message that is received would be returned to the queue if the transaction is aborted. The message is not permanently removed from the queue until the transaction is committed. - - Two other methods allow you to receive messages from a queue. The method returns the first message in the queue, and the method is used to retrieve an acknowledgment, report, or application-generated response message that was created as a result of a message sent to the queue. - - To read a message with a specified identifier without removing it from the queue, use the method. The method always returns the first message in the queue, so subsequent calls to the method return the same message unless a higher priority message arrives in the queue. There is no transaction context associated with a message returned by a call to . Because does not remove any messages in the queue, there would be nothing to roll back if the transaction were aborted. - - The following table shows whether this method is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|No| -|Remote computer and direct format name|Yes| - - - -## Examples - The following code example demonstrates the use of . - + property of a message is unique across the Message Queuing enterprise, so there will be at most one message in the queue that matches the given `id` parameter. If the message with the specified identifier is in a queue other than the one associated with this instance, the message will not be found. + + If this method is called to receive a message from a transactional queue, the message that is received would be returned to the queue if the transaction is aborted. The message is not permanently removed from the queue until the transaction is committed. + + Two other methods allow you to receive messages from a queue. The method returns the first message in the queue, and the method is used to retrieve an acknowledgment, report, or application-generated response message that was created as a result of a message sent to the queue. + + To read a message with a specified identifier without removing it from the queue, use the method. The method always returns the first message in the queue, so subsequent calls to the method return the same message unless a higher priority message arrives in the queue. There is no transaction context associated with a message returned by a call to . Because does not remove any messages in the queue, there would be nothing to roll back if the transaction were aborted. + + The following table shows whether this method is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|No| +|Remote computer and direct format name|Yes| + + + +## Examples + The following code example demonstrates the use of . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue2/cpp/class1.cpp" id="Snippet15"::: - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet15"::: - + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet15"::: + ]]> The parameter is . @@ -6433,46 +6433,46 @@ The name of the computer is not valid, possibly because the syntax is incorrect. Receives the message that matches the given identifier (from a non-transactional queue) and waits until either a message with the specified identifier is available in the queue or the time-out expires. The whose property matches the parameter passed in. - of the new message to see if it matches the `id` parameter. If not, this method starts the time-out period over and waits for another new message to arrive. Therefore, if new messages continue to arrive within the time-out period, it is possible for this method to continue running indefinitely, either until the time-out period expires without any new messages arriving, or until a message arrives whose matches the `id` parameter. - - The property of a message is unique across the Message Queuing enterprise, so there will be at most one message in the queue that matches the given `id` parameter. - - Use this overload of when it is acceptable for the current thread to be blocked as long as new messages continue to arrive in the queue within the time-out period specified by the `timeout` parameter. The thread will be blocked for at least the given period of time, or indefinitely if you specified the value for the `timeout` parameter, or if new messages continue to arrive in the queue within the time-out period specified by the `timeout` parameter. - - Two other methods allow you to receive messages from a queue. The method returns the first message in the queue, and the method is used to retrieve an acknowledgment, report, or application-generated response message that was created as a result of a message sent to the queue. - - To read a message with a specified identifier without removing it from the queue, use the method. The method always returns the first message in the queue, so subsequent calls to the method return the same message unless a higher priority message arrives in the queue. - - The following table shows whether this method is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|No| -|Remote computer and direct format name|Yes| - - - -## Examples - The following code example demonstrates the use of . - + of the new message to see if it matches the `id` parameter. If not, this method starts the time-out period over and waits for another new message to arrive. Therefore, if new messages continue to arrive within the time-out period, it is possible for this method to continue running indefinitely, either until the time-out period expires without any new messages arriving, or until a message arrives whose matches the `id` parameter. + + The property of a message is unique across the Message Queuing enterprise, so there will be at most one message in the queue that matches the given `id` parameter. + + Use this overload of when it is acceptable for the current thread to be blocked as long as new messages continue to arrive in the queue within the time-out period specified by the `timeout` parameter. The thread will be blocked for at least the given period of time, or indefinitely if you specified the value for the `timeout` parameter, or if new messages continue to arrive in the queue within the time-out period specified by the `timeout` parameter. + + Two other methods allow you to receive messages from a queue. The method returns the first message in the queue, and the method is used to retrieve an acknowledgment, report, or application-generated response message that was created as a result of a message sent to the queue. + + To read a message with a specified identifier without removing it from the queue, use the method. The method always returns the first message in the queue, so subsequent calls to the method return the same message unless a higher priority message arrives in the queue. + + The following table shows whether this method is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|No| +|Remote computer and direct format name|Yes| + + + +## Examples + The following code example demonstrates the use of . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue2/cpp/class1.cpp" id="Snippet20"::: - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet20"::: - + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet20"::: + ]]> The parameter is . The value specified for the parameter is not valid, possibly is less than or greater than . - A message with the specified did not arrive in the queue before the time-out expired. - - -or- - + A message with the specified did not arrive in the queue before the time-out expired. + + -or- + An error occurred when accessing a Message Queuing method. @@ -6509,56 +6509,56 @@ The name of the computer is not valid, possibly because the syntax is incorrect. Receives the message that matches the given identifier (from a transactional queue) and waits until either a message with the specified identifier is available in the queue or the time-out expires. The whose property matches the parameter passed in. - of the new message to see if it matches the `id` parameter. If not, this method starts the time-out period over and waits for another new message to arrive. Therefore, if new messages continue to arrive within the time-out period, it is possible for this method to continue running indefinitely, either until the time-out period expires without any new messages arriving, or until a message arrives whose matches the `id` parameter. - - The property of a message is unique across the Message Queuing enterprise, so there will be at most one message in the queue that matches the given `id` parameter. - - Use this overload of when it is acceptable for the current thread to be blocked as long as new messages continue to arrive in the queue within the time-out period specified by the `timeout` parameter. The thread will be blocked for at least the given period of time, or indefinitely if you specified the value for the `timeout` parameter, or if new messages continue to arrive in the queue within the timeout period specified by the `timeout` parameter. - - Because this method is called on a transactional queue, the message that is received would be returned to the queue if the transaction is aborted. The message is not permanently removed from the queue until the transaction is committed. - - Two other methods allow you to receive messages from a queue. The method returns the first message in the queue, and the method is used to retrieve an acknowledgment, report, or application-generated response message that was created as a result of a message sent to the queue. - - To read a message with a specified identifier without removing it from the queue, use the method. The method always returns the first message in the queue, so subsequent calls to the method return the same message, unless a higher priority message arrives in the queue. There is no transaction context associated with a message returned by a call to . Because does not remove any messages in the queue, there would be nothing to roll back if the transaction were aborted. - - The following table shows whether this method is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|No| -|Remote computer and direct format name|Yes| - - - -## Examples - The following code example demonstrates the use of . - + of the new message to see if it matches the `id` parameter. If not, this method starts the time-out period over and waits for another new message to arrive. Therefore, if new messages continue to arrive within the time-out period, it is possible for this method to continue running indefinitely, either until the time-out period expires without any new messages arriving, or until a message arrives whose matches the `id` parameter. + + The property of a message is unique across the Message Queuing enterprise, so there will be at most one message in the queue that matches the given `id` parameter. + + Use this overload of when it is acceptable for the current thread to be blocked as long as new messages continue to arrive in the queue within the time-out period specified by the `timeout` parameter. The thread will be blocked for at least the given period of time, or indefinitely if you specified the value for the `timeout` parameter, or if new messages continue to arrive in the queue within the timeout period specified by the `timeout` parameter. + + Because this method is called on a transactional queue, the message that is received would be returned to the queue if the transaction is aborted. The message is not permanently removed from the queue until the transaction is committed. + + Two other methods allow you to receive messages from a queue. The method returns the first message in the queue, and the method is used to retrieve an acknowledgment, report, or application-generated response message that was created as a result of a message sent to the queue. + + To read a message with a specified identifier without removing it from the queue, use the method. The method always returns the first message in the queue, so subsequent calls to the method return the same message, unless a higher priority message arrives in the queue. There is no transaction context associated with a message returned by a call to . Because does not remove any messages in the queue, there would be nothing to roll back if the transaction were aborted. + + The following table shows whether this method is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|No| +|Remote computer and direct format name|Yes| + + + +## Examples + The following code example demonstrates the use of . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue2/cpp/class1.cpp" id="Snippet18"::: - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet18"::: - + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet18"::: + ]]> - The parameter is . - - -or- - + The parameter is . + + -or- + The parameter is . The value specified for the parameter is not valid, possibly is less than or greater than . - A message with the specified did not arrive in the queue before the time-out expired. - - -or- - - The queue is non-transactional. - - -or- - + A message with the specified did not arrive in the queue before the time-out expired. + + -or- + + The queue is non-transactional. + + -or- + An error occurred when accessing a Message Queuing method. @@ -6597,50 +6597,50 @@ The name of the computer is not valid, possibly because the syntax is incorrect. Receives the message that matches the given identifier and waits until either a message with the specified identifier is available in the queue or the time-out expires. The whose property matches the parameter passed in. - of the new message to see if it matches the `id` parameter. If not, this method starts the time-out period over and waits for another new message to arrive. Therefore, if new messages continue to arrive within the time-out period, it is possible for this method to continue running indefinitely, either until the time-out period expires without any new messages arriving, or until a message arrives whose matches the `id` parameter. - - Specify `Automatic` for the `transactionType` parameter if there is already an external transaction context attached to the thread that you want to use to receive the message. Specify `Single` if you want to receive the message as a single internal transaction. You can specify `None` if you want to receive a message from a transactional queue outside of a transaction context. - - The property of a message is unique across the Message Queuing enterprise, so there will be at most one message in the queue that matches the given `id` parameter. If the message with the specified identifier is in a queue other than the one associated with this instance, the message will not be found. - - Use this overload of when it is acceptable for the current thread to be blocked as long as new messages continue to arrive in the queue within the time-out period specified by the `timeout` parameter. The thread will be blocked for at least the given period of time, or indefinitely if you specified the value for the `timeout` parameter, or if new messages continue to arrive in the queue within the time-out period specified by the `timeout` parameter. - - If this method is called to receive a message from a transactional queue, the message that is received would be returned to the queue if the transaction is aborted. The message is not permanently removed from the queue until the transaction is committed. - - Two other methods allow you to receive messages from a queue. The method returns the first message in the queue, and the method is used to retrieve an acknowledgment, report, or application-generated response message that was created as a result of a message sent to the queue. - - To read a message with a specified identifier without removing it from the queue, use the method. The method always returns the first message in the queue, so subsequent calls to the method return the same message unless a higher priority message arrives in the queue. There is no transaction context associated with a message returned by a call to . Because does not remove any messages in the queue, there would be nothing to roll back if the transaction were aborted. - - The following table shows whether this method is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|No| -|Remote computer and direct format name|Yes| - - - -## Examples - The following code example demonstrates the use of . - + of the new message to see if it matches the `id` parameter. If not, this method starts the time-out period over and waits for another new message to arrive. Therefore, if new messages continue to arrive within the time-out period, it is possible for this method to continue running indefinitely, either until the time-out period expires without any new messages arriving, or until a message arrives whose matches the `id` parameter. + + Specify `Automatic` for the `transactionType` parameter if there is already an external transaction context attached to the thread that you want to use to receive the message. Specify `Single` if you want to receive the message as a single internal transaction. You can specify `None` if you want to receive a message from a transactional queue outside of a transaction context. + + The property of a message is unique across the Message Queuing enterprise, so there will be at most one message in the queue that matches the given `id` parameter. If the message with the specified identifier is in a queue other than the one associated with this instance, the message will not be found. + + Use this overload of when it is acceptable for the current thread to be blocked as long as new messages continue to arrive in the queue within the time-out period specified by the `timeout` parameter. The thread will be blocked for at least the given period of time, or indefinitely if you specified the value for the `timeout` parameter, or if new messages continue to arrive in the queue within the time-out period specified by the `timeout` parameter. + + If this method is called to receive a message from a transactional queue, the message that is received would be returned to the queue if the transaction is aborted. The message is not permanently removed from the queue until the transaction is committed. + + Two other methods allow you to receive messages from a queue. The method returns the first message in the queue, and the method is used to retrieve an acknowledgment, report, or application-generated response message that was created as a result of a message sent to the queue. + + To read a message with a specified identifier without removing it from the queue, use the method. The method always returns the first message in the queue, so subsequent calls to the method return the same message unless a higher priority message arrives in the queue. There is no transaction context associated with a message returned by a call to . Because does not remove any messages in the queue, there would be nothing to roll back if the transaction were aborted. + + The following table shows whether this method is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|No| +|Remote computer and direct format name|Yes| + + + +## Examples + The following code example demonstrates the use of . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue2/cpp/class1.cpp" id="Snippet19"::: - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet19"::: - + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet19"::: + ]]> The parameter is . The value specified for the parameter is not valid, possibly is less than or greater than . - A message with the specified did not arrive in the queue before the time-out expired. - - -or- - + A message with the specified did not arrive in the queue before the time-out expired. + + -or- + An error occurred when accessing a Message Queuing method. The parameter is not one of the members. @@ -6683,24 +6683,24 @@ The name of the computer is not valid, possibly because the syntax is incorrect. Introduced in MSMQ 3.0. Receives the message that matches the given lookup identifier from a non-transactional queue. The whose property matches the parameter passed in. - property of a message is unique to the queue where the message resides, so there will be at most one message in the queue that matches the given `lookupId` parameter. - - To read a message with a specified lookup identifier without removing it from the queue, use the method. - - The following table shows whether this method is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|No| -|Remote computer and direct format name|Yes| - + property of a message is unique to the queue where the message resides, so there will be at most one message in the queue that matches the given `lookupId` parameter. + + To read a message with a specified lookup identifier without removing it from the queue, use the method. + + The following table shows whether this method is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|No| +|Remote computer and direct format name|Yes| + ]]> MSMQ 3.0 is not installed. @@ -6732,50 +6732,50 @@ The name of the computer is not valid, possibly because the syntax is incorrect. - One of the values, specifying how the message is read in the queue. Specify one of the following: - - : Receives the message specified by and removes it from the queue. - - : Receives the message following the message specified by and removes it from the queue. - - : Receives the message preceding the message specified by and removes it from the queue. - - : Receives the first message in the queue and removes it from the queue. The parameter must be set to 0. - + One of the values, specifying how the message is read in the queue. Specify one of the following: + + : Receives the message specified by and removes it from the queue. + + : Receives the message following the message specified by and removes it from the queue. + + : Receives the message preceding the message specified by and removes it from the queue. + + : Receives the first message in the queue and removes it from the queue. The parameter must be set to 0. + : Receives the last message in the queue and removes it from the queue. The parameter must be set to 0. The of the message to receive, or 0. 0 is used when accessing the first or last message in the queue. The object. Introduced in MSMQ 3.0. Receives a specific message from a transactional queue. The message can be specified by a lookup identifier or by its position at the front or end of the queue. The specified by the and parameters passed in. - property of a message is unique to the queue where the message resides, so there will be at most one message in the queue that matches the given `lookupId` parameter. - - Because this method is called on a transactional queue, the message that is received would be returned to the queue if the transaction is aborted. The message is not permanently removed from the queue until the transaction is committed. - - To read a message with a specified identifier without removing it from the queue, use the method. There is no transaction context associated with a message returned by a call to . Because does not remove any messages from the queue, there would be nothing to roll back if the transaction were aborted. - - The following table shows whether this method is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|No| -|Remote computer and direct format name|Yes| - + property of a message is unique to the queue where the message resides, so there will be at most one message in the queue that matches the given `lookupId` parameter. + + Because this method is called on a transactional queue, the message that is received would be returned to the queue if the transaction is aborted. The message is not permanently removed from the queue until the transaction is committed. + + To read a message with a specified identifier without removing it from the queue, use the method. There is no transaction context associated with a message returned by a call to . Because does not remove any messages from the queue, there would be nothing to roll back if the transaction were aborted. + + The following table shows whether this method is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|No| +|Remote computer and direct format name|Yes| + ]]> MSMQ 3.0 is not installed. The message with the specified could not be found. - An error occurred when accessing a Message Queuing method. - - -or- - + An error occurred when accessing a Message Queuing method. + + -or- + The queue is non-transactional. The parameter is not one of the members. @@ -6804,53 +6804,53 @@ The name of the computer is not valid, possibly because the syntax is incorrect. - One of the values, specifying how the message is read in the queue. Specify one of the following: - - : Receives the message specified by and removes it from the queue. - - : Receives the message following the message specified by and removes it from the queue. - - : Receives the message preceding the message specified by and removes it from the queue. - - : Receives the first message in the queue and removes it from the queue. The parameter must be set to 0. - + One of the values, specifying how the message is read in the queue. Specify one of the following: + + : Receives the message specified by and removes it from the queue. + + : Receives the message following the message specified by and removes it from the queue. + + : Receives the message preceding the message specified by and removes it from the queue. + + : Receives the first message in the queue and removes it from the queue. The parameter must be set to 0. + : Receives the last message in the queue and removes it from the queue. The parameter must be set to 0. The of the message to receive, or 0. 0 is used when accessing the first or last message in the queue. One of the values, describing the type of transaction context to associate with the message. Introduced in MSMQ 3.0. Receives a specific message from the queue, using the specified transaction context. The message can be specified by a lookup identifier or by its position at the front or end of the queue. The specified by the and parameters passed in. - property of a message is unique to the queue where the message resides, so there will be at most one message in the queue that matches the given `lookupId` parameter. - - To read a message with a specified identifier without removing it from the queue, use the method. There is no transaction context associated with a message returned by a call to . Because does not remove any messages from the queue, there would be nothing to roll back if the transaction were aborted. - - Specify `Automatic` for the `transactionType` parameter if there is already an external transaction context attached to the thread that you want to use to receive the message. Specify `Single` if you want to receive the message as a single internal transaction. You can specify `None` if you want to receive a message from a transactional queue outside of a transaction context. - - If this method is called to receive a message from a transactional queue, the message that is received would be returned to the queue if the transaction is aborted. The message is not permanently removed from the queue until the transaction is committed. - - The following table shows whether this method is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|No| -|Remote computer and direct format name|Yes| - + property of a message is unique to the queue where the message resides, so there will be at most one message in the queue that matches the given `lookupId` parameter. + + To read a message with a specified identifier without removing it from the queue, use the method. There is no transaction context associated with a message returned by a call to . Because does not remove any messages from the queue, there would be nothing to roll back if the transaction were aborted. + + Specify `Automatic` for the `transactionType` parameter if there is already an external transaction context attached to the thread that you want to use to receive the message. Specify `Single` if you want to receive the message as a single internal transaction. You can specify `None` if you want to receive a message from a transactional queue outside of a transaction context. + + If this method is called to receive a message from a transactional queue, the message that is received would be returned to the queue if the transaction is aborted. The message is not permanently removed from the queue until the transaction is committed. + + The following table shows whether this method is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|No| +|Remote computer and direct format name|Yes| + ]]> MSMQ 3.0 is not installed. The message with the specified could not be found. An error occurred when accessing a Message Queuing method. - The parameter is not one of the members. - - -or- - + The parameter is not one of the members. + + -or- + The parameter is not one of the members. @@ -6882,24 +6882,24 @@ The name of the computer is not valid, possibly because the syntax is incorrect. Occurs when a message has been removed from the queue. This event is raised by the asynchronous operation, . - is used in asynchronous processing to raise the event when a message is available in the queue. - - is used to complete the operation initiated by a call to and peek the message when the event is raised. - - 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 code example creates an event handler named `MyReceiveCompleted`, attaches it to the event handler delegate, and calls to initiate an asynchronous receive operation on the queue that is located at the path ".\myQueue". When a event is raised, the example receives the message and writes its body to the screen. The example then calls again to initiate a new asynchronous receive operation. - + is used in asynchronous processing to raise the event when a message is available in the queue. + + is used to complete the operation initiated by a call to and peek the message when the event is raised. + + 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 code example creates an event handler named `MyReceiveCompleted`, attaches it to the event handler delegate, and calls to initiate an asynchronous receive operation on the queue that is located at the path ".\myQueue". When a event is raised, the example receives the message and writes its body to the screen. The example then calls again to initiate a new asynchronous receive operation. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue.ReceiveCompleted/CPP/mqreceivecompletedeventhandler.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/ReceiveCompleted/mqreceivecompletedeventhandler.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.ReceiveCompleted/VB/mqreceivecompletedeventhandler.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.ReceiveCompleted/VB/mqreceivecompletedeventhandler.vb" id="Snippet1"::: + ]]> @@ -6930,28 +6930,28 @@ The name of the computer is not valid, possibly because the syntax is incorrect. Refreshes the properties presented by the to reflect the current state of the resource. - synchronizes the properties of a with its associated Message Queuing server resource. If any property, such as or , has changed on the server since the time the was created, updates the with the new information. - - The following table shows whether this method is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|No| -|Remote computer and direct format name|Yes| - - - -## Examples - The following code example demonstrates the use of . - + synchronizes the properties of a with its associated Message Queuing server resource. If any property, such as or , has changed on the server since the time the was created, updates the with the new information. + + The following table shows whether this method is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|No| +|Remote computer and direct format name|Yes| + + + +## Examples + The following code example demonstrates the use of . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue2/cpp/class1.cpp" id="Snippet28"::: - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet28"::: - + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet28"::: + ]]> @@ -6978,34 +6978,34 @@ The name of the computer is not valid, possibly because the syntax is incorrect. Resets the permission list to the operating system's default values. Removes any queue permissions you have appended to the default list. - , you return the permission list to its default values. Generally, this grants the queue creator all permissions, and gives the group Everyone the following rights: - -- Get the properties of the queue. - -- Get queue permissions. - -- Write to the queue. - - The following table shows whether this method is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|No| -|Remote computer and direct format name|No| - - - -## Examples - The following code example demonstrates the use of . - + , you return the permission list to its default values. Generally, this grants the queue creator all permissions, and gives the group Everyone the following rights: + +- Get the properties of the queue. + +- Get queue permissions. + +- Write to the queue. + + The following table shows whether this method is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|No| +|Remote computer and direct format name|No| + + + +## Examples + The following code example demonstrates the use of . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue2/cpp/class1.cpp" id="Snippet27"::: - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet27"::: - + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet27"::: + ]]> An error occurred when accessing a Message Queuing method. @@ -7045,43 +7045,43 @@ The name of the computer is not valid, possibly because the syntax is incorrect. The object to send to the queue. Sends an object to non-transactional queue referenced by this . - . The object you send to the queue can be a or any managed object. If you send any object other than a , the object is serialized and inserted into the body of the message. - - If you use this overload to send a message to a transactional queue, the message will be sent to the dead-letter queue. If you want the message to be part of a transaction that contains other messages, use an overload that takes a or as a parameter. - - If you do not set the property before calling , the formatter defaults to the . - - The property applies to any object other than a . If you specify, for example, a label or a priority using the member, these values apply to any message that contains an object that is not of type when your application sends it to the queue. When sending a , the property values set for the take precedence over and the message's property takes precedence over the queue's property. - - The following table shows whether this method is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|No| -|Remote computer and direct format name|Yes| - - - -## Examples - The following code example connects to a message queue and sends a message to the queue. - + . The object you send to the queue can be a or any managed object. If you send any object other than a , the object is serialized and inserted into the body of the message. + + If you use this overload to send a message to a transactional queue, the message will be sent to the dead-letter queue. If you want the message to be part of a transaction that contains other messages, use an overload that takes a or as a parameter. + + If you do not set the property before calling , the formatter defaults to the . + + The property applies to any object other than a . If you specify, for example, a label or a priority using the member, these values apply to any message that contains an object that is not of type when your application sends it to the queue. When sending a , the property values set for the take precedence over and the message's property takes precedence over the queue's property. + + The following table shows whether this method is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|No| +|Remote computer and direct format name|Yes| + + + +## Examples + The following code example connects to a message queue and sends a message to the queue. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue.Send_obj/CPP/mqsend_generic.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/Send/mqsend_generic.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.Send_obj/VB/mqsend_generic.vb" id="Snippet1"::: - - The following code example sends an application-defined `Order` class to a queue and then receives a message from that queue. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.Send_obj/VB/mqsend_generic.vb" id="Snippet1"::: + + The following code example sends an application-defined `Order` class to a queue and then receives a message from that queue. + ]]> - The property has not been set. - - -or- - + The property has not been set. + + -or- + An error occurred when accessing a Message Queuing method. @@ -7118,53 +7118,53 @@ The name of the computer is not valid, possibly because the syntax is incorrect. The object. Sends an object to the transactional queue referenced by this . - , using an internal transaction context defined by the `transaction` parameter. The object you send to the queue can be a or any managed object. If you send any object other than a , the object is serialized and inserted into the body of the message. - - If you use this overload to send a message to a non-transactional queue, the message might be sent to the dead-letter queue without throwing an exception. - - If you do not set the property before calling , the formatter defaults to the . - - The property applies to any object other than a . If you specify, for example, a label or a priority using the member, these values apply to any message that contains an object that is not of type when your application sends it to the queue. When sending a , the property values set for the take precedence over and the message's property takes precedence over the queue's property. - - is threading apartment aware, so if your apartment state is `STA`, you cannot use the transaction in multiple threads. Visual Basic sets the state of the main thread to `STA`, so you must apply the in the `Main` subroutine. Otherwise, sending a transactional message using another thread throws a exception. You apply the by using the following fragment. - -```vb - - public sub Main() -``` - - The following table shows whether this method is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|No| -|Remote computer and direct format name|Yes| - - - -## Examples - The following code example sends a string to a transactional queue and then receives a message from that queue. - + , using an internal transaction context defined by the `transaction` parameter. The object you send to the queue can be a or any managed object. If you send any object other than a , the object is serialized and inserted into the body of the message. + + If you use this overload to send a message to a non-transactional queue, the message might be sent to the dead-letter queue without throwing an exception. + + If you do not set the property before calling , the formatter defaults to the . + + The property applies to any object other than a . If you specify, for example, a label or a priority using the member, these values apply to any message that contains an object that is not of type when your application sends it to the queue. When sending a , the property values set for the take precedence over and the message's property takes precedence over the queue's property. + + is threading apartment aware, so if your apartment state is `STA`, you cannot use the transaction in multiple threads. Visual Basic sets the state of the main thread to `STA`, so you must apply the in the `Main` subroutine. Otherwise, sending a transactional message using another thread throws a exception. You apply the by using the following fragment. + +```vb + + public sub Main() +``` + + The following table shows whether this method is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|No| +|Remote computer and direct format name|Yes| + + + +## Examples + The following code example sends a string to a transactional queue and then receives a message from that queue. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue.Send_ObjectTransaction/CPP/mqsend_objtransaction.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/Send/mqsend_objtransaction.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.Send_ObjectTransaction/VB/mqsend_objtransaction.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/MessageQueue.Send_ObjectTransaction/VB/mqsend_objtransaction.vb" id="Snippet1"::: + ]]> The parameter is . - The property has not been set. - - -or- - - The Message Queuing application indicated an incorrect transaction use. - - -or- - + The property has not been set. + + -or- + + The Message Queuing application indicated an incorrect transaction use. + + -or- + An error occurred when accessing a Message Queuing method. @@ -7202,41 +7202,41 @@ The name of the computer is not valid, possibly because the syntax is incorrect. One of the values, describing the type of transaction context to associate with the message. Sends an object to the queue referenced by this . - , using a transaction context defined by the `transactionType` parameter. Specify `Automatic` for the `transactionType` parameter if there is already an external transaction context attached to the thread that you want to use to send the message. Specify `Single` if you want to send the message as a single internal transaction. You can specify `None` if you want to send a transactional message to a non-transactional thread. - - The object you send to the queue can be a or any managed object. If you send any object other than a , the object is serialized and inserted into the body of the message. - - If you do not set the property before calling , the formatter defaults to the . - - The property applies to any object other than a . If you specify, for example, a label or a priority using the member, these values apply to any message that contains an object that is not of type when your application sends it to the queue. When sending a , the property values set for the take precedence over and the message's property takes precedence over the queue's property. - - The following table shows whether this method is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|No| -|Remote computer and direct format name|Yes| - - - -## Examples - The following code example demonstrates the use of . - + , using a transaction context defined by the `transactionType` parameter. Specify `Automatic` for the `transactionType` parameter if there is already an external transaction context attached to the thread that you want to use to send the message. Specify `Single` if you want to send the message as a single internal transaction. You can specify `None` if you want to send a transactional message to a non-transactional thread. + + The object you send to the queue can be a or any managed object. If you send any object other than a , the object is serialized and inserted into the body of the message. + + If you do not set the property before calling , the formatter defaults to the . + + The property applies to any object other than a . If you specify, for example, a label or a priority using the member, these values apply to any message that contains an object that is not of type when your application sends it to the queue. When sending a , the property values set for the take precedence over and the message's property takes precedence over the queue's property. + + The following table shows whether this method is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|No| +|Remote computer and direct format name|Yes| + + + +## Examples + The following code example demonstrates the use of . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue2/cpp/class1.cpp" id="Snippet2"::: - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet2"::: - + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet2"::: + ]]> The parameter is not one of the members. - The property has not been set. - - -or- - + The property has not been set. + + -or- + An error occurred when accessing a Message Queuing method. @@ -7274,43 +7274,43 @@ The name of the computer is not valid, possibly because the syntax is incorrect. The label of the message. Sends an object to the non-transactional queue referenced by this and specifies a label for the message. - . With this overload, you can specify the string label that identifies the message. The object you send to the queue can be a , a structure, a data object, or any managed object. If you send any object other than a , the object is serialized and inserted into the body of the message. - - The message label is distinct from the message queue label, but both are application-dependent and have no inherit meaning to Message Queuing. - - If you use this overload to send a message to a transactional queue, the message will be sent to the dead-letter queue. If you want the message to be part of a transaction that contains other messages, use an overload that takes a or as a parameter. - - The property for this instance must be specified before you send the message. If you do not set the property before calling , the formatter defaults to the . - - The property applies to any object other than a . If you specify, for example, a label or a priority using the member, these values apply to any message that contains an object that is not of type when your application sends it to the queue. When sending a , the property values set for the take precedence over and the message's property takes precedence over the queue's property. - - The following table shows whether this method is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|No| -|Remote computer and direct format name|Yes| - - - -## Examples - The following code example demonstrates the use of . - + . With this overload, you can specify the string label that identifies the message. The object you send to the queue can be a , a structure, a data object, or any managed object. If you send any object other than a , the object is serialized and inserted into the body of the message. + + The message label is distinct from the message queue label, but both are application-dependent and have no inherit meaning to Message Queuing. + + If you use this overload to send a message to a transactional queue, the message will be sent to the dead-letter queue. If you want the message to be part of a transaction that contains other messages, use an overload that takes a or as a parameter. + + The property for this instance must be specified before you send the message. If you do not set the property before calling , the formatter defaults to the . + + The property applies to any object other than a . If you specify, for example, a label or a priority using the member, these values apply to any message that contains an object that is not of type when your application sends it to the queue. When sending a , the property values set for the take precedence over and the message's property takes precedence over the queue's property. + + The following table shows whether this method is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|No| +|Remote computer and direct format name|Yes| + + + +## Examples + The following code example demonstrates the use of . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue2/cpp/class1.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet1"::: - + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet1"::: + ]]> The parameter is . - The property has not been set. - - -or- - + The property has not been set. + + -or- + An error occurred when accessing a Message Queuing method. @@ -7349,58 +7349,58 @@ The name of the computer is not valid, possibly because the syntax is incorrect. The object. Sends an object to the transactional queue referenced by this and specifies a label for the message. - , using an internal transaction context defined by the `transaction` parameter. With this overload, you can specify the string label that identifies the message. The object you send to the queue can be a , a structure, a data object, or any managed object. If you send any object other than a , the object is serialized and inserted into the body of the message. - - The message label is distinct from the message queue label, but both are application-dependent and have no inherit meaning to Message Queuing. - - If you use this overload to send a message to a non-transactional queue, the message might be sent to the dead-letter queue without throwing an exception. - - If you do not set the property before calling , the formatter defaults to the . - - The property applies to any object other than a . If you specify, for example, a label or a priority using the member, these values apply to any message that contains an object that is not of type when your application sends it to the queue. When sending a , the property values set for the take precedence over and the message's property takes precedence over the queue's property - - is threading apartment aware, so if your apartment state is `STA`, you cannot use the transaction in multiple threads. Visual Basic sets the state of the main thread to `STA`, so you must apply the in the `Main` subroutine. Otherwise, sending a transactional message using another thread throws a exception. You apply the by using the following fragment. - -```vb - - public sub Main() -``` - - The following table shows whether this method is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|No| -|Remote computer and direct format name|Yes| - - - -## Examples - The following code example demonstrates the use of . - + , using an internal transaction context defined by the `transaction` parameter. With this overload, you can specify the string label that identifies the message. The object you send to the queue can be a , a structure, a data object, or any managed object. If you send any object other than a , the object is serialized and inserted into the body of the message. + + The message label is distinct from the message queue label, but both are application-dependent and have no inherit meaning to Message Queuing. + + If you use this overload to send a message to a non-transactional queue, the message might be sent to the dead-letter queue without throwing an exception. + + If you do not set the property before calling , the formatter defaults to the . + + The property applies to any object other than a . If you specify, for example, a label or a priority using the member, these values apply to any message that contains an object that is not of type when your application sends it to the queue. When sending a , the property values set for the take precedence over and the message's property takes precedence over the queue's property + + is threading apartment aware, so if your apartment state is `STA`, you cannot use the transaction in multiple threads. Visual Basic sets the state of the main thread to `STA`, so you must apply the in the `Main` subroutine. Otherwise, sending a transactional message using another thread throws a exception. You apply the by using the following fragment. + +```vb + + public sub Main() +``` + + The following table shows whether this method is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|No| +|Remote computer and direct format name|Yes| + + + +## Examples + The following code example demonstrates the use of . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue2/cpp/class1.cpp" id="Snippet4"::: - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet4"::: - + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet4"::: + ]]> - The parameter is . - - -or- - + The parameter is . + + -or- + The parameter is . - The property has not been set. - - -or- - - The Message Queuing application indicated an incorrect transaction usage. - - -or- - + The property has not been set. + + -or- + + The Message Queuing application indicated an incorrect transaction usage. + + -or- + An error occurred when accessing a Message Queuing method. @@ -7441,45 +7441,45 @@ The name of the computer is not valid, possibly because the syntax is incorrect. One of the values, describing the type of transaction context to associate with the message. Sends an object to the queue referenced by this and specifies a label for the message. - , using a transaction context defined by the `transactionType` parameter. Specify `Automatic` for the `transactionType` parameter if there is already an external transaction context attached to the thread that you want to use to send the message. Specify `Single` if you want to send the message as a single internal transaction. You can specify `None` if you want to send a transactional message to a non-transactional thread. - - The object you send to the queue can be a or any managed object. If you send any object other than a , the object is serialized and inserted into the body of the message. With this overload, you can specify the string label that identifies the message. - - The message label is distinct from the message queue label, but both are application-dependent and have no inherit meaning to Message Queuing. - - If you do not set the property before calling , the formatter defaults to the . - - The property applies to any object other than a . If you specify, for example, a label or a priority using the member, these values apply to any message that contains an object that is not of type when your application sends it to the queue. When sending a , the property values set for the take precedence over , and the message's property takes precedence over the queue's property. - - The following table shows whether this method is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|No| -|Remote computer and direct format name|Yes| - - - -## Examples - The following code example demonstrates the use of . - + , using a transaction context defined by the `transactionType` parameter. Specify `Automatic` for the `transactionType` parameter if there is already an external transaction context attached to the thread that you want to use to send the message. Specify `Single` if you want to send the message as a single internal transaction. You can specify `None` if you want to send a transactional message to a non-transactional thread. + + The object you send to the queue can be a or any managed object. If you send any object other than a , the object is serialized and inserted into the body of the message. With this overload, you can specify the string label that identifies the message. + + The message label is distinct from the message queue label, but both are application-dependent and have no inherit meaning to Message Queuing. + + If you do not set the property before calling , the formatter defaults to the . + + The property applies to any object other than a . If you specify, for example, a label or a priority using the member, these values apply to any message that contains an object that is not of type when your application sends it to the queue. When sending a , the property values set for the take precedence over , and the message's property takes precedence over the queue's property. + + The following table shows whether this method is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|No| +|Remote computer and direct format name|Yes| + + + +## Examples + The following code example demonstrates the use of . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue2/cpp/class1.cpp" id="Snippet3"::: - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet3"::: - + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet3"::: + ]]> The parameter is . The Message Queuing application indicated an incorrect transaction usage. The parameter is not one of the members. - The property has not been set. - - -or- - + The property has not been set. + + -or- + An error occurred when accessing a Message Queuing method. @@ -7525,88 +7525,88 @@ The name of the computer is not valid, possibly because the syntax is incorrect. A that contains one or more access control entries that specify the trustees and the permissions to grant. Assigns access rights to the queue based on the contents of an access control list. - add rights to the existing list. By default, the creator of a public or private queue has full control, and the domain group Everyone has permission to get queue properties, get permissions, and write to the queue. When you call , the user and permissions information is appended to the bottom of the existing list. - - The system examines each in sequence until one of the following events occurs: - -- An access-denied explicitly denies any of the requested access rights to one of the trustees listed in the thread's access token. - -- One or more access-allowed items for trustees listed in the thread's access token explicitly grant all the requested access rights. - -- All items have been checked and there is still at least one requested access right that has not been explicitly allowed, in which case, access is implicitly denied. - - When you construct the `dacl` parameter, you add instances to your collection. When you construct each access control entry, you can specify generic or standard access rights. The rights to a queue can be any combination of the following: - -- Delete - -- Read Security - -- Write Security - -- Synchronize - -- Modify Owner - -- Read - -- Write - -- Execute - -- Required - -- All - -- None - - These rights are a set of bit flags that you can combine using the OR bitwise operator. - -- Full Control - -- Delete Message - -- Receive Message - -- Peek Message - -- Receive Journal Message - -- Get Queue Properties - -- Set Queue Properties - -- Get Permissions - -- Set Permissions - -- Take Queue Ownership - -- Write Message - - The following table shows whether this method is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|No| -|Remote computer and direct format name|No| - - - -## Examples - The following code example demonstrates the use of . - + add rights to the existing list. By default, the creator of a public or private queue has full control, and the domain group Everyone has permission to get queue properties, get permissions, and write to the queue. When you call , the user and permissions information is appended to the bottom of the existing list. + + The system examines each in sequence until one of the following events occurs: + +- An access-denied explicitly denies any of the requested access rights to one of the trustees listed in the thread's access token. + +- One or more access-allowed items for trustees listed in the thread's access token explicitly grant all the requested access rights. + +- All items have been checked and there is still at least one requested access right that has not been explicitly allowed, in which case, access is implicitly denied. + + When you construct the `dacl` parameter, you add instances to your collection. When you construct each access control entry, you can specify generic or standard access rights. The rights to a queue can be any combination of the following: + +- Delete + +- Read Security + +- Write Security + +- Synchronize + +- Modify Owner + +- Read + +- Write + +- Execute + +- Required + +- All + +- None + + These rights are a set of bit flags that you can combine using the OR bitwise operator. + +- Full Control + +- Delete Message + +- Receive Message + +- Peek Message + +- Receive Journal Message + +- Get Queue Properties + +- Set Queue Properties + +- Get Permissions + +- Set Permissions + +- Take Queue Ownership + +- Write Message + + The following table shows whether this method is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|No| +|Remote computer and direct format name|No| + + + +## Examples + The following code example demonstrates the use of . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue2/cpp/class1.cpp" id="Snippet26"::: - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet26"::: - + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet26"::: + ]]> An error occurred when accessing a Message Queuing method. @@ -7639,66 +7639,66 @@ The name of the computer is not valid, possibly because the syntax is incorrect. A that specifies a user, an access type, and a permission type. Assigns access rights to the queue based on the contents of an access control entry. - add rights to the existing list. By default, the creator of a public or private queue has full control, and the domain group Everyone has permission to get queue properties, get permissions, and write to the queue. When you call , the user and permissions information is appended to the bottom of the existing list. - - The system examines each in sequence until one of the following events occurs: - -- An access-denied explicitly denies any of the requested access rights to one of the trustees listed in the thread's access token. - -- One or more access-allowed items for trustees listed in the thread's access token explicitly grant all the requested access rights. - -- All items have been checked and there is still at least one requested access right that has not been explicitly allowed, in which case, access is implicitly denied. - - The rights to a queue, which you specify in the `rights` parameter when you construct your , can be any combination of the following: - -- Full Control - -- Delete Message - -- Receive Message - -- Peek Message - -- Receive Journal Message - -- Get Queue Properties - -- Set Queue Properties - -- Get Permissions - -- Set Permissions - -- Take Queue Ownership - -- Write Message - - The `rights` parameter you specify in the constructor for the `ace` parameter is a flag of the enumeration. It represents a set of bit flags that you can combine using the bitwise operator OR when you build the `rights` parameter. - - The following table shows whether this method is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|No| -|Remote computer and direct format name|No| - - - -## Examples - The following code example demonstrates the use of . - + add rights to the existing list. By default, the creator of a public or private queue has full control, and the domain group Everyone has permission to get queue properties, get permissions, and write to the queue. When you call , the user and permissions information is appended to the bottom of the existing list. + + The system examines each in sequence until one of the following events occurs: + +- An access-denied explicitly denies any of the requested access rights to one of the trustees listed in the thread's access token. + +- One or more access-allowed items for trustees listed in the thread's access token explicitly grant all the requested access rights. + +- All items have been checked and there is still at least one requested access right that has not been explicitly allowed, in which case, access is implicitly denied. + + The rights to a queue, which you specify in the `rights` parameter when you construct your , can be any combination of the following: + +- Full Control + +- Delete Message + +- Receive Message + +- Peek Message + +- Receive Journal Message + +- Get Queue Properties + +- Set Queue Properties + +- Get Permissions + +- Set Permissions + +- Take Queue Ownership + +- Write Message + + The `rights` parameter you specify in the constructor for the `ace` parameter is a flag of the enumeration. It represents a set of bit flags that you can combine using the bitwise operator OR when you build the `rights` parameter. + + The following table shows whether this method is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|No| +|Remote computer and direct format name|No| + + + +## Examples + The following code example demonstrates the use of . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue2/cpp/class1.cpp" id="Snippet24"::: - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet24"::: - + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet24"::: + ]]> An error occurred when accessing a Message Queuing method. @@ -7734,66 +7734,66 @@ The name of the computer is not valid, possibly because the syntax is incorrect. A that indicates the set of rights to the queue that Message Queuing assigns to the passed in. Gives a computer, group, or user the specified access rights. - add rights to the existing list. By default, the creator of a public or private queue has full control, and the domain group Everyone has permission to get queue properties, get permissions, and write to the queue. When you call , the user and permissions information is appended to the bottom of the existing list. - - The system examines each in sequence until one of the following events occurs: - -- An access-denied explicitly denies any of the requested access rights to one of the trustees listed in the thread's access token. - -- One or more access-allowed items for trustees listed in the thread's access token explicitly grant all the requested access rights. - -- All items have been checked and there is still at least one requested access right that has not been explicitly allowed, in which case, access is implicitly denied. - - The rights to a queue, specified in the `rights` parameter, can be any combination of the following: - -- Full Control - -- Delete Message - -- Receive Message - -- Peek Message - -- Receive Journal Message - -- Get Queue Properties - -- Set Queue Properties - -- Get Permissions - -- Set Permissions - -- Take Queue Ownership - -- Write Message - - The enumeration represents a set of bit flags that you can combine using the bitwise operator OR to build the `rights` parameter. - - With this overload, you can only grant permissions; you cannot revoke or deny them. You must use a different overload to explicitly grant any other than `Allow`. - - The following table shows whether this method is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|No| -|Remote computer and direct format name|No| - - - -## Examples - The following code example demonstrates the use of . - + add rights to the existing list. By default, the creator of a public or private queue has full control, and the domain group Everyone has permission to get queue properties, get permissions, and write to the queue. When you call , the user and permissions information is appended to the bottom of the existing list. + + The system examines each in sequence until one of the following events occurs: + +- An access-denied explicitly denies any of the requested access rights to one of the trustees listed in the thread's access token. + +- One or more access-allowed items for trustees listed in the thread's access token explicitly grant all the requested access rights. + +- All items have been checked and there is still at least one requested access right that has not been explicitly allowed, in which case, access is implicitly denied. + + The rights to a queue, specified in the `rights` parameter, can be any combination of the following: + +- Full Control + +- Delete Message + +- Receive Message + +- Peek Message + +- Receive Journal Message + +- Get Queue Properties + +- Set Queue Properties + +- Get Permissions + +- Set Permissions + +- Take Queue Ownership + +- Write Message + + The enumeration represents a set of bit flags that you can combine using the bitwise operator OR to build the `rights` parameter. + + With this overload, you can only grant permissions; you cannot revoke or deny them. You must use a different overload to explicitly grant any other than `Allow`. + + The following table shows whether this method is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|No| +|Remote computer and direct format name|No| + + + +## Examples + The following code example demonstrates the use of . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue2/cpp/class1.cpp" id="Snippet23"::: - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet23"::: - + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet23"::: + ]]> The is . @@ -7831,64 +7831,64 @@ The name of the computer is not valid, possibly because the syntax is incorrect. A that specifies whether to grant, deny, or revoke the permissions specified by the parameter. Gives a computer, group, or user the specified access rights, with the specified access control type (allow, deny, revoke, or set). - add rights to the existing list. By default, the creator of a public or private queue has full control, and the domain group Everyone has permission to get queue properties, get permissions, and write to the queue. When you call , the user and permissions information is appended to the bottom of the existing list. - - The system examines each in sequence until one of the following events occurs: - -- An access-denied explicitly denies any of the requested access rights to one of the trustees listed in the thread's access token. - -- One or more access-allowed items for trustees listed in the thread's access token explicitly grant all the requested access rights. - -- All items have been checked and there is still at least one requested access right that has not been explicitly allowed, in which case, access is implicitly denied. - - The rights to a queue, specified in the `rights` parameter, can be any combination of the following: - -- Full Control - -- Delete Message - -- Receive Message - -- Peek Message - -- Receive Journal Message - -- Get Queue Properties - -- Set Queue Properties - -- Get Permissions - -- Set Permissions - -- Take Queue Ownership - -- Write Message - - The enumeration represents a set of bit flags that you can combine using the bitwise operator OR to build the `rights` parameter. - - The following table shows whether this method is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|No| -|Remote computer and direct format name|No| - - - -## Examples - The following code example demonstrates the use of . - + add rights to the existing list. By default, the creator of a public or private queue has full control, and the domain group Everyone has permission to get queue properties, get permissions, and write to the queue. When you call , the user and permissions information is appended to the bottom of the existing list. + + The system examines each in sequence until one of the following events occurs: + +- An access-denied explicitly denies any of the requested access rights to one of the trustees listed in the thread's access token. + +- One or more access-allowed items for trustees listed in the thread's access token explicitly grant all the requested access rights. + +- All items have been checked and there is still at least one requested access right that has not been explicitly allowed, in which case, access is implicitly denied. + + The rights to a queue, specified in the `rights` parameter, can be any combination of the following: + +- Full Control + +- Delete Message + +- Receive Message + +- Peek Message + +- Receive Journal Message + +- Get Queue Properties + +- Set Queue Properties + +- Get Permissions + +- Set Permissions + +- Take Queue Ownership + +- Write Message + + The enumeration represents a set of bit flags that you can combine using the bitwise operator OR to build the `rights` parameter. + + The following table shows whether this method is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|No| +|Remote computer and direct format name|No| + + + +## Examples + The following code example demonstrates the use of . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue2/cpp/class1.cpp" id="Snippet25"::: - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet25"::: - + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetAllMessages/class1.cs" id="Snippet25"::: + ]]> An error occurred when accessing a Message Queuing method. @@ -7933,13 +7933,13 @@ The name of the computer is not valid, possibly because the syntax is incorrect. Gets or sets the object that marshals the event-handler call resulting from a or event. A , which represents the object that marshals the event-handler call resulting from a or event. The default is . - or event results from a or request, respectively, to a specific thread. Typically, the is set when its related component is placed inside a control or a form, because those components are bound to a specific thread. - - Typically, the synchronizing object marshals a method call into a single thread. - + or event results from a or request, respectively, to a specific thread. Typically, the is set when its related component is placed inside a control or a form, because those components are bound to a specific thread. + + Typically, the synchronizing object marshals a method call into a single thread. + ]]> @@ -7978,38 +7978,38 @@ The name of the computer is not valid, possibly because the syntax is incorrect. if the queue accepts only messages sent as part of a transaction; otherwise, . - , , and syntax. If a non-transactional message is sent to a transactional queue, this component creates a single-message transaction for it, except in the case of referencing a queue on a remote computer using a direct format name. In this situation, if you do not specify a transaction context when sending a message, one is not created for you and the message will be sent to the dead-letter queue. - - If you send a non-transactional message to a transactional queue, you will not be able to roll back the message in the event of an exception. - - is threading apartment aware, so if your apartment state is `STA`, you cannot use the transaction in multiple threads. Visual Basic sets the state of the main thread to `STA`, so you must apply the in the `Main` subroutine. Otherwise, sending a transactional message using another thread throws a exception. You apply the by using the following fragment. - -```vb - - public sub Main() -``` - - The following table shows whether this property is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|No| -|Remote computer and direct format name|No| - - - -## Examples - The following code example displays the value of a message queue's property. - - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/.ctor/class1.cs" id="Snippet27"::: - + , , and syntax. If a non-transactional message is sent to a transactional queue, this component creates a single-message transaction for it, except in the case of referencing a queue on a remote computer using a direct format name. In this situation, if you do not specify a transaction context when sending a message, one is not created for you and the message will be sent to the dead-letter queue. + + If you send a non-transactional message to a transactional queue, you will not be able to roll back the message in the event of an exception. + + is threading apartment aware, so if your apartment state is `STA`, you cannot use the transaction in multiple threads. Visual Basic sets the state of the main thread to `STA`, so you must apply the in the `Main` subroutine. Otherwise, sending a transactional message using another thread throws a exception. You apply the by using the following fragment. + +```vb + + public sub Main() +``` + + The following table shows whether this property is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|No| +|Remote computer and direct format name|No| + + + +## Examples + The following code example displays the value of a message queue's property. + + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/.ctor/class1.cs" id="Snippet27"::: + ]]> An error occurred when accessing a Message Queuing method. @@ -8053,31 +8053,31 @@ The name of the computer is not valid, possibly because the syntax is incorrect. if messages received from the queue are copied to its journal queue; otherwise, . - instances are affected by the change. - - The journal queue does not track messages removed from the queue because their time-to-be-received timer expired, nor does it track messages purged from the queue by using a Message Queuing directory service (Information Store or Active Directory). - - Applications cannot send messages to journal queues; they are limited to read-only access of these queues. Furthermore, Message Queuing never removes messages from journal queues. The application using the queue must clear these messages either by receiving them or by purging the queue. - - The following table shows whether this property is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|No| -|Remote computer and direct format name|No| - - - -## Examples - The following code example gets and sets the value of a message queue's property. - - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/.ctor/class1.cs" id="Snippet28"::: - + instances are affected by the change. + + The journal queue does not track messages removed from the queue because their time-to-be-received timer expired, nor does it track messages purged from the queue by using a Message Queuing directory service (Information Store or Active Directory). + + Applications cannot send messages to journal queues; they are limited to read-only access of these queues. Furthermore, Message Queuing never removes messages from journal queues. The application using the queue must clear these messages either by receiving them or by purging the queue. + + The following table shows whether this property is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|No| +|Remote computer and direct format name|No| + + + +## Examples + The following code example gets and sets the value of a message queue's property. + + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/.ctor/class1.cs" id="Snippet28"::: + ]]> An error occurred when accessing a Message Queuing method. @@ -8119,20 +8119,20 @@ The name of the computer is not valid, possibly because the syntax is incorrect. Gets the native handle used to send messages to the message queue. A handle to the native queue object that you use for sending messages to the queue. - provides a native Windows handle to the message queue object that is used for sending messages to the queue. If you change the path of the queue, the handle is closed and reopened with a new value. - - The following table shows whether this property is available in various Workgroup modes. - -|Workgroup mode|Available| -|--------------------|---------------| -|Local computer|Yes| -|Local computer and direct format name|Yes| -|Remote computer|No| -|Remote computer and direct format name|Yes| - + provides a native Windows handle to the message queue object that is used for sending messages to the queue. If you change the path of the queue, the handle is closed and reopened with a new value. + + The following table shows whether this property is available in various Workgroup modes. + +|Workgroup mode|Available| +|--------------------|---------------| +|Local computer|Yes| +|Local computer and direct format name|Yes| +|Remote computer|No| +|Remote computer and direct format name|Yes| + ]]> The message queue is not available for writing. diff --git a/xml/System.Net.NetworkInformation/NetworkInterface.xml b/xml/System.Net.NetworkInformation/NetworkInterface.xml index 6f9cc307871..8d131f3149d 100644 --- a/xml/System.Net.NetworkInformation/NetworkInterface.xml +++ b/xml/System.Net.NetworkInformation/NetworkInterface.xml @@ -63,19 +63,19 @@ Provides configuration and statistical information for a network interface. - method returns an array that contains one instance of this class for each network interface on the local computer. - - - -## Examples - The following code example displays information about interfaces. - + method returns an array that contains one instance of this class for each network interface on the local computer. + + + +## Examples + The following code example displays information about interfaces. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NCLNetInfoReport/CPP/netinfo.cpp" id="Snippet12"::: - :::code language="csharp" source="~/snippets/csharp/System.Net.NetworkInformation/IcmpV4Statistics/Overview/netinfo.cs" id="Snippet12"::: - + :::code language="csharp" source="~/snippets/csharp/System.Net.NetworkInformation/IcmpV4Statistics/Overview/netinfo.cs" id="Snippet12"::: + ]]> @@ -123,11 +123,11 @@ Initializes a new instance of the class. - class. - + class. + ]]> @@ -176,19 +176,19 @@ Gets the description of the interface. A that describes this interface. - @@ -245,20 +245,20 @@ Returns objects that describe the network interfaces on the local computer. A array that contains objects that describe the available network interfaces, or an empty array if no interfaces are detected. - A Windows system function call failed. @@ -310,20 +310,20 @@ Returns an object that describes the configuration of this network interface. An object that describes this network interface. - @@ -484,11 +484,11 @@ if a network connection is available; otherwise, . - @@ -539,20 +539,20 @@ Returns the Media Access Control (MAC) or physical address for this adapter. A object that contains the physical address. - @@ -653,11 +653,11 @@ Gets the index of the IPv6 loopback interface. The index for the IPv6 loopback interface. - @@ -708,15 +708,15 @@ if the interface only receives network traffic; otherwise, . - This property is not valid on computers running operating systems earlier than Windows XP. @@ -773,13 +773,13 @@ Gets the index of the IPv4 loopback interface. A that contains the index for the IPv4 loopback interface. - property to get the correct value. - - A network interface may have different interface indexes for the IPv4 and IPv6 loopback interface. The property only returns the IPv4 loopback interface. - + property to get the correct value. + + A network interface may have different interface indexes for the IPv4 and IPv6 loopback interface. The property only returns the IPv4 loopback interface. + ]]> This property is not valid on computers running only Ipv6. @@ -830,14 +830,14 @@ Gets the name of the network adapter. A that contains the adapter name. - @@ -886,24 +886,24 @@ Gets the interface type. An value that specifies the network interface type. - enumeration documentation. + enumeration documentation. In principle, this property can return any member of the enumeration. The specific value that it does return is dependent on the runtime conditions of the underlying network topology. This means that: - + - It is not possible to determine in advance which value the property returns for a particular network. - + - It is possible that in practice on a particular network, the full range of enumeration values is not available. For example, on a gigabit Ethernet network, it is possible that the property returns rather than . -## Examples - The following example displays type information for all interfaces on the local computer. - +## Examples + The following example displays type information for all interfaces on the local computer. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NCLNetInfo2/CPP/networkexamples.cpp" id="Snippet51"::: :::code language="csharp" source="~/snippets/csharp/System.Net.NetworkInformation/DuplicateAddressDetectionState/Overview/networkexamples.cs" id="Snippet51"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NCLNetInfo2/VB/networkexamples.vb" id="Snippet51"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NCLNetInfo2/VB/networkexamples.vb" id="Snippet51"::: + ]]> @@ -952,19 +952,19 @@ Gets the current operational state of the network connection. One of the values. - enumeration documentation. - - - -## Examples - The following code example displays a summary for all interfaces on the local computer. - + enumeration documentation. + + + +## Examples + The following code example displays a summary for all interfaces on the local computer. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NCLNetInfoReport/CPP/netinfo.cpp" id="Snippet16"::: - :::code language="csharp" source="~/snippets/csharp/System.Net.NetworkInformation/IcmpV4Statistics/Overview/netinfo.cs" id="Snippet16"::: - + :::code language="csharp" source="~/snippets/csharp/System.Net.NetworkInformation/IcmpV4Statistics/Overview/netinfo.cs" id="Snippet16"::: + ]]> @@ -1013,20 +1013,20 @@ Gets the speed of the network interface. A value that specifies the speed in bits per second. -
@@ -1073,7 +1073,7 @@ System.Boolean - + A value. @@ -1081,15 +1081,15 @@ if the specified protocol is supported; otherwise, . - @@ -1139,20 +1139,20 @@ if the interface receives multicast packets; otherwise, . - This property is not valid on computers running operating systems earlier than Windows XP. diff --git a/xml/System.Net.Sockets/Socket.xml b/xml/System.Net.Sockets/Socket.xml index 9acb4f586f6..d9d5e107f0f 100644 --- a/xml/System.Net.Sockets/Socket.xml +++ b/xml/System.Net.Sockets/Socket.xml @@ -195,7 +195,7 @@ This method populates the instance with data ga - + The socket information returned by . @@ -897,8 +897,8 @@ This method populates the instance with data ga System.IAsyncResult - - + + The delegate. @@ -1000,9 +1000,9 @@ This method populates the instance with data ga System.IAsyncResult - - - + + + The number of bytes to accept from the sender. @@ -1101,10 +1101,10 @@ This method populates the instance with data ga System.IAsyncResult - - - - + + + + The accepted object. This value may be . @@ -1210,8 +1210,7 @@ This method populates the instance with data ga - - + [System.Runtime.CompilerServices.Nullable(2)] @@ -1219,7 +1218,7 @@ This method populates the instance with data ga - + [System.Runtime.CompilerServices.Nullable(2)] @@ -1230,7 +1229,6 @@ This method populates the instance with data ga An that represents the remote host. - An that represents the remote host. The delegate. An object that contains state information for this request. Begins an asynchronous request for a remote host connection. @@ -1317,8 +1315,8 @@ This method populates the instance with data ga System.IAsyncResult - - + + @@ -1327,8 +1325,7 @@ This method populates the instance with data ga - - + [System.Runtime.CompilerServices.Nullable(2)] @@ -1341,7 +1338,6 @@ This method populates the instance with data ga The of the remote host. The port number of the remote host. An delegate that references the method to invoke when the connect operation is complete. - An delegate that references the method to invoke when the connect operation is complete. A user-defined object that contains information about the connect operation. This object is passed to the delegate when the operation is complete. Begins an asynchronous request for a remote host connection. The host is specified by an and a port number. An that references the asynchronous connection. @@ -1433,8 +1429,8 @@ This method populates the instance with data ga System.IAsyncResult - - + + @@ -1443,8 +1439,7 @@ This method populates the instance with data ga - - + [System.Runtime.CompilerServices.Nullable(2)] @@ -1457,7 +1452,6 @@ This method populates the instance with data ga At least one , designating the remote host. The port number of the remote host. An delegate that references the method to invoke when the connect operation is complete. - An delegate that references the method to invoke when the connect operation is complete. A user-defined object that contains information about the connect operation. This object is passed to the delegate when the operation is complete. Begins an asynchronous request for a remote host connection. The host is specified by an array and a port number. An that references the asynchronous connections. @@ -1549,8 +1543,8 @@ This method populates the instance with data ga System.IAsyncResult - - + + @@ -1559,8 +1553,7 @@ This method populates the instance with data ga - - + [System.Runtime.CompilerServices.Nullable(2)] @@ -1573,7 +1566,6 @@ This method populates the instance with data ga The name of the remote host. The port number of the remote host. An delegate that references the method to invoke when the connect operation is complete. - An delegate that references the method to invoke when the connect operation is complete. A user-defined object that contains information about the connect operation. This object is passed to the delegate when the operation is complete. Begins an asynchronous request for a remote host connection. The host is specified by a host name and a port number. An that references the asynchronous connection. @@ -1669,9 +1661,9 @@ This method populates the instance with data ga System.IAsyncResult - - - + + + @@ -1759,7 +1751,7 @@ This method populates the instance with data ga System.IAsyncResult - + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 0 })] @@ -1767,9 +1759,9 @@ This method populates the instance with data ga - - - + + + An array of type that is the storage location for the received data. @@ -1866,7 +1858,7 @@ This method populates the instance with data ga System.IAsyncResult - + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 0 })] @@ -1874,10 +1866,10 @@ This method populates the instance with data ga - - - - + + + + An array of type that is the storage location for the received data. @@ -1970,12 +1962,11 @@ This method populates the instance with data ga System.IAsyncResult - - - + + + - - + [System.Runtime.CompilerServices.Nullable(2)] @@ -1983,7 +1974,7 @@ This method populates the instance with data ga - + [System.Runtime.CompilerServices.Nullable(2)] @@ -1997,7 +1988,6 @@ This method populates the instance with data ga The zero-based position in the parameter at which to store the received data. The number of bytes to receive. A bitwise combination of the values. - A bitwise combination of the values. An delegate that references the method to invoke when the operation is complete. A user-defined object that contains information about the receive operation. This object is passed to the delegate when the operation is complete. Begins to asynchronously receive data from a connected . @@ -2104,7 +2094,7 @@ This method populates the instance with data ga System.IAsyncResult - + [System.Runtime.CompilerServices.Nullable(1)] @@ -2112,23 +2102,19 @@ This method populates the instance with data ga - - + + - - - - + + An array of type that is the storage location for the received data. The location in to store the received data. The number of bytes to receive. A bitwise combination of the values. - A bitwise combination of the values. A object that stores the socket error. - A object that stores the socket error. An delegate that references the method to invoke when the operation is complete. A user-defined object that contains information about the receive operation. This object is passed to the delegate when the operation is complete. Begins to asynchronously receive data from a connected . @@ -2230,14 +2216,12 @@ This method populates the instance with data ga System.IAsyncResult - - - + + + - - - + [System.Runtime.CompilerServices.Nullable(2)] @@ -2245,7 +2229,7 @@ This method populates the instance with data ga - + [System.Runtime.CompilerServices.Nullable(2)] @@ -2259,9 +2243,7 @@ This method populates the instance with data ga The zero-based position in the parameter at which to store the data. The number of bytes to receive. A bitwise combination of the values. - A bitwise combination of the values. A reference to an of the same type as the endpoint of the remote host to be updated on synchronous receive. - A reference to an of the same type as the endpoint of the remote host to be updated on synchronous receive. The delegate. An object that contains state information for this request. Begins to asynchronously receive data from a specified network device. @@ -2369,12 +2351,12 @@ This method populates the instance with data ga System.IAsyncResult - - - - - - + + + + + + [System.Runtime.CompilerServices.Nullable(2)] @@ -2382,7 +2364,7 @@ This method populates the instance with data ga - + [System.Runtime.CompilerServices.Nullable(2)] @@ -2505,7 +2487,7 @@ This method populates the instance with data ga System.IAsyncResult - + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 0 })] @@ -2513,9 +2495,9 @@ This method populates the instance with data ga - - - + + + An array of type that contains the data to send. @@ -2617,7 +2599,7 @@ This method populates the instance with data ga System.IAsyncResult - + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 0 })] @@ -2625,10 +2607,10 @@ This method populates the instance with data ga - - - - + + + + An array of type that contains the data to send. @@ -2731,7 +2713,7 @@ This method populates the instance with data ga System.IAsyncResult - + [System.Runtime.CompilerServices.Nullable(1)] @@ -2739,12 +2721,12 @@ This method populates the instance with data ga - - - - - - + + + + + + An array of type that contains the data to send. @@ -2856,12 +2838,11 @@ This method populates the instance with data ga System.IAsyncResult - - - + + + - - + [System.Runtime.CompilerServices.Nullable(2)] @@ -2869,7 +2850,7 @@ This method populates the instance with data ga - + [System.Runtime.CompilerServices.Nullable(2)] @@ -2883,7 +2864,6 @@ This method populates the instance with data ga The zero-based position in the parameter at which to begin sending data. The number of bytes to send. A bitwise combination of the values. - A bitwise combination of the values. The delegate. An object that contains state information for this request. Sends data asynchronously to a connected . @@ -3004,9 +2984,9 @@ This method populates the instance with data ga System.IAsyncResult - - - + + + A string that contains the path and name of the file to send. This parameter can be . @@ -3090,12 +3070,12 @@ This method populates the instance with data ga System.IAsyncResult - - - - - - + + + + + + A string that contains the path and name of the file to be sent. This parameter can be . @@ -3183,14 +3163,12 @@ This method populates the instance with data ga System.IAsyncResult - - - + + + - - - + [System.Runtime.CompilerServices.Nullable(2)] @@ -3198,7 +3176,7 @@ This method populates the instance with data ga - + [System.Runtime.CompilerServices.Nullable(2)] @@ -3212,9 +3190,7 @@ This method populates the instance with data ga The zero-based position in at which to begin sending data. The number of bytes to send. A bitwise combination of the values. - A bitwise combination of the values. An that represents the remote device. - An that represents the remote device. The delegate. An object that contains state information for this request. Sends data asynchronously to a specific remote host. @@ -3616,7 +3592,7 @@ This method populates the instance with data ga System.Void - + Wait up to milliseconds to send any remaining data, then close the socket. @@ -3701,7 +3677,7 @@ This method populates the instance with data ga System.Void - + An that represents the remote device. @@ -3790,8 +3766,8 @@ This method populates the instance with data ga System.Void - - + + The IP address of the remote host. @@ -3874,8 +3850,8 @@ This method populates the instance with data ga System.Void - - + + The IP addresses of the remote host. @@ -3956,8 +3932,8 @@ This method populates the instance with data ga System.Void - - + + The name of the remote host. @@ -4712,7 +4688,7 @@ This method populates the instance with data ga System.Void - + @@ -4785,7 +4761,7 @@ This method populates the instance with data ga System.Boolean - + The object to use for this asynchronous socket operation. @@ -5136,7 +5112,7 @@ This method populates the instance with data ga System.Net.Sockets.SocketInformation - + The ID of the target process where a duplicate of the socket reference is created. @@ -5278,8 +5254,8 @@ Duplication of the socket reference failed.
System.Net.Sockets.Socket - - + + An array of type that contains the bytes transferred. @@ -5360,11 +5336,9 @@ Duplication of the socket reference failed.
- An that stores state information for this asynchronous operation as well as any user defined data. - An that stores state information for this asynchronous operation as well as any user defined data. Asynchronously accepts an incoming connection attempt and creates a new to handle remote host communication. A to handle communication with the remote host. @@ -5440,9 +5414,9 @@ Duplication of the socket reference failed.
System.Net.Sockets.Socket - - - + + + An array of type that contains the bytes transferred. @@ -5522,11 +5496,9 @@ Duplication of the socket reference failed.
- An that stores state information and any user defined data for this asynchronous operation. - An that stores state information and any user defined data for this asynchronous operation. Ends a pending asynchronous connection request. System.Void - + An object that stores state information and any user-defined data for this asynchronous operation. @@ -5685,11 +5657,9 @@ Duplication of the socket reference failed.
- An that stores state information and any user defined data for this asynchronous operation. - An that stores state information and any user defined data for this asynchronous operation. Ends a pending asynchronous read. The number of bytes received. @@ -5770,8 +5740,8 @@ Duplication of the socket reference failed.
System.Int32 - - + + An that stores state information and any user defined data for this asynchronous operation. @@ -5858,15 +5828,11 @@ Duplication of the socket reference failed.
- - An that stores state information and any user defined data for this asynchronous operation. - An that stores state information and any user defined data for this asynchronous operation. The source . - The source . Ends a pending asynchronous read from a specific endpoint. If successful, the number of bytes received. If unsuccessful, returns 0. @@ -5939,10 +5905,10 @@ Duplication of the socket reference failed.
System.Int32 - - - - + + + + An that stores state information and any user defined data for this asynchronous operation. @@ -6034,11 +6000,9 @@ Duplication of the socket reference failed.
- An that stores state information for this asynchronous operation. - An that stores state information for this asynchronous operation. Ends a pending asynchronous send. If successful, the number of bytes sent to the ; otherwise, an invalid error. @@ -6124,8 +6088,8 @@ Duplication of the socket reference failed.
System.Int32 - - + + An that stores state information for this asynchronous operation. @@ -6215,7 +6179,7 @@ Duplication of the socket reference failed.
System.Void - + An object that stores state information for this asynchronous operation. @@ -6293,11 +6257,9 @@ Duplication of the socket reference failed.
- An that stores state information and any user defined data for this asynchronous operation. - An that stores state information and any user defined data for this asynchronous operation. Ends a pending asynchronous send to a specific location. If successful, the number of bytes sent; otherwise, an invalid error. @@ -6606,8 +6568,8 @@ In general, the `GetSocketOption` method should be used whenever getting a System.Object - - + + One of the values. @@ -6687,9 +6649,9 @@ In general, the `GetSocketOption` method should be used whenever getting a System.Void - - - + + + One of the values. @@ -6768,9 +6730,9 @@ In general, the `GetSocketOption` method should be used whenever getting a System.Byte[] - - - + + + One of the values. @@ -6911,9 +6873,9 @@ In general, the `GetSocketOption` method should be used whenever getting a System.Int32 - - - + + + An value that specifies the control code of the operation to perform. @@ -6994,9 +6956,9 @@ In general, the `GetSocketOption` method should be used whenever getting a System.Int32 - - - + + + A value that specifies the control code of the operation to perform. @@ -7701,8 +7663,8 @@ The maximum length of the pending connections queue is determined automatically. System.Boolean - - + + The time to wait for a response, in microseconds. @@ -7900,7 +7862,7 @@ The maximum length of the pending connections queue is determined automatically. System.Int32 - + An array of type that is the storage location for the received data. @@ -7995,7 +7957,7 @@ The maximum length of the pending connections queue is determined automatically. System.Int32 - + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 0 })] @@ -8153,8 +8115,8 @@ This member outputs trace information when you enable network tracing in your ap System.Int32 - - + + An array of type that is the storage location for the received data. @@ -8244,7 +8206,7 @@ This member outputs trace information when you enable network tracing in your ap System.Int32 - + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 0 })] @@ -8252,7 +8214,7 @@ This member outputs trace information when you enable network tracing in your ap - + A list of s of type that contains the received data. @@ -8431,9 +8393,9 @@ This member outputs trace information when you enable network tracing in your ap System.Int32 - - - + + + An array of type that is the storage location for the received data. @@ -8526,7 +8488,7 @@ This member outputs trace information when you enable network tracing in your ap System.Int32 - + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 0 })] @@ -8534,8 +8496,8 @@ This member outputs trace information when you enable network tracing in your ap - - + + A list of s of type that contains the received data. @@ -8704,10 +8666,10 @@ If you're using a connectionless , System.Int32 - - - - + + + + An array of type that is the storage location for received data. @@ -8820,11 +8782,11 @@ If you're using a connectionless , System.Int32 - - - - - + + + + + An array of type that is the storage location for the received data. @@ -9361,8 +9323,8 @@ If you're using a connectionless , System.Int32 - - + + An array of type that is the storage location for received data. @@ -9519,9 +9481,9 @@ If you're using a connectionless , System.Int32 - - - + + + An array of type that is the storage location for the received data. @@ -9744,10 +9706,10 @@ If you're using a connectionless , System.Int32 - - - - + + + + An array of type that is the storage location for received data. @@ -9863,11 +9825,11 @@ If you're using a connectionless , System.Int32 - - - - - + + + + + An array of type that is the storage location for received data. @@ -10420,12 +10382,12 @@ You must call the Bind method before performing this operation.
System.Int32 - - - - - - + + + + + + An array of type that is the storage location for received data. @@ -10540,7 +10502,7 @@ You must call the Bind method before performing this operation.
System.Boolean - + The object to use for this asynchronous socket operation. @@ -11043,10 +11005,10 @@ You must call the Bind method before performing this operation.
System.Void - - - - + + + + An of instances to check for readability. @@ -11207,7 +11169,7 @@ You must call the Bind method before performing this operation.
System.Int32 - + An array of type that contains the data to be sent. @@ -11301,7 +11263,7 @@ You must call the Bind method before performing this operation.
System.Int32 - + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 0 })] @@ -11464,8 +11426,8 @@ This member outputs trace information when you enable network tracing in your ap System.Int32 - - + + An array of type that contains the data to be sent. @@ -11554,7 +11516,7 @@ This member outputs trace information when you enable network tracing in your ap System.Int32 - + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 0 })] @@ -11562,7 +11524,7 @@ This member outputs trace information when you enable network tracing in your ap - + A list of s of type that contains the data to be sent. @@ -11707,9 +11669,9 @@ This member outputs trace information when you enable network tracing in your ap System.Int32 - - - + + + An array of type that contains the data to be sent. @@ -11804,7 +11766,7 @@ The following code example sends the data found in buffer, and specifies System.Int32 - + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 1, 0 })] @@ -11812,8 +11774,8 @@ The following code example sends the data found in buffer, and specifies - - + + A list of s of type that contains the data to be sent. @@ -11972,10 +11934,10 @@ This member outputs trace information when you enable network tracing in your ap System.Int32 - - - - + + + + An array of type that contains the data to be sent. @@ -12087,11 +12049,11 @@ This member outputs trace information when you enable network tracing in your ap System.Int32 - - - - - + + + + + An array of type that contains the data to be sent. @@ -12654,7 +12616,7 @@ This member outputs trace information when you enable network tracing in your ap System.Void - + A that contains the path and name of the file to be sent. This parameter can be . @@ -12738,10 +12700,10 @@ This member outputs trace information when you enable network tracing in your ap System.Void - - - - + + + + The path and name of the file to be sent. This parameter can be . @@ -12999,7 +12961,7 @@ This member outputs trace information when you enable network tracing in your ap System.Boolean - + The object to use for this asynchronous socket operation. @@ -13160,8 +13122,8 @@ This member outputs trace information when you enable network tracing in your ap System.Int32 - - + + An array of type that contains the data to be sent. @@ -13308,9 +13270,9 @@ This member outputs trace information when you enable network tracing in your ap System.Int32 - - - + + + An array of type that contains the data to be sent. @@ -13522,10 +13484,10 @@ This member outputs trace information when you enable network tracing in your ap System.Int32 - - - - + + + + An array of type that contains the data to be sent. @@ -13619,11 +13581,11 @@ This member outputs trace information when you enable network tracing in your ap System.Int32 - - - - - + + + + + An array of type that contains the data to be sent. @@ -14111,7 +14073,7 @@ This member outputs trace information when you enable network tracing in your ap System.Void - + The IP protection level to set on this socket. @@ -14248,9 +14210,9 @@ The System.Void - - - + + + One of the values. @@ -14359,9 +14321,9 @@ The System.Void - - - + + + One of the values. @@ -14435,9 +14397,9 @@ The System.Void - - - + + + One of the values. @@ -14577,9 +14539,9 @@ The System.Void - - - + + + One of the values. diff --git a/xml/System.Net.Sockets/SocketException.xml b/xml/System.Net.Sockets/SocketException.xml index 0b5dc8323c5..f74a2a1a18d 100644 --- a/xml/System.Net.Sockets/SocketException.xml +++ b/xml/System.Net.Sockets/SocketException.xml @@ -68,13 +68,13 @@ The exception that is thrown when a socket error occurs. - is thrown by the and classes when an error occurs with the network. - - The parameterless constructor for the class sets the property to the last operating system socket error that occurred. For more information about socket error codes, see the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation. - + is thrown by the and classes when an error occurs with the network. + + The parameterless constructor for the class sets the property to the last operating system socket error that occurred. For more information about socket error codes, see the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation. + ]]> @@ -128,11 +128,11 @@ Initializes a new instance of the class with the last operating system error code. - constructor sets the property to the last operating system socket error that occurred. For more information about socket error codes, see the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation. - + constructor sets the property to the last operating system socket error that occurred. For more information about socket error codes, see the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation. + ]]> @@ -185,11 +185,11 @@ The error code that indicates the error that occurred. Initializes a new instance of the class with the specified error code. - constructor sets the property to `errorCode`. - + constructor sets the property to `errorCode`. + ]]> @@ -282,19 +282,19 @@ - - + + A instance that contains the information that is required to serialize the new instance. A that contains the source of the serialized stream that is associated with the new instance. Initializes a new instance of the class from the specified instances of the and classes. - interface for the class. - + interface for the class. + ]]> XML and SOAP Serialization @@ -341,13 +341,13 @@ Gets the error code that is associated with this exception. An integer error code that is associated with this exception. - property contains the error code that is associated with the error that caused the exception. - - The parameterless constructor for sets the property to the last operating system error that occurred. For more information about socket error codes, see the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation. - + property contains the error code that is associated with the error that caused the exception. + + The parameterless constructor for sets the property to the last operating system error that occurred. For more information about socket error codes, see the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation. + ]]> @@ -436,13 +436,13 @@ Gets the error code that is associated with this exception. An integer error code that is associated with this exception. - property contains the error code that is associated with the error that caused the exception. - - The parameterless constructor for sets the property to the last operating system error that occurred. For more information about socket error codes, see the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation. - + property contains the error code that is associated with the error that caused the exception. + + The parameterless constructor for sets the property to the last operating system error that occurred. For more information about socket error codes, see the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation. + ]]> diff --git a/xml/System.Net.WebSockets/ClientWebSocketOptions.xml b/xml/System.Net.WebSockets/ClientWebSocketOptions.xml index 95aa891c803..032b5b87018 100644 --- a/xml/System.Net.WebSockets/ClientWebSocketOptions.xml +++ b/xml/System.Net.WebSockets/ClientWebSocketOptions.xml @@ -53,30 +53,6 @@ To be added. - - - - - - - Constructor - - System - 2.0.5.0 - 4.0.0.0 - - - System.Net.WebSockets.Client - - - netstandard - - - - To be added. - To be added. - - diff --git a/xml/System.Net.WebSockets/HttpListenerWebSocketContext.xml b/xml/System.Net.WebSockets/HttpListenerWebSocketContext.xml index 8b00207f1aa..12204e65891 100644 --- a/xml/System.Net.WebSockets/HttpListenerWebSocketContext.xml +++ b/xml/System.Net.WebSockets/HttpListenerWebSocketContext.xml @@ -52,30 +52,6 @@ To be added. - - - - - - - Constructor - - System - 2.0.5.0 - 4.0.0.0 - - - System.Net.HttpListener - - - netstandard - - - - To be added. - To be added. - - diff --git a/xml/System.Net/CookieCollection.xml b/xml/System.Net/CookieCollection.xml index b7be6ba22c7..37e3bcfebf7 100644 --- a/xml/System.Net/CookieCollection.xml +++ b/xml/System.Net/CookieCollection.xml @@ -94,11 +94,11 @@ Provides a collection container for instances of the class. - class implements an interface to provide a general mechanism for handling collections of cookies. For example, this is useful in the case where an application is designed to store cookies for multiple servers. - + class implements an interface to provide a general mechanism for handling collections of cookies. For example, this is useful in the case where an application is designed to store cookies for multiple servers. + ]]> @@ -148,17 +148,17 @@ Initializes a new instance of the class. - . - -|Property|Default| -|--------------|-------------| -||`true`| -||0| -||`false`| - + . + +|Property|Default| +|--------------|-------------| +||`true`| +||0| +||`false`| + ]]> @@ -286,11 +286,11 @@ The to be added. Adds the contents of a to the current instance. - is read from the `cookies` parameter and added to the current instance. - + is read from the `cookies` parameter and added to the current instance. + ]]> @@ -381,9 +381,9 @@ if the specified cookie is found in the ; otherwise, . - , and match. The comparison for and is case-insensitive. The comparison for is case-sensitive. @@ -443,19 +443,19 @@ The comparison for is case-sensitive. System.Void - - + + The target array to which the will be copied. The zero-based index in the target array where copying begins. Copies the elements of a to the specified array, starting at a particular index. - `array` parameter must be one-dimensional with zero-based indexing. - + `array` parameter must be one-dimensional with zero-based indexing. + ]]> @@ -463,10 +463,10 @@ The comparison for is case-sensitive. is less than zero. - is multidimensional. - - -or- - + is multidimensional. + + -or- + The number of elements in this is greater than the available space from to the end of the destination . The elements in this cannot be cast automatically to the type of the destination . @@ -514,19 +514,19 @@ The comparison for is case-sensitive. System.Void - - + + The target array to which the will be copied. The zero-based index in the target array where copying begins. Copies the elements of this to a array starting at the specified index of the target array. - @@ -534,10 +534,10 @@ The comparison for is case-sensitive. is less than zero. - is multidimensional. - - -or- - + is multidimensional. + + -or- + The number of elements in this is greater than the available space from to the end of the destination . The elements in this cannot be cast automatically to the type of the destination . @@ -645,13 +645,13 @@ The comparison for is case-sensitive. Gets an enumerator that can iterate through a . An for this collection. - only to read data in the collection. Enumerators cannot be used to modify the underlying collection. The enumerator does not have exclusive access to the collection. - - When an enumerator is created, it takes a snapshot of the current state of the collection. If changes are made to the collection, such as adding, modifying, or deleting elements, this snapshot gets out of sync and the enumerator throws an . Two enumerators created from the same collection at the same time can produce different snapshots of the collection. - + only to read data in the collection. Enumerators cannot be used to modify the underlying collection. The enumerator does not have exclusive access to the collection. + + When an enumerator is created, it takes a snapshot of the current state of the collection. If changes are made to the collection, such as adding, modifying, or deleting elements, this snapshot gets out of sync and the enumerator throws an . Two enumerators created from the same collection at the same time can produce different snapshots of the collection. + ]]> @@ -807,25 +807,25 @@ The comparison for is case-sensitive. System.Net.Cookie - + The zero-based index of the to be found. Gets the with a specific index from a . A with a specific index from a . - . - - - -## Examples + . + + + +## Examples :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/CookieCollection_Item_2/CPP/CookieCollection_Item_2.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Net/CookieCollection/Item/cookiecollection_item_2.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/CookieCollection_Item_2/VB/cookiecollection_item_2.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/CookieCollection_Item_2/VB/cookiecollection_item_2.vb" id="Snippet1"::: + ]]> @@ -890,18 +890,18 @@ The comparison for is case-sensitive. Gets the with a specific name from a . The with a specific name from a . - . - - - -## Examples + . + + + +## Examples :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/CookieCollection_Item_1/CPP/CookieCollection_Item_1.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Net/CookieCollection/Item/cookiecollection_item_1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/CookieCollection_Item_1/VB/cookiecollection_item_1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/CookieCollection_Item_1/VB/cookiecollection_item_1.vb" id="Snippet1"::: + ]]> @@ -953,9 +953,9 @@ The comparison for is case-sensitive. if was successfully removed from the ; otherwise, . This method also returns if item is not found in the original collection. - , and match. The comparison for and is case-insensitive. @@ -1009,11 +1009,11 @@ The comparison for is case-sensitive. Gets an object to synchronize access to the . An object to synchronize access to the . - property returns an object that can be used to synchronize access to the . - + property returns an object that can be used to synchronize access to the . + ]]> @@ -1057,15 +1057,15 @@ The comparison for is case-sensitive. Gets an enumerator that can iterate through the . An for this collection. - only to read data in the collection. Enumerators cannot be used to modify the underlying collection. The enumerator does not have exclusive access to the collection. - - When an enumerator is created, it takes a snapshot of the current state of the collection. If changes are made to the collection, such as adding, modifying, or deleting elements, this snapshot gets out of sync and the enumerator throws an . Two enumerators created from the same collection at the same time can produce different snapshots of the collection. + only to read data in the collection. Enumerators cannot be used to modify the underlying collection. The enumerator does not have exclusive access to the collection. + + When an enumerator is created, it takes a snapshot of the current state of the collection. If changes are made to the collection, such as adding, modifying, or deleting elements, this snapshot gets out of sync and the enumerator throws an . Two enumerators created from the same collection at the same time can produce different snapshots of the collection. This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - + ]]> @@ -1108,11 +1108,11 @@ The comparison for is case-sensitive. The zero-based index in the target array where copying begins. Copies the elements of a to the specified array, starting at a particular index. - `array` parameter must be one-dimensional with zero-based indexing. - + `array` parameter must be one-dimensional with zero-based indexing. + ]]> @@ -1120,10 +1120,10 @@ The comparison for is case-sensitive. is less than zero. - is multidimensional. - - -or- - + is multidimensional. + + -or- + The number of elements in this is greater than the available space from to the end of the destination . The elements in this cannot be cast automatically to the type of the destination . @@ -1205,11 +1205,11 @@ This member is an explicit interface member implementation. It can be used only Gets an object to synchronize access to the . An object to synchronize access to the . - property returns an object that can be used to synchronize access to the . - + property returns an object that can be used to synchronize access to the . + ]]> diff --git a/xml/System.Net/CookieContainer.xml b/xml/System.Net/CookieContainer.xml index be1aa4f200f..34b4f8c270d 100644 --- a/xml/System.Net/CookieContainer.xml +++ b/xml/System.Net/CookieContainer.xml @@ -70,15 +70,15 @@ Provides a container for a collection of objects. - is a data structure that provides storage for instances of the class, and which is accessed in a database-like manner. The has a capacity limit that is set when the container is created or changed by a property. - - An instance of the class is added to the container based on its originating URI. It is added to an internal associated with the URI. A is retrieved from the container based on the URI as a , or as a string that can be used to submit HTTP WebRequests. - - The has three properties that govern the volume of the content of the container: , , and . These values have the default settings of 300, 4096, and 20 respectively. When a is added to the container, these properties are used to determine whether a already contained in the should be discarded to make room for the new one. The keeps track of each addition to ensure that neither the nor the limits are exceeded. If one or both are exceeded, then instances held by the are removed. First, any expired is removed. If further capacity must be recaptured, then the least-recently used is purged. - + is a data structure that provides storage for instances of the class, and which is accessed in a database-like manner. The has a capacity limit that is set when the container is created or changed by a property. + + An instance of the class is added to the container based on its originating URI. It is added to an internal associated with the URI. A is retrieved from the container based on the URI as a , or as a string that can be used to submit HTTP WebRequests. + + The has three properties that govern the volume of the content of the container: , , and . These values have the default settings of 300, 4096, and 20 respectively. When a is added to the container, these properties are used to determine whether a already contained in the should be discarded to make room for the new one. The keeps track of each addition to ensure that neither the nor the limits are exceeded. If one or both are exceeded, then instances held by the are removed. First, any expired is removed. If further capacity must be recaptured, then the least-recently used is purged. + ]]> @@ -140,11 +140,11 @@ Initializes a new instance of the class. - is used to initialize , is used for , and is used for . - + is used to initialize , is used for , and is used for . + ]]> @@ -188,17 +188,17 @@ System.Net - + The number of instances that the can hold. Initializes a new instance of the class with a specified value for the number of instances that the container can hold. - is initialized to 20, and is initialized to 4096. - + is initialized to 20, and is initialized to 4096. + ]]> @@ -244,9 +244,9 @@ System.Net - - - + + + The number of instances that the can hold. @@ -254,18 +254,18 @@ The maximum size in bytes for any single in a . Initializes a new instance of the class with specific properties. - , , and . - + , , and . + ]]> - is not equal to Int32.MaxValue. - - and - + is not equal to Int32.MaxValue. + + and + is less than or equal to zero or is greater than . is less than or equal to zero. @@ -323,27 +323,27 @@ System.Void - + The to be added to the . Adds a to a . This method uses the domain from the to determine which domain collection to associate the with. - property equals or exceeds the property, one or more instances are removed from the container before adding the `cookie` parameter. Enough instances are removed to bring below as follows: if there are expired instances in the given scope, they are cleaned up. If not, then the least recently used is found and removed from the container. - + property equals or exceeds the property, one or more instances are removed from the container before adding the `cookie` parameter. Enough instances are removed to bring below as follows: if there are expired instances in the given scope, they are cleaned up. If not, then the least recently used is found and removed from the container. + ]]> is . The domain for is or the empty string (""). - is larger than . - - -or- - + is larger than . + + -or- + the domain for is not a valid URI. @@ -389,17 +389,17 @@ System.Void - + The to be added to the . Adds the contents of a to the . - property equals the property, one or more instances are removed from the container before adding the contents of the `cookies` parameter. Enough instances are removed to make room for `cookies` as follows: if there are expired instances, they are cleaned up. If not, or if more room is needed, then the least recently used is found and removed from the container. - + property equals the property, one or more instances are removed from the container before adding the contents of the `cookies` parameter. Enough instances are removed to make room for `cookies` as follows: if there are expired instances, they are cleaned up. If not, or if more room is needed, then the least recently used is found and removed from the container. + ]]> @@ -459,26 +459,26 @@ The to be added to the . Adds a to the for a particular URI. - instance for just one specific host, do not set the property of the instance. This is set automatically, based on the URI. - - If your URI corresponds to your local domain and sends to all the hosts on the local domain, set the property equal to ".local". Otherwise, make sure it matches the host name used in the URI. - - If the property of a is Netscape, the property of the , if not set explicitly, is derived from the URI and is the complete path from the URI, including the page name. - - If the property equals the property, one or more instances are removed from the container before adding the `cookie` parameter. Enough instances are removed to bring below as follows: if there are expired instances in scope, they are cleaned up. If not, then the least recently used is found and removed from the container. - + instance for just one specific host, do not set the property of the instance. This is set automatically, based on the URI. + + If your URI corresponds to your local domain and sends to all the hosts on the local domain, set the property equal to ".local". Otherwise, make sure it matches the host name used in the URI. + + If the property of a is Netscape, the property of the , if not set explicitly, is derived from the URI and is the complete path from the URI, including the page name. + + If the property equals the property, one or more instances are removed from the container before adding the `cookie` parameter. Enough instances are removed to bring below as follows: if there are expired instances in scope, they are cleaned up. If not, then the least recently used is found and removed from the container. + ]]> is or is . - is larger than . - - -or- - + is larger than . + + -or- + The domain for is not a valid URI. @@ -535,15 +535,15 @@ The to be added to the . Adds the contents of a to the for a particular URI. - instance for just one specific host, do not set the property of the instance. This is set automatically, based on the URI. - - If your URI corresponds to your local domain and sends to all the hosts on the local domain, set the property equal to ".local". Otherwise, make sure it matches the host name used in the URI. - - If equals , one or more instances is removed from the container before adding the `cookie` parameter. Enough instances are removed to bring below as follows: if there are expired instances in scope they are cleaned up. If not, then the least recently used is found and removed from the container. - + instance for just one specific host, do not set the property of the instance. This is set automatically, based on the URI. + + If your URI corresponds to your local domain and sends to all the hosts on the local domain, set the property equal to ".local". Otherwise, make sure it matches the host name used in the URI. + + If equals , one or more instances is removed from the container before adding the `cookie` parameter. Enough instances are removed to bring below as follows: if there are expired instances in scope they are cleaned up. If not, then the least recently used is found and removed from the container. + ]]> @@ -610,13 +610,13 @@ Gets or sets the number of instances that a can hold. The number of instances that a can hold. This is a hard limit and cannot be exceeded by adding a . - equals or exceeds , one or more instances are removed from the container. Enough instances are removed to bring below as follows: if there are expired instances in scope, they are cleaned up. If not, then the least recently used is found and removed from the container. - - must be greater than or equal to . - + equals or exceeds , one or more instances are removed from the container. Enough instances are removed to bring below as follows: if there are expired instances in scope, they are cleaned up. If not, then the least recently used is found and removed from the container. + + must be greater than or equal to . + ]]> @@ -677,11 +677,11 @@ Gets the number of instances that a currently holds. The number of instances that a currently holds. This is the total of instances in all domains. - . If equals or exceeds , one or more instances are removed from the container. Enough instances are removed to bring below as follows: if there are expired instances in scope, they are cleaned up. If not, then the least recently used is found and removed from the container. - + . If equals or exceeds , one or more instances are removed from the container. Enough instances are removed to bring below as follows: if there are expired instances in scope, they are cleaned up. If not, then the least recently used is found and removed from the container. + ]]> @@ -734,11 +734,11 @@ Represents the default maximum size, in bytes, of the instances that the can hold. This field is constant. - size is 4096. - + size is 4096. + ]]> @@ -791,11 +791,11 @@ Represents the default maximum number of instances that the can hold. This field is constant. - instances is 300. - + instances is 300. + ]]> @@ -847,11 +847,11 @@ Represents the default maximum number of instances that the can reference per domain. This field is constant. - instances per domain is 20. - + instances per domain is 20. + ]]> @@ -942,13 +942,13 @@ Gets the HTTP cookie header that contains the HTTP cookies that represent the instances that are associated with a specific URI. An HTTP cookie header, with strings representing instances delimited by semicolons. - returns a string that holds the HTTP cookie header for the instances specified by `uri`. The HTTP header is built by adding a string representation of each associated with `uri`. Note that the exact format of the string depends on the RFC that the conforms to. The strings for all the instances that are associated with `uri` are combined and delimited by semicolons. - - This string is not in the correct format for use as the second parameter of the method. - + returns a string that holds the HTTP cookie header for the instances specified by `uri`. The HTTP header is built by adding a string representation of each associated with `uri`. Note that the exact format of the string depends on the RFC that the conforms to. The strings for all the instances that are associated with `uri` are combined and delimited by semicolons. + + This string is not in the correct format for use as the second parameter of the method. + ]]> @@ -1007,11 +1007,11 @@ Gets a that contains the instances that are associated with a specific URI. A that contains the instances that are associated with a specific URI. - is created. Then the instances in the internal collection that are associated with the specified URI are read out and added to the new . - + is created. Then the instances in the internal collection that are associated with the specified URI are read out and added to the new . + ]]> @@ -1076,11 +1076,11 @@ Represents the maximum allowed length of a . The maximum allowed length, in bytes, of a . - is less than the current value, any with a length that exceeds the new value will be truncated. - + is less than the current value, any with a length that exceeds the new value will be truncated. + ]]> @@ -1145,18 +1145,18 @@ Gets or sets the number of instances that a can hold per domain. The number of instances that are allowed per domain. - value is less than the current value, and if any of the domain collections contain more instances than the new value, the collections are pruned to fit. This uses the same basic rules as described in the property. However, this does the clean-up only on the collection for this domain. - + value is less than the current value, and if any of the domain collections contain more instances than the new value, the collections are pruned to fit. This uses the same basic rules as described in the property. However, this does the clean-up only on the collection for this domain. + ]]> - is less than or equal to zero. - - -or- - + is less than or equal to zero. + + -or- + is greater than the maximum allowable number of cookies instances, 300, and is not equal to Int32.MaxValue). @@ -1213,19 +1213,19 @@ The contents of an HTTP set-cookie header as returned by a HTTP server, with instances delimited by commas. Adds instances for one or more cookies from an HTTP cookie header to the for a specific URI. - pulls all the HTTP cookies out of the HTTP cookie header, builds a for each one, and then adds each to the internal that is associated with the URI. The HTTP cookies in the `cookieHeader` string must be delimited by commas. - + pulls all the HTTP cookies out of the HTTP cookie header, builds a for each one, and then adds each to the internal that is associated with the URI. The HTTP cookies in the `cookieHeader` string must be delimited by commas. + ]]> or is . - One of the cookies is invalid. - - -or- - + One of the cookies is invalid. + + -or- + An error occurred while adding one of the cookies to the container. diff --git a/xml/System.Net/CookieException.xml b/xml/System.Net/CookieException.xml index f9ce74942f1..b8224946a56 100644 --- a/xml/System.Net/CookieException.xml +++ b/xml/System.Net/CookieException.xml @@ -64,25 +64,25 @@ The exception that is thrown when an error is made adding a to a . - a with length greater than to a . - - **Associated Tips** - - **Make sure the cookie size does not exceed the maximum allowed by the cookie container.** - This exception is thrown when an attempt is made to add a with length greater than to a . The default maximum cookie size is 4096 bytes. - - **When setting the Name property for a cookie, make sure the value is not a null reference or empty string.** - The property must be initialized before using an instance of the class. The following characters are reserved and cannot be used for this attribute value: equal sign, semicolon, comma, new line (\n), carriage return (\r), tab (\t). The dollar sign ($) character cannot be the first character. - - **When setting the Port property for a cookie, make sure the value is valid and enclosed in double quotes.** - The attribute restricts the ports to which a cookie may be sent. The default value means no restriction. Setting the property to an empty string ("") restricts the port to the one used in the HTTP response. Otherwise the value must be a string in quotation marks that contains port values delineated with commas. - - **When setting the Value property for a cookie, make sure the value is not null.** - The following characters are reserved and cannot be used for this property: semicolon, comma. - + a with length greater than to a . + + **Associated Tips** + + **Make sure the cookie size does not exceed the maximum allowed by the cookie container.** + This exception is thrown when an attempt is made to add a with length greater than to a . The default maximum cookie size is 4096 bytes. + + **When setting the Name property for a cookie, make sure the value is not a null reference or empty string.** + The property must be initialized before using an instance of the class. The following characters are reserved and cannot be used for this attribute value: equal sign, semicolon, comma, new line (\n), carriage return (\r), tab (\t). The dollar sign ($) character cannot be the first character. + + **When setting the Port property for a cookie, make sure the value is valid and enclosed in double quotes.** + The attribute restricts the ports to which a cookie may be sent. The default value means no restriction. Setting the property to an empty string ("") restricts the port to the one used in the HTTP response. Otherwise the value must be a string in quotation marks that contains port values delineated with commas. + + **When setting the Value property for a cookie, make sure the value is not null.** + The following characters are reserved and cannot be used for this property: semicolon, comma. + ]]> @@ -146,11 +146,11 @@ Initializes a new instance of the class. - . - + . + ]]> @@ -209,19 +209,19 @@ - - + + The to be used. The to be used. Initializes a new instance of the class with specific values of and . - @@ -278,19 +278,19 @@ System.Void - - + + The object that holds the serialized object data. The to populate with data. The contextual information about the source or destination. A that specifies the destination for this serialization. Populates a instance with the data needed to serialize the . - are automatically tracked and serialized by the formatter. - + are automatically tracked and serialized by the formatter. + ]]> @@ -336,8 +336,8 @@ System.Void - - + + The to be used. diff --git a/xml/System.Net/HttpListenerTimeoutManager.xml b/xml/System.Net/HttpListenerTimeoutManager.xml index a64a7b46cb9..550966c0851 100644 --- a/xml/System.Net/HttpListenerTimeoutManager.xml +++ b/xml/System.Net/HttpListenerTimeoutManager.xml @@ -40,11 +40,11 @@ The timeout manager to use for an object. - instance. - + instance. + ]]> @@ -52,30 +52,6 @@ - - - - - - - Constructor - - System - 2.0.5.0 - 4.0.0.0 - - - System.Net.HttpListener - - - netstandard - - - - To be added. - To be added. - - @@ -112,13 +88,13 @@ Gets or sets the time allowed for the to drain the entity body on a Keep-Alive connection. The time allowed for the to drain the entity body on a Keep-Alive connection. - starts draining the remainder of the entity body to reach another potentially pipelined request from the client. If the time to drain the remaining entity body exceeds the allowed period the connection is timed out. - + starts draining the remainder of the entity body to reach another potentially pipelined request from the client. If the time to drain the remaining entity body exceeds the allowed period the connection is timed out. + ]]> @@ -165,13 +141,13 @@ Gets or sets the time allowed for the request entity body to arrive. The time allowed for the request entity body to arrive. - turns on this timer when the request has an entity body. The timer expiration is initially set to the configured value. When the receives additional data indications on the request, it resets the timer to give the connection another interval. - + turns on this timer when the request has an entity body. The timer expiration is initially set to the configured value. When the receives additional data indications on the request, it resets the timer to give the connection another interval. + ]]> @@ -218,15 +194,15 @@ Gets or sets the time allowed for the to parse the request header. The time allowed for the to parse the request header. - . - - The system cannot determine the request queue or URL group that the request is associated with until the headers have been parsed. Therefore, the enforces the default timer for the first request on a connection. Subsequent requests on a Keep-Alive connection will use the value set on this property. - + . + + The system cannot determine the request queue or URL group that the request is associated with until the headers have been parsed. Therefore, the enforces the default timer for the first request on a connection. Subsequent requests on a Keep-Alive connection will use the value set on this property. + ]]> @@ -267,15 +243,15 @@ Gets or sets the time allowed for an idle connection. The time allowed for an idle connection. - . - - The system cannot determine the request queue or URL group that the request is associated with until the headers have been parsed. Therefore, the enforces the default timer for the first request on a connection. Subsequent requests on a Keep-Alive connection will use the value set on this property. - + . + + The system cannot determine the request queue or URL group that the request is associated with until the headers have been parsed. Therefore, the enforces the default timer for the first request on a connection. Subsequent requests on a Keep-Alive connection will use the value set on this property. + ]]> @@ -322,13 +298,13 @@ Gets or sets the minimum send rate, in bytes-per-second, for the response. The minimum send rate, in bytes-per-second, for the response. - to MAXULONG. - + to MAXULONG. + ]]> @@ -375,11 +351,11 @@ Gets or sets the time allowed for the request to remain in the request queue before the picks it up. The time allowed for the request to remain in the request queue before the picks it up. - diff --git a/xml/System.Net/HttpWebRequest.xml b/xml/System.Net/HttpWebRequest.xml index bd036d741e1..31f99f02bb8 100644 --- a/xml/System.Net/HttpWebRequest.xml +++ b/xml/System.Net/HttpWebRequest.xml @@ -203,36 +203,6 @@ Both constructors are obsolete and should not b To be added. - - - - - - - - Constructor - - System - 2.0.5.0 - - - System.Net.Requests - - - netstandard - - - System.Net - - - - - - To be added. - To be added. - To be added. - - @@ -294,8 +264,8 @@ Both constructors are obsolete and should not b - - + + A object that contains the information required to serialize the new object. @@ -511,7 +481,7 @@ Both constructors are obsolete and should not b System.Void - + The starting or ending point of the range. @@ -605,7 +575,7 @@ Both constructors are obsolete and should not b System.Void - + The starting or ending point of the range. @@ -686,8 +656,8 @@ Both constructors are obsolete and should not b System.Void - - + + The position at which to start sending data. @@ -784,8 +754,8 @@ Both constructors are obsolete and should not b System.Void - - + + The position at which to start sending data. @@ -875,8 +845,8 @@ Both constructors are obsolete and should not b System.Void - - + + The description of the range. @@ -966,8 +936,8 @@ Both constructors are obsolete and should not b System.Void - - + + The description of the range. @@ -1059,9 +1029,9 @@ Both constructors are obsolete and should not b System.Void - - - + + + The description of the range. @@ -1156,9 +1126,9 @@ Both constructors are obsolete and should not b System.Void - - - + + + The description of the range. @@ -2734,7 +2704,7 @@ Both constructors are obsolete and should not b System.IO.Stream - + @@ -2743,12 +2713,10 @@ Both constructors are obsolete and should not b - The pending request for a stream. The for the . - The for the . Ends an asynchronous request for a object to use to write data and outputs the associated with the stream. A to use to write request data. @@ -3021,8 +2989,8 @@ The GetHashCode method returns a hash code of the web request. This value can be System.Void - - + + The to populate with data. @@ -3191,7 +3159,7 @@ The GetHashCode method returns a hash code of the web request. This value can be System.IO.Stream - + [System.Runtime.CompilerServices.Nullable(2)] @@ -4890,8 +4858,8 @@ The GetHashCode method returns a hash code of the web request. This value can be System.Void - - + + The to populate with data. diff --git a/xml/System.Net/HttpWebResponse.xml b/xml/System.Net/HttpWebResponse.xml index a05c3ce1ae4..c7b1a4c73df 100644 --- a/xml/System.Net/HttpWebResponse.xml +++ b/xml/System.Net/HttpWebResponse.xml @@ -81,39 +81,39 @@ Provides an HTTP-specific implementation of the class. - class. The class is used to build HTTP stand-alone client applications that send HTTP requests and receive HTTP responses. - + class. The class is used to build HTTP stand-alone client applications that send HTTP requests and receive HTTP responses. + > [!NOTE] -> Do not confuse with the class that is used in ASP.NET applications and whose methods and properties are exposed through ASP.NET's intrinsic `Response` object. - - You should never directly create an instance of the class. Instead, use the instance returned by a call to . You must call either the or the method to close the response and release the connection for reuse. It is not necessary to call both and , but doing so does not cause an error. - - Common header information returned from the Internet resource is exposed as properties of the class. See the following table for a complete list. Other headers can be read from the property as name/value pairs. - - The following table shows the common HTTP headers that are available through properties of the class. - -|Header|Property| -|------------|--------------| -|Content-Encoding|| -|Content-Length|| -|Content-Type|| -|Last-Modified|| -|Server|| - -The contents of the response from the Internet resource are returned as a by calling the method. - - - -## Examples - The following example returns an from an . - +> Do not confuse with the class that is used in ASP.NET applications and whose methods and properties are exposed through ASP.NET's intrinsic `Response` object. + + You should never directly create an instance of the class. Instead, use the instance returned by a call to . You must call either the or the method to close the response and release the connection for reuse. It is not necessary to call both and , but doing so does not cause an error. + + Common header information returned from the Internet resource is exposed as properties of the class. See the following table for a complete list. Other headers can be read from the property as name/value pairs. + + The following table shows the common HTTP headers that are available through properties of the class. + +|Header|Property| +|------------|--------------| +|Content-Encoding|| +|Content-Length|| +|Content-Type|| +|Last-Modified|| +|Server|| + +The contents of the response from the Internet resource are returned as a by calling the method. + + + +## Examples + The following example returns an from an . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/Classic HttpWebResponse Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebResponse/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic HttpWebResponse Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic HttpWebResponse Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -239,19 +239,19 @@ The contents of the response from the Internet resource are returned as a - - + + A that contains the information required to serialize the new . A that contains the source of the serialized stream that is associated with the new . Initializes a new instance of the class from the specified and instances. - interface for the class. - + interface for the class. + ]]> @@ -309,20 +309,20 @@ The contents of the response from the Internet resource are returned as a Gets the character set of the response. A string that contains the character set of the response. - property contains a value that describes the character set of the response. This character set information is taken from the header returned with the response. - - - -## Examples - The following example obtains the character set of the response. - + property contains a value that describes the character set of the response. This character set information is taken from the header returned with the response. + + + +## Examples + The following example obtains the character set of the response. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/HttpWebResponse_ContentEncoding_CharacterSet/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebResponse/CharacterSet/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/HttpWebResponse_ContentEncoding_CharacterSet/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/HttpWebResponse_ContentEncoding_CharacterSet/VB/source.vb" id="Snippet1"::: + ]]> The current instance has been disposed. @@ -369,27 +369,27 @@ The contents of the response from the Internet resource are returned as a Closes the response stream. - method closes the response stream and releases the connection to the resource for reuse by other requests. - + method closes the response stream and releases the connection to the resource for reuse by other requests. + You should not access any properties of the object after the call to the `Close` method. On .NET Core, an is thrown. - You must call either the or the method to close the stream and release the connection for reuse. It is not necessary to call both and , but doing so does not cause an error. Failure to close the stream can cause your application to run out of connections. - + You must call either the or the method to close the stream and release the connection for reuse. It is not necessary to call both and , but doing so does not cause an error. Failure to close the stream can cause your application to run out of connections. + > [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). - - - -## Examples - The following example demonstrates how to close a . - +> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). + + + +## Examples + The following example demonstrates how to close a . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/HttpWebResponse_Close/CPP/httpwebresponse_close.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebResponse/Close/httpwebresponse_close.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/HttpWebResponse_Close/VB/httpwebresponse_close.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/HttpWebResponse_Close/VB/httpwebresponse_close.vb" id="Snippet1"::: + ]]> **.NET Core only:** This object has been disposed. @@ -436,20 +436,20 @@ The contents of the response from the Internet resource are returned as a Gets the method that is used to encode the body of the response. A string that describes the method that is used to encode the body of the response. - property contains the value of the Content-Encoding header returned with the response. - - - -## Examples - The following example uses the property to obtain the value of the Content-Encoding header returned with the response. - + property contains the value of the Content-Encoding header returned with the response. + + + +## Examples + The following example uses the property to obtain the value of the Content-Encoding header returned with the response. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/HttpWebResponse_ContentEncoding_CharacterSet/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebResponse/CharacterSet/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/HttpWebResponse_ContentEncoding_CharacterSet/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/HttpWebResponse_ContentEncoding_CharacterSet/VB/source.vb" id="Snippet1"::: + ]]> The current instance has been disposed. @@ -497,20 +497,20 @@ The contents of the response from the Internet resource are returned as a Gets the length of the content returned by the request. The number of bytes returned by the request. Content length does not include header information. - property contains the value of the Content-Length header returned with the response. If the Content-Length header is not set in the response, is set to the value -1. - - - -## Examples - The following example displays the value of this property. - + property contains the value of the Content-Length header returned with the response. If the Content-Length header is not set in the response, is set to the value -1. + + + +## Examples + The following example displays the value of this property. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NCLResponse1/CPP/httpwebrequest1.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/Credentials/httpwebrequest1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NCLResponse1/VB/httpwebrequest1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NCLResponse1/VB/httpwebrequest1.vb" id="Snippet1"::: + ]]> The current instance has been disposed. @@ -558,20 +558,20 @@ The contents of the response from the Internet resource are returned as a Gets the content type of the response. A string that contains the content type of the response. - property contains the value of the Content-Type header returned with the response. - - - -## Examples - The following example displays the value of this property. - + property contains the value of the Content-Type header returned with the response. + + + +## Examples + The following example displays the value of this property. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NCLResponse1/CPP/httpwebrequest1.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/Credentials/httpwebrequest1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NCLResponse1/VB/httpwebrequest1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NCLResponse1/VB/httpwebrequest1.vb" id="Snippet1"::: + ]]> The current instance has been disposed. @@ -626,22 +626,22 @@ The contents of the response from the Internet resource are returned as a Gets or sets the cookies that are associated with this response. A that contains the cookies that are associated with this response. - property provides an instance of the class that holds the cookies associated with this response. - - If the property of the associated is `null`, the property will also be `null`. Any cookie information sent by the server will be available in the property, however. - - - -## Examples - The following example sends a request to a URL and displays the cookies returned in the response. - + property provides an instance of the class that holds the cookies associated with this response. + + If the property of the associated is `null`, the property will also be `null`. Any cookie information sent by the server will be available in the property, however. + + + +## Examples + The following example sends a request to a URL and displays the cookies returned in the response. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NCLCookies/CPP/cookiessnippets.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Net/Cookie/Overview/cookiessnippets.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NCLCookies/VB/cookiessnippets.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NCLCookies/VB/cookiessnippets.vb" id="Snippet1"::: + ]]> The current instance has been disposed. @@ -698,22 +698,22 @@ The contents of the response from the Internet resource are returned as a to release both managed and unmanaged resources; to releases only unmanaged resources. Releases the unmanaged resources used by the , and optionally disposes of the managed resources. - method, if it has been overridden. `Dispose()` invokes this method with the `disposing` parameter set to `true`. `Finalize` invokes this method with `disposing` set to `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. - + + 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. + > [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). - +> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). + ]]> - can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). - + can be called multiple times by other objects. When overriding , be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). + For more information about and , see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged) and [Overriding the Finalize Method](https://docs.microsoft.com/previous-versions/dotnet/netframework-4.0/ddae83kx(v=vs.100)). @@ -749,7 +749,7 @@ The contents of the response from the Internet resource are returned as a @@ -807,19 +807,19 @@ The GetHashCode method returns a hash code of the web response instance. This va System.Void - - + + The to populate with data. A that specifies the destination for this serialization. Populates a with the data needed to serialize the target object. - are automatically tracked and serialized by the formatter. - + are automatically tracked and serialized by the formatter. + ]]> @@ -862,27 +862,27 @@ The GetHashCode method returns a hash code of the web response instance. This va System.String - + The header value to return. Gets the contents of a header that was returned with the response. The contents of the specified header. - to retrieve the contents of particular headers. You must specify which header you want to return. - - - -## Examples - This example creates a Web request and queries for a response. If the site requires authentication, this example will respond with a challenge string. This string is extracted using . - + to retrieve the contents of particular headers. You must specify which header you want to return. + + + +## Examples + This example creates a Web request and queries for a response. If the site requires authentication, this example will respond with a challenge string. This string is extracted using . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/HttpWebResponse_GetResponseHeader/CPP/httpwebresponse_getresponseheader.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebResponse/GetResponseHeader/httpwebresponse_getresponseheader.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/HttpWebResponse_GetResponseHeader/VB/httpwebresponse_getresponseheader.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/HttpWebResponse_GetResponseHeader/VB/httpwebresponse_getresponseheader.vb" id="Snippet1"::: + ]]> The current instance has been disposed. @@ -931,26 +931,26 @@ The GetHashCode method returns a hash code of the web response instance. This va Gets the stream that is used to read the body of the response from the server. A containing the body of the response. - method returns the data stream from the requested Internet resource. - + method returns the data stream from the requested Internet resource. + > [!NOTE] -> You must call one of the , , , or methods to close the stream and release the connection for reuse. It's not necessary to close or dispose both and instances, but doing so doesn't cause an error. Failure to close or dispose the stream will cause your application to run out of connections. - +> You must call one of the , , , or methods to close the stream and release the connection for reuse. It's not necessary to close or dispose both and instances, but doing so doesn't cause an error. Failure to close or dispose the stream will cause your application to run out of connections. + > [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). - - - -## Examples - The following example demonstrates how to use to return the instance used to read the response from the server. - +> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). + + + +## Examples + The following example demonstrates how to use to return the instance used to read the response from the server. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/HttpWebResponse_GetResponseStream/CPP/httpwebresponse_getresponsestream.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebResponse/GetResponseStream/httpwebresponse_getresponsestream.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/HttpWebResponse_GetResponseStream/VB/httpwebresponse_getresponsestream.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/HttpWebResponse_GetResponseStream/VB/httpwebresponse_getresponsestream.vb" id="Snippet1"::: + ]]> There is no response stream. @@ -999,28 +999,28 @@ The GetHashCode method returns a hash code of the web response instance. This va Gets the headers that are associated with this response from the server. A that contains the header information returned with the response. - property is a collection of name/value pairs that contain the HTTP header values returned with the response. Common header information returned from the Internet resource is exposed as properties of the class. The following table lists common headers that the API exposes as properties. - -|Header|Property| -|------------|--------------| -|Content-Encoding|| -|Content-Length|| -|Content-Type|| -|Last-Modified|| -|Server|| - - - -## Examples - The following example writes the contents of all of the response headers to the console. - + property is a collection of name/value pairs that contain the HTTP header values returned with the response. Common header information returned from the Internet resource is exposed as properties of the class. The following table lists common headers that the API exposes as properties. + +|Header|Property| +|------------|--------------| +|Content-Encoding|| +|Content-Length|| +|Content-Type|| +|Last-Modified|| +|Server|| + + + +## Examples + The following example writes the contents of all of the response headers to the console. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/HttpWebResponse_Headers/CPP/httpwebresponse_headers.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebResponse/Headers/httpwebresponse_headers.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/HttpWebResponse_Headers/VB/httpwebresponse_headers.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/HttpWebResponse_Headers/VB/httpwebresponse_headers.vb" id="Snippet1"::: + ]]> The current instance has been disposed. @@ -1067,11 +1067,11 @@ The GetHashCode method returns a hash code of the web response instance. This va if mutual authentication occurred; otherwise, . - property. - + property. + ]]> The current instance has been disposed. @@ -1118,20 +1118,20 @@ The GetHashCode method returns a hash code of the web response instance. This va Gets the last date and time that the contents of the response were modified. A that contains the date and time that the contents of the response were modified. - property contains the value of the Last-Modified header received with the response. The date and time are assumed to be local time. - - - -## Examples - This example creates an and queries for a response. This example then checks whether the entity requested had been modified any time today. - + property contains the value of the Last-Modified header received with the response. The date and time are assumed to be local time. + + + +## Examples + This example creates an and queries for a response. This example then checks whether the entity requested had been modified any time today. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/HttpWebResponse_LastModified/CPP/httpwebresponse_lastmodified.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebResponse/LastModified/httpwebresponse_lastmodified.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/HttpWebResponse_LastModified/VB/httpwebresponse_lastmodified.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/HttpWebResponse_LastModified/VB/httpwebresponse_lastmodified.vb" id="Snippet1"::: + ]]> The current instance has been disposed. @@ -1182,20 +1182,20 @@ The GetHashCode method returns a hash code of the web response instance. This va Gets the method that is used to return the response. A string that contains the HTTP method that is used to return the response. - returns the method that is used to return the response. Common HTTP methods are GET, HEAD, POST, PUT, and DELETE. - - - -## Examples - The following example checks the string contained in , to determine the Http method invoked by the Web server. - + returns the method that is used to return the response. Common HTTP methods are GET, HEAD, POST, PUT, and DELETE. + + + +## Examples + The following example checks the string contained in , to determine the Http method invoked by the Web server. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/HttpWebResponse_Method_Server/CPP/httpwebresponse_method_server.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebResponse/Method/httpwebresponse_method_server.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/HttpWebResponse_Method_Server/VB/httpwebresponse_method_server.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/HttpWebResponse_Method_Server/VB/httpwebresponse_method_server.vb" id="Snippet1"::: + ]]> The current instance has been disposed. @@ -1242,20 +1242,20 @@ The GetHashCode method returns a hash code of the web response instance. This va Gets the version of the HTTP protocol that is used in the response. A that contains the HTTP protocol version of the response. - property contains the HTTP protocol version number of the response sent by the Internet resource. - - - -## Examples - This example creates an and queries for an . The example then checks to see if the server is responding with the same version. - + property contains the HTTP protocol version number of the response sent by the Internet resource. + + + +## Examples + This example creates an and queries for an . The example then checks to see if the server is responding with the same version. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/HttpWebResponse_ProtocolVersion/CPP/httpwebresponse_protocolversion.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebResponse/ProtocolVersion/httpwebresponse_protocolversion.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/HttpWebResponse_ProtocolVersion/VB/httpwebresponse_protocolversion.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/HttpWebResponse_ProtocolVersion/VB/httpwebresponse_protocolversion.vb" id="Snippet1"::: + ]]> The current instance has been disposed. @@ -1303,24 +1303,24 @@ The GetHashCode method returns a hash code of the web response instance. This va Gets the URI of the Internet resource that responded to the request. The URI of the Internet resource that responded to the request. - property contains the URI of the Internet resource that actually responded to the request. This URI might not be the same as the originally requested URI, if the original server redirected the request. - - The property will use the Content-Location header if present. - - Applications that need to access the last redirected should use the property rather than , since the use of property may open security vulnerabilities. - - - -## Examples - This example creates a and queries for an and then checks to see whether the original URI was redirected by the server. - + property contains the URI of the Internet resource that actually responded to the request. This URI might not be the same as the originally requested URI, if the original server redirected the request. + + The property will use the Content-Location header if present. + + Applications that need to access the last redirected should use the property rather than , since the use of property may open security vulnerabilities. + + + +## Examples + This example creates a and queries for an and then checks to see whether the original URI was redirected by the server. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/HttpWebResponse_ResponseUri/CPP/httpwebresponse_responseuri.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebResponse/ResponseUri/httpwebresponse_responseuri.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/HttpWebResponse_ResponseUri/VB/httpwebresponse_responseuri.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/HttpWebResponse_ResponseUri/VB/httpwebresponse_responseuri.vb" id="Snippet1"::: + ]]> The current instance has been disposed. @@ -1367,20 +1367,20 @@ The GetHashCode method returns a hash code of the web response instance. This va Gets the name of the server that sent the response. A string that contains the name of the server that sent the response. - property contains the value of the Server header returned with the response. - - - -## Examples - The following example uses the property to display the Web server's name to the console. - + property contains the value of the Server header returned with the response. + + + +## Examples + The following example uses the property to display the Web server's name to the console. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/HttpWebResponse_Method_Server/CPP/httpwebresponse_method_server.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebResponse/Method/httpwebresponse_method_server.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/HttpWebResponse_Method_Server/VB/httpwebresponse_method_server.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/HttpWebResponse_Method_Server/VB/httpwebresponse_method_server.vb" id="Snippet2"::: + ]]> The current instance has been disposed. @@ -1431,20 +1431,20 @@ The GetHashCode method returns a hash code of the web response instance. This va Gets the status of the response. One of the values. - parameter is a number that indicates the status of the HTTP response. The expected values for status are defined in the class. - - - -## Examples - The following example uses to verify that the status of the is OK. - + parameter is a number that indicates the status of the HTTP response. The expected values for status are defined in the class. + + + +## Examples + The following example uses to verify that the status of the is OK. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/HttpWebResponse_StatusCode_StatusDescription/CPP/httpwebresponse_statuscode_statusdescription.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebResponse/StatusCode/httpwebresponse_statuscode_statusdescription.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/HttpWebResponse_StatusCode_StatusDescription/VB/httpwebresponse_statuscode_statusdescription.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/HttpWebResponse_StatusCode_StatusDescription/VB/httpwebresponse_statuscode_statusdescription.vb" id="Snippet1"::: + ]]> The current instance has been disposed. @@ -1495,20 +1495,20 @@ The GetHashCode method returns a hash code of the web response instance. This va Gets the status description returned with the response. A string that describes the status of the response. - to verify that the status of the is OK. - + to verify that the status of the is OK. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/HttpWebResponse_StatusCode_StatusDescription/CPP/httpwebresponse_statuscode_statusdescription.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebResponse/StatusCode/httpwebresponse_statuscode_statusdescription.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/HttpWebResponse_StatusCode_StatusDescription/VB/httpwebresponse_statuscode_statusdescription.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/HttpWebResponse_StatusCode_StatusDescription/VB/httpwebresponse_statuscode_statusdescription.vb" id="Snippet2"::: + ]]> The current instance has been disposed. @@ -1591,10 +1591,10 @@ The GetHashCode method returns a hash code of the web response instance. This va . 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). -> [!NOTE] +> [!NOTE] > Always call `Dispose` 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. ]]> @@ -1657,8 +1657,8 @@ Call `Dispose` when you are finished using the System.Void - - + + The object into which this will be serialized. diff --git a/xml/System.Net/NetworkCredential.xml b/xml/System.Net/NetworkCredential.xml index f76362514d1..49c1fbb8843 100644 --- a/xml/System.Net/NetworkCredential.xml +++ b/xml/System.Net/NetworkCredential.xml @@ -74,22 +74,22 @@ Provides credentials for password-based authentication schemes such as basic, digest, NTLM, and Kerberos authentication. - class is a base class that supplies credentials in password-based authentication schemes such as basic, digest, NTLM, and Kerberos. Classes that implement the interface, such as the class, return objects. - - This class does not support public key-based authentication methods such as Secure Sockets Layer (SSL) client authentication. - - - -## Examples + class is a base class that supplies credentials in password-based authentication schemes such as basic, digest, NTLM, and Kerberos. Classes that implement the interface, such as the class, return objects. + + This class does not support public key-based authentication methods such as Secure Sockets Layer (SSL) client authentication. + + + +## Examples The following code example associates a object with a set of Uniform Resource Identifiers (URIs) in a . It then passes the to a object, which uses it to authenticate requests to an Internet server. - + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/Classic NetworkCredential Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Net/NetworkCredential/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic NetworkCredential Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic NetworkCredential Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -152,11 +152,11 @@ Initializes a new instance of the class. - class initializes all properties to `null`. - + class initializes all properties to `null`. + ]]> @@ -205,23 +205,23 @@ - - + + The user name associated with the credentials. The password for the user name associated with the credentials. Initializes a new instance of the class with the specified user name and password. - object with the property set to `userName` and the property set to `password`. - - The `password` parameter is a instance. - - If this constructor is called with the `password` parameter set to `null`, a new instance of is initialized, If secure strings are not supported on this platform, then the is thrown - + object with the property set to `userName` and the property set to `password`. + + The `password` parameter is a instance. + + If this constructor is called with the `password` parameter set to `null`, a new instance of is initialized, If secure strings are not supported on this platform, then the is thrown + ]]> The class is not supported on this platform. @@ -280,20 +280,20 @@ The password for the user name associated with the credentials. Initializes a new instance of the class with the specified user name and password. - object with the property set to `userName` and the property set to `password`. - - - -## Examples - The following code example creates a object using the specified user name and password. - + object with the property set to `userName` and the property set to `password`. + + + +## Examples + The following code example creates a object using the specified user name and password. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NetworkCredential_Constructor2/CPP/networkcredential_constructor2.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Net/NetworkCredential/.ctor/networkcredential_constructor2.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NetworkCredential_Constructor2/VB/networkcredential_constructor2.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NetworkCredential_Constructor2/VB/networkcredential_constructor2.vb" id="Snippet1"::: + ]]> @@ -342,9 +342,9 @@ - - - + + + The user name associated with the credentials. @@ -352,15 +352,15 @@ The domain associated with these credentials. Initializes a new instance of the class with the specified user name, password, and domain. - object with the property set to `userName`, the property set to `password`, and the property set to `domain`. - - The `password` parameter is a instance. - - If this constructor is called with the `password` parameter set to `null`, a new instance of is initialized, If secure strings are not supported on this platform, then the is thrown - + object with the property set to `userName`, the property set to `password`, and the property set to `domain`. + + The `password` parameter is a instance. + + If this constructor is called with the `password` parameter set to `null`, a new instance of is initialized, If secure strings are not supported on this platform, then the is thrown + ]]> The class is not supported on this platform. @@ -421,11 +421,11 @@ The domain associated with these credentials. Initializes a new instance of the class with the specified user name, password, and domain. - object with the property set to `userName`, the property set to `password`, and the property set to `domain`. - + object with the property set to `userName`, the property set to `password`, and the property set to `domain`. + ]]> @@ -474,20 +474,20 @@ Gets or sets the domain or computer name that verifies the credentials. The name of the domain associated with the credentials. - property specifies the domain or realm to which the user name belongs. Typically, this is the host computer name where the application runs or the user domain for the currently logged in user. - - - -## Examples - The following code example uses the property to set the domain associated with the credentials. - + property specifies the domain or realm to which the user name belongs. Typically, this is the host computer name where the application runs or the user domain for the currently logged in user. + + + +## Examples + The following code example uses the property to set the domain associated with the credentials. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NetworkCredential_UserName_Password_Domain/CPP/networkcredential_username_password_domain.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Net/NetworkCredential/Domain/networkcredential_username_password_domain.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NetworkCredential_UserName_Password_Domain/VB/networkcredential_username_password_domain.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NetworkCredential_UserName_Password_Domain/VB/networkcredential_username_password_domain.vb" id="Snippet1"::: + ]]> @@ -564,11 +564,11 @@ Returns an instance of the class for the specified host, port, and authentication type. A for the specified host, port, and authentication protocol, or if there are no credentials available for the specified host, port, and authentication protocol. - property. - + property. + ]]> @@ -639,15 +639,15 @@ Returns an instance of the class for the specified Uniform Resource Identifier (URI) and authentication type. A object. - method to retrieve a object for the specified URI. - + method to retrieve a object for the specified URI. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NetworkCredential_GetCredential/CPP/networkcredential_getcredential.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Net/NetworkCredential/GetCredential/networkcredential_getcredential.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NetworkCredential_GetCredential/VB/networkcredential_getcredential.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NetworkCredential_GetCredential/VB/networkcredential_getcredential.vb" id="Snippet1"::: + ]]> @@ -696,15 +696,15 @@ Gets or sets the password for the user name associated with the credentials. The password associated with the credentials. If this instance was initialized with the parameter set to , then the property will return an empty string. - property to set the password associated with the credentials. - + property to set the password associated with the credentials. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NetworkCredential_UserName_Password_Domain/CPP/networkcredential_username_password_domain.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Net/NetworkCredential/Domain/networkcredential_username_password_domain.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NetworkCredential_UserName_Password_Domain/VB/networkcredential_username_password_domain.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NetworkCredential_UserName_Password_Domain/VB/networkcredential_username_password_domain.vb" id="Snippet1"::: + ]]> @@ -754,11 +754,11 @@ Gets or sets the password as a instance. The password for the user name associated with the credentials. - property to `null`, a new instance of is initialized, If secure strings are not supported on this platform, then the is thrown - + property to `null`, a new instance of is initialized, If secure strings are not supported on this platform, then the is thrown + ]]> The class is not supported on this platform. @@ -808,15 +808,15 @@ Gets or sets the user name associated with the credentials. The user name associated with the credentials. - property to set the user name associated with the credentials. - + property to set the user name associated with the credentials. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NetworkCredential_UserName_Password_Domain/CPP/networkcredential_username_password_domain.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Net/NetworkCredential/Domain/networkcredential_username_password_domain.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NetworkCredential_UserName_Password_Domain/VB/networkcredential_username_password_domain.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NetworkCredential_UserName_Password_Domain/VB/networkcredential_username_password_domain.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.Net/ProtocolViolationException.xml b/xml/System.Net/ProtocolViolationException.xml index 4d3bb34e940..0b5f2e04e9b 100644 --- a/xml/System.Net/ProtocolViolationException.xml +++ b/xml/System.Net/ProtocolViolationException.xml @@ -62,11 +62,11 @@ The exception that is thrown when an error is made while using a network protocol. - is thrown by descendants of and to indicate an error using the underlying protocol. For example, the and classes throw a to indicate an error using HTTP. - + is thrown by descendants of and to indicate an error using the underlying protocol. For example, the and classes throw a to indicate an error using HTTP. + ]]> @@ -126,11 +126,11 @@ Initializes a new instance of the class. - property is initialized to a system-supplied message that describes the error. The property is initialized to `null`. - + property is initialized to a system-supplied message that describes the error. The property is initialized to `null`. + ]]> @@ -188,11 +188,11 @@ The error message string. Initializes a new instance of the class with the specified message. - class with the property set to the value of the `message` parameter. If `message` is a null reference, the `Message` property is initialized to a system-supplied message. The `InnerException` property is initialized to `null`. - + class with the property set to the value of the `message` parameter. If `message` is a null reference, the `Message` property is initialized to a system-supplied message. The `InnerException` property is initialized to `null`. + ]]> @@ -250,19 +250,19 @@ - - + + A that contains the information that is required to deserialize the . A that contains the source of the serialized stream that is associated with the new . Initializes a new instance of the class from the specified and instances. - interface for the class. - + interface for the class. + ]]> @@ -319,19 +319,19 @@ System.Void - - + + The to populate with data. A that specifies the destination for this serialization. Populates a with the data required to serialize the target object. - are automatically tracked and serialized by the formatter. - + are automatically tracked and serialized by the formatter. + ]]> @@ -377,8 +377,8 @@ System.Void - - + + The object into which this will be serialized. diff --git a/xml/System.Net/WebException.xml b/xml/System.Net/WebException.xml index 412b085114b..003af32eeec 100644 --- a/xml/System.Net/WebException.xml +++ b/xml/System.Net/WebException.xml @@ -70,24 +70,24 @@ The exception that is thrown when an error occurs while accessing the network through a pluggable protocol. - class is thrown by classes descended from and that implement pluggable protocols for accessing the Internet. - - When is thrown by a descendant of the class, the property provides the Internet response to the application. - - **Associated Tips** - - **Check the Response property of the exception to determine why the request failed.** - When a exception is thrown by a descendent of the class, the property provides the Internet response to the application. - - **Check the Status property of the exception to determine why the request failed.** - The property of the exception provides status information for the error. For more information, see . - - **If you are timing out when stepping into an XML Web Service, set the timeout value for the XML Web Service call to infinite.** - For more information, see [Error: Timeout While Debugging Web Services](https://msdn.microsoft.com/library/4b7df112-788a-4429-9a0c-4c6dac4fb609). - + class is thrown by classes descended from and that implement pluggable protocols for accessing the Internet. + + When is thrown by a descendant of the class, the property provides the Internet response to the application. + + **Associated Tips** + + **Check the Response property of the exception to determine why the request failed.** + When a exception is thrown by a descendent of the class, the property provides the Internet response to the application. + + **Check the Status property of the exception to determine why the request failed.** + The property of the exception provides status information for the error. For more information, see . + + **If you are timing out when stepping into an XML Web Service, set the timeout value for the XML Web Service call to infinite.** + For more information, see [Error: Timeout While Debugging Web Services](https://msdn.microsoft.com/library/4b7df112-788a-4429-9a0c-4c6dac4fb609). + ]]> @@ -141,20 +141,20 @@ Initializes a new instance of the class. - class. The property is initialized to a system-supplied message that describes the error. This message takes into account the current system culture. The and properties are initialized to `null`. The property is initialized to . - - - -## Examples - The following example throws a default . - + class. The property is initialized to a system-supplied message that describes the error. This message takes into account the current system culture. The and properties are initialized to `null`. The property is initialized to . + + + +## Examples + The following example throws a default . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/WebException_Constructor1/CPP/webexception_constructor1.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Net/WebException/.ctor/webexception_constructor1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/WebException_Constructor1/VB/webexception_constructor1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/WebException_Constructor1/VB/webexception_constructor1.vb" id="Snippet1"::: + ]]> @@ -208,20 +208,20 @@ The text of the error message. Initializes a new instance of the class with the specified error message. - instance is initialized with the property set to the value of `message`. If `message` is `null`, the property is initialized to a system-supplied message. The and properties are initialized to `null`. The property is initialized to . - - - -## Examples - The following example throws a by specifying an error message. - + instance is initialized with the property set to the value of `message`. If `message` is `null`, the property is initialized to a system-supplied message. The and properties are initialized to `null`. The property is initialized to . + + + +## Examples + The following example throws a by specifying an error message. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/WebException_Constructor2/CPP/webexception_constructor2.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Net/WebException/.ctor/webexception_constructor2.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/WebException_Constructor2/VB/webexception_constructor2.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/WebException_Constructor2/VB/webexception_constructor2.vb" id="Snippet1"::: + ]]> @@ -276,19 +276,19 @@ - - + + A that contains the information required to serialize the new . A that contains the source of the serialized stream that is associated with the new . Initializes a new instance of the class from the specified and instances. - interface for the class. - + interface for the class. + ]]> @@ -345,20 +345,20 @@ One of the values. Initializes a new instance of the class with the specified error message and status. - instance is initialized with the property set to the value of `message` and the property set to the value of `status`. If `message` is `null`, the property is initialized to a system-supplied message. The and properties are initialized to `null`. - - - -## Examples - The following example throws a by specifying an error message and a . - + instance is initialized with the property set to the value of `message` and the property set to the value of `status`. If `message` is `null`, the property is initialized to a system-supplied message. The and properties are initialized to `null`. + + + +## Examples + The following example throws a by specifying an error message and a . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/WebException_Constructor3/CPP/webexception_constructor3.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Net/WebException/.ctor/webexception_constructor3.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/WebException_Constructor3/VB/webexception_constructor3.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/WebException_Constructor3/VB/webexception_constructor3.vb" id="Snippet1"::: + ]]> @@ -415,20 +415,20 @@ A nested exception. Initializes a new instance of the class with the specified error message and nested exception. - 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 and properties are initialized to `null`. The property is initialized to . - - - -## Examples - The following example throws a by specifying an error message and nested exception. - + 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 and properties are initialized to `null`. The property is initialized to . + + + +## Examples + The following example throws a by specifying an error message and nested exception. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/WebException_Constructor4/CPP/webexception_constructor4.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Net/WebException/.ctor/webexception_constructor4.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/WebException_Constructor4/VB/webexception_constructor4.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/WebException_Constructor4/VB/webexception_constructor4.vb" id="Snippet1"::: + ]]> @@ -496,20 +496,20 @@ A instance that contains the response from the remote host. Initializes a new instance of the class with the specified error message, nested exception, status, and response. - instance is initialized with the property set to the value of `message`, the property set to the value of `innerException`, the property set to the value of `status`, and the property set to the value of `response`. If `message` is `null`, the property is initialized to a system-supplied message. - - - -## Examples - The following example throws a by specifying an error message and a . - + instance is initialized with the property set to the value of `message`, the property set to the value of `innerException`, the property set to the value of `status`, and the property set to the value of `response`. If `message` is `null`, the property is initialized to a system-supplied message. + + + +## Examples + The following example throws a by specifying an error message and a . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/WebException_Constructor5/CPP/webexception_constructor5.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Net/WebException/.ctor/webexception_constructor5.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/WebException_Constructor5/VB/webexception_constructor5.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/WebException_Constructor5/VB/webexception_constructor5.vb" id="Snippet1"::: + ]]> @@ -565,8 +565,8 @@ System.Void - - + + The to be used. @@ -624,20 +624,20 @@ Gets the response that the remote host returned. If a response is available from the Internet resource, a instance that contains the error response from an Internet resource; otherwise, . - sets the property to and provides the that contains the error message in the property of the that was thrown. The application can examine the to determine the actual error. - - - -## Examples - The following example checks the property and prints to the console the and of the underlying instance. - + sets the property to and provides the that contains the error message in the property of the that was thrown. The application can examine the to determine the actual error. + + + +## Examples + The following example checks the property and prints to the console the and of the underlying instance. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/WebException_Status_Response/CPP/webexception_status_response.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Net/WebException/Response/webexception_status_response.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/WebException_Status_Response/VB/webexception_status_response.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/WebException_Status_Response/VB/webexception_status_response.vb" id="Snippet1"::: + ]]> @@ -690,25 +690,25 @@ Gets the status of the response. One of the values. - property indicates the reason for the . - - The value of is one of the values. - + property indicates the reason for the . + + The value of is one of the values. + > [!WARNING] -> The error is not returned to Windows 8.x Store apps. - - - -## Examples - The following example checks the property and prints to the console the and of the underlying instance. - +> The error is not returned to Windows 8.x Store apps. + + + +## Examples + The following example checks the property and prints to the console the and of the underlying instance. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/WebException_Status_Response/CPP/webexception_status_response.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Net/WebException/Response/webexception_status_response.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/WebException_Status_Response/VB/webexception_status_response.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/WebException_Status_Response/VB/webexception_status_response.vb" id="Snippet1"::: + ]]> @@ -756,8 +756,8 @@ System.Void - - + + The object into which this will be serialized. diff --git a/xml/System.Net/WebHeaderCollection.xml b/xml/System.Net/WebHeaderCollection.xml index eec1049f4a7..04ffae17585 100644 --- a/xml/System.Net/WebHeaderCollection.xml +++ b/xml/System.Net/WebHeaderCollection.xml @@ -98,41 +98,41 @@ Contains protocol headers associated with a request or response. - class is generally accessed through or . On .NET Framework, some common headers are considered restricted and are either exposed directly by the API (such as `Content-Type`) or protected by the system and cannot be changed. This does *not* apply to .NET Core and .NET 5+, where none of the headers are restricted. - The restricted headers are: - -- Accept - -- Connection - -- Content-Length - -- Content-Type - -- Date - -- Expect - -- Host - -- If-Modified-Since - -- Range - -- Referer - -- Transfer-Encoding - -- User-Agent - -- Proxy-Connection - + The restricted headers are: + +- Accept + +- Connection + +- Content-Length + +- Content-Type + +- Date + +- Expect + +- Host + +- If-Modified-Since + +- Range + +- Referer + +- Transfer-Encoding + +- User-Agent + +- Proxy-Connection + ]]> @@ -238,19 +238,19 @@ - - + + A containing the information required to serialize the . A containing the source of the serialized stream associated with the new . Initializes a new instance of the class from the specified instances of the and classes. - interface for the class. - + interface for the class. + ]]> @@ -311,28 +311,28 @@ System.Void - + The header to add, with the name and value separated by a colon. Inserts the specified header into the collection. - using the Method. - + using the Method. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/WebHeaderCollection_Add/CPP/webheadercollection_add.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Net/WebHeaderCollection/Add/webheadercollection_add.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/WebHeaderCollection_Add/VB/webheadercollection_add.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/WebHeaderCollection_Add/VB/webheadercollection_add.vb" id="Snippet1"::: + > [!NOTE] > The length of the *value* portion of `header`, that is, the string after the colon (:), is validated only in .NET Framework and .NET Core versions 2.0 - 3.1. > - On all applicable .NET Framework versions: A instance that's returned by the property will throw an if the length of the *value* portion of `header` is greater than 65535. All other instances accept a *value* of any length. @@ -343,20 +343,20 @@ is or . - does not contain a colon (:) character. - - The length of is greater than 65535. - - -or- - - The name part of is or contains invalid characters. - - -or- - - is a restricted header that should be set with a property. - - -or- - + does not contain a colon (:) character. + + The length of is greater than 65535. + + -or- + + The name part of is or contains invalid characters. + + -or- + + is a restricted header that should be set with a property. + + -or- + The value part of contains invalid characters. .NET Framework and .NET Core versions 2.0 - 3.1 only: The length of the string after the colon (:) is greater than 65535. @@ -408,21 +408,21 @@ System.Void - - + + The header to add to the collection. The content of the header. Inserts the specified header with the specified value into the collection. - method inserts a new header into the list of header name/value pairs. - - If the specified header is already present, `value` is added to the comma-separated list of values associated with the header. - + method inserts a new header into the list of header name/value pairs. + + If the specified header is already present, `value` is added to the comma-separated list of values associated with the header. + > [!NOTE] > The length of `value` is validated only in .NET Framework and .NET Core versions 2.0 - 3.1. > - On all applicable .NET Framework versions: A instance that's returned by the property will throw an if the length of `value` is greater than 65535. All other instances accept a `value` of any length. @@ -481,21 +481,21 @@ System.Void - - + + The header to add to the collection. The content of the header. Inserts the specified header with the specified value into the collection. - method inserts a new header into the list of header name/value pairs. - - If the specified header is already present, `value` is added to the comma-separated list of values associated with the header. - + method inserts a new header into the list of header name/value pairs. + + If the specified header is already present, `value` is added to the comma-separated list of values associated with the header. + > [!NOTE] > The length of `value` is validated only in .NET Framework and .NET Core versions 2.0 - 3.1. > - On all applicable .NET Framework versions: A instance that's returned by the property will throw an if the length of `value` is greater than 65535. All other instances accept a `value` of any length. @@ -549,8 +549,8 @@ System.Void - - + + [System.Runtime.CompilerServices.Nullable(2)] @@ -564,22 +564,22 @@ The content of the header. Inserts a header with the specified name and value into the collection. - method inserts a new header into the list of header name/value pairs. - - If the header specified in `name` is already present, `value` is added to the existing comma-separated list of values associated with `name`. - - - -## Examples - The following example adds a name/value pair to a using the Method. - + method inserts a new header into the list of header name/value pairs. + + If the header specified in `name` is already present, `value` is added to the existing comma-separated list of values associated with `name`. + + + +## Examples + The following example adds a name/value pair to a using the Method. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/WebHeaderCollection_Add/CPP/webheadercollection_add.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Net/WebHeaderCollection/Add/webheadercollection_add.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/WebHeaderCollection_Add/VB/webheadercollection_add.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/WebHeaderCollection_Add/VB/webheadercollection_add.vb" id="Snippet1"::: + > [!NOTE] > The length of `value` is validated only in .NET Framework and .NET Core versions 2.0 - 3.1. > - On all applicable .NET Framework versions: A instance that's returned by the property will throw an if the length of `value` is greater than 65535. All other instances accept a `value` of any length. @@ -588,14 +588,14 @@ ]]> - is , , or contains invalid characters. - - -or- - - is a restricted header that must be set with a property setting. - - -or- - + is , , or contains invalid characters. + + -or- + + is a restricted header that must be set with a property setting. + + -or- + contains invalid characters. .NET Framework and .NET Core versions 2.0 - 3.1 only: The length of is greater than 65535. @@ -642,8 +642,8 @@ System.Void - - + + [System.Runtime.CompilerServices.Nullable(2)] @@ -657,11 +657,11 @@ The content of the header. Inserts a header into the collection without checking whether the header is on the restricted header list. - method adds a header to the collection without checking whether the header is on the restricted header list. - + method adds a header to the collection without checking whether the header is on the restricted header list. + > [!NOTE] > The length of `headerValue` is validated only in .NET Framework and .NET Core versions 2.0 - 3.1. > - On all applicable .NET Framework versions: A instance that's returned by the property will throw an if the length of `headerValue` is greater than 65535. All other instances accept a `headerValue` of any length. @@ -670,10 +670,10 @@ ]]> - is , , or contains invalid characters. - - -or- - + is , , or contains invalid characters. + + -or- + contains invalid characters. .NET Framework and .NET Core only: is not and the length of is too long (greater than 65,535 characters). @@ -730,13 +730,13 @@ Gets all header names (keys) in the collection. An array of type containing all header names in a Web request. - property to get the header names a . - - :::code language="csharp" source="~/snippets/csharp/System.Net/WebHeaderCollection/AllKeys/webheadercollection_newprops.cs" id="Snippet1"::: - + property to get the header names a . + + :::code language="csharp" source="~/snippets/csharp/System.Net/WebHeaderCollection/AllKeys/webheadercollection_newprops.cs" id="Snippet1"::: + ]]> @@ -784,13 +784,13 @@ Removes all headers from the collection. - . - - :::code language="csharp" source="~/snippets/csharp/System.Net/WebHeaderCollection/AllKeys/webheadercollection_newprops.cs" id="Snippet1"::: - + . + + :::code language="csharp" source="~/snippets/csharp/System.Net/WebHeaderCollection/AllKeys/webheadercollection_newprops.cs" id="Snippet1"::: + ]]> @@ -843,13 +843,13 @@ Gets the number of headers in the collection. An indicating the number of headers in a request. - property to iterate through a . - - :::code language="csharp" source="~/snippets/csharp/System.Net/WebHeaderCollection/AllKeys/webheadercollection_newprops.cs" id="Snippet1"::: - + property to iterate through a . + + :::code language="csharp" source="~/snippets/csharp/System.Net/WebHeaderCollection/AllKeys/webheadercollection_newprops.cs" id="Snippet1"::: + ]]> @@ -912,27 +912,27 @@ System.String - + The zero-based index of the key to get from the collection. Gets the value of a particular header in the collection, specified by an index into the collection. A containing the value of the specified header. - method to retrieve a header value in a . - - :::code language="csharp" source="~/snippets/csharp/System.Net/WebHeaderCollection/AllKeys/webheadercollection_newprops.cs" id="Snippet1"::: - + method to retrieve a header value in a . + + :::code language="csharp" source="~/snippets/csharp/System.Net/WebHeaderCollection/AllKeys/webheadercollection_newprops.cs" id="Snippet1"::: + ]]> - is negative. - - -or- - + is negative. + + -or- + exceeds the size of the collection. @@ -984,25 +984,25 @@ System.String - + The name of the Web header. Gets the value of a particular header in the collection, specified by the name of the header. A holding the value of the specified header. - property to retrieve header values in a . - - :::code language="csharp" source="~/snippets/csharp/System.Net/WebHeaderCollection/AllKeys/webheadercollection_newprops.cs" id="Snippet1"::: - + property to retrieve header values in a . + + :::code language="csharp" source="~/snippets/csharp/System.Net/WebHeaderCollection/AllKeys/webheadercollection_newprops.cs" id="Snippet1"::: + ]]> @@ -1097,27 +1097,27 @@ System.String - + The zero-based index of the key to get from the collection. Gets the header name at the specified position in the collection. A holding the header name. - to get a header name in a . - - :::code language="csharp" source="~/snippets/csharp/System.Net/WebHeaderCollection/AllKeys/webheadercollection_newprops.cs" id="Snippet1"::: - + to get a header name in a . + + :::code language="csharp" source="~/snippets/csharp/System.Net/WebHeaderCollection/AllKeys/webheadercollection_newprops.cs" id="Snippet1"::: + ]]> - is negative. - - -or- - + is negative. + + -or- + exceeds the size of the collection. @@ -1172,19 +1172,19 @@ System.Void - - + + The to populate with data. A that specifies the destination for this serialization. Populates a with the data needed to serialize the target object. - are automatically tracked and serialized by the formatter. - + are automatically tracked and serialized by the formatter. + ]]> @@ -1241,18 +1241,18 @@ System.String[] - + The header index to return. Gets an array of header values stored in the position of the header collection. An array of header strings. - returns the contents of the specified header as an array. - + returns the contents of the specified header as an array. + ]]> @@ -1299,27 +1299,27 @@ System.String[] - + The header to return. Gets an array of header values stored in a header. An array of header strings. - returns the contents of the specified header as an array. - - - -## Examples - The following example uses the method to retrieve an array of values for each header in the . - + returns the contents of the specified header as an array. + + + +## Examples + The following example uses the method to retrieve an array of values for each header in the . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/WebHeaderCollection_GetValues_1/CPP/webheadercollection_getvalues_1.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Net/WebHeaderCollection/GetValues/webheadercollection_getvalues_1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/WebHeaderCollection_GetValues_1/VB/webheadercollection_getvalues_1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/WebHeaderCollection_GetValues_1/VB/webheadercollection_getvalues_1.vb" id="Snippet1"::: + ]]> @@ -1381,7 +1381,7 @@ System.Boolean - + The header to test. @@ -1389,46 +1389,46 @@ if the header is restricted; otherwise . - method returns `true` to indicate that a header is restricted and must be set using properties instead of directly or is set by the system. The restricted headers are: - -- Accept - -- Connection - -- Content-Length - -- Content-Type - -- Date - -- Expect - -- Host - -- If-Modified-Since - -- Range - -- Referer - -- Transfer-Encoding - -- User-Agent - -- Proxy-Connection - - - -## Examples - The following example checks the property to see if any headers are prohibited from being set. - + method returns `true` to indicate that a header is restricted and must be set using properties instead of directly or is set by the system. The restricted headers are: + +- Accept + +- Connection + +- Content-Length + +- Content-Type + +- Date + +- Expect + +- Host + +- If-Modified-Since + +- Range + +- Referer + +- Transfer-Encoding + +- User-Agent + +- Proxy-Connection + + + +## Examples + The following example checks the property to see if any headers are prohibited from being set. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/WebHeaderCollection_IsRestricted/CPP/webheadercollection_isrestricted.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Net/WebHeaderCollection/IsRestricted/webheadercollection_isrestricted.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/WebHeaderCollection_IsRestricted/VB/webheadercollection_isrestricted.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/WebHeaderCollection_IsRestricted/VB/webheadercollection_isrestricted.vb" id="Snippet1"::: + ]]> @@ -1477,8 +1477,8 @@ System.Boolean - - + + The header to test. @@ -1488,44 +1488,44 @@ if the header is restricted; otherwise, . - method returns `true` to indicate that a request or response header is restricted and must be set using properties instead of directly or is set by the system. The restricted headers are: - -- Accept - -- Connection - -- Content-Length - -- Content-Type - -- Date - -- Expect - -- Host - -- If-Modified-Since - -- Range - -- Referer - -- Transfer-Encoding - -- User-Agent - + method returns `true` to indicate that a request or response header is restricted and must be set using properties instead of directly or is set by the system. The restricted headers are: + +- Accept + +- Connection + +- Content-Length + +- Content-Type + +- Date + +- Expect + +- Host + +- If-Modified-Since + +- Range + +- Referer + +- Transfer-Encoding + +- User-Agent + - Proxy-Connection - -## Examples - The following example checks the property to see if any request headers are prohibited from being set. - + +## Examples + The following example checks the property to see if any request headers are prohibited from being set. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/WebHeaderCollection_IsRestricted/CPP/webheadercollection_isrestricted.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Net/WebHeaderCollection/IsRestricted/webheadercollection_isrestricted.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/WebHeaderCollection_IsRestricted/VB/webheadercollection_isrestricted.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/WebHeaderCollection_IsRestricted/VB/webheadercollection_isrestricted.vb" id="Snippet1"::: + ]]> @@ -1673,9 +1673,9 @@ Gets or sets the specified response header. A instance containing the specified header. - [!NOTE] > The length of `value` is validated only in .NET Framework and .NET Core versions 2.0 - 3.1. @@ -1823,7 +1823,7 @@ System.Void - + The source of the deserialization event. @@ -1881,17 +1881,17 @@ System.Void - + The instance to remove from the collection. Removes the specified header from the collection. - deletes the specified header from the collection. If the specified header does not exist, the method does nothing. - + deletes the specified header from the collection. If the specified header does not exist, the method does nothing. + ]]> This instance does not allow instances of . @@ -1937,17 +1937,17 @@ System.Void - + The instance to remove from the collection. Removes the specified header from the collection. - deletes the specified header from the collection. If the specified header does not exist, the method does nothing. - + deletes the specified header from the collection. If the specified header does not exist, the method does nothing. + ]]> This instance does not allow instances of . @@ -2006,29 +2006,29 @@ The name of the header to remove from the collection. Removes the specified header from the collection. - deletes the specified header from the collection. If the specified header does not exist, the method returns. - - - -## Examples - The following example uses the method to remove a header from the . After the header is removed, this example prints all existing headers to the screen to prove that it has been removed. - + deletes the specified header from the collection. If the specified header does not exist, the method returns. + + + +## Examples + The following example uses the method to remove a header from the . After the header is removed, this example prints all existing headers to the screen to prove that it has been removed. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/WebHeaderCollection_Remove/CPP/webheadercollection_remove.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Net/WebHeaderCollection/Remove/webheadercollection_remove.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/WebHeaderCollection_Remove/VB/webheadercollection_remove.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/WebHeaderCollection_Remove/VB/webheadercollection_remove.vb" id="Snippet1"::: + ]]> is . - is a restricted header. - - -or- - + is a restricted header. + + -or- + contains invalid characters. @@ -2089,21 +2089,21 @@ System.Void - - + + The value to set. The content of the header to set. Sets the specified header to the specified value. - method inserts a new header into the list of header name/value pairs. - - If the header specified in `header` is already present, `value` replaces the existing value. - + method inserts a new header into the list of header name/value pairs. + + If the header specified in `header` is already present, `value` replaces the existing value. + > [!NOTE] > The length of `value` is validated only in .NET Framework and .NET Core versions 2.0 - 3.1. > - On all applicable .NET Framework versions: A instance that's returned by the property will throw an if the length of `value` is greater than 65535. All other instances accept a `value` of any length. @@ -2162,21 +2162,21 @@ System.Void - - + + The value to set. The content of the header to set. Sets the specified header to the specified value. - method inserts a new header into the list of header name/value pairs. - - If the header specified in `header` is already present, `value` replaces the existing value. - + method inserts a new header into the list of header name/value pairs. + + If the header specified in `header` is already present, `value` replaces the existing value. + > [!NOTE] > The length of `value` is validated only in .NET Framework and .NET Core versions 2.0 - 3.1. > - On all applicable .NET Framework versions: A instance that's returned by the property will throw an if the length of `value` is greater than 65535. All other instances accept a `value` of any length. @@ -2230,8 +2230,8 @@ System.Void - - + + [System.Runtime.CompilerServices.Nullable(2)] @@ -2245,22 +2245,22 @@ The content of the header to set. Sets the specified header to the specified value. - method inserts a new header into the list of header name/value pairs. - - If the header specified in `header` is already present, `value` replaces the existing value. - - - -## Examples - The following example uses the method to set the value of an existing header. - + method inserts a new header into the list of header name/value pairs. + + If the header specified in `header` is already present, `value` replaces the existing value. + + + +## Examples + The following example uses the method to set the value of an existing header. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/WebHeaderCollection_Set/CPP/webheadercollection_set.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Net/WebHeaderCollection/Set/webheadercollection_set.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/WebHeaderCollection_Set/VB/webheadercollection_set.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/WebHeaderCollection_Set/VB/webheadercollection_set.vb" id="Snippet1"::: + > [!NOTE] > The length of `value` is validated only in .NET Framework and .NET Core versions 2.0 - 3.1. > - On all applicable .NET Framework versions: A instance that's returned by the property will throw an if the length of `value` is greater than 65535. All other instances accept a `value` of any length. @@ -2272,10 +2272,10 @@ is or . .NET Framework and .NET Core versions 2.0 - 3.1 only: The length of is greater than 65535. - is a restricted header. - - -or- - + is a restricted header. + + -or- + or contain invalid characters. @@ -2368,8 +2368,8 @@ This member is an explicit interface member implementation. It can be used only System.Void - - + + The object into which this will be serialized. diff --git a/xml/System.Net/WebRequest.xml b/xml/System.Net/WebRequest.xml index fc693cb80e0..837724512c6 100644 --- a/xml/System.Net/WebRequest.xml +++ b/xml/System.Net/WebRequest.xml @@ -74,34 +74,34 @@ Makes a request to a Uniform Resource Identifier (URI). This is an class. - [!IMPORTANT] > Don't use `WebRequest` or its derived classes for new development. Instead, use the class. - is the `abstract` base class for .NET's request/response model for accessing data from the Internet. An application that uses the request/response model can request data from the Internet in a protocol-agnostic manner, in which the application works with instances of the class while protocol-specific descendant classes carry out the details of the request. - - Requests are sent from an application to a particular URI, such as a Web page on a server. The URI determines the proper descendant class to create from a list of descendants registered for the application. descendants are typically registered to handle a specific protocol, such as HTTP or FTP, but can be registered to handle a request to a specific server or path on a server. - - The class throws a when errors occur while accessing an Internet resource. The property is one of the values that indicates the source of the error. When is , the property contains the received from the Internet resource. - - Because the class is an `abstract` class, the actual behavior of instances at run time is determined by the descendant class returned by method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . - + is the `abstract` base class for .NET's request/response model for accessing data from the Internet. An application that uses the request/response model can request data from the Internet in a protocol-agnostic manner, in which the application works with instances of the class while protocol-specific descendant classes carry out the details of the request. + + Requests are sent from an application to a particular URI, such as a Web page on a server. The URI determines the proper descendant class to create from a list of descendants registered for the application. descendants are typically registered to handle a specific protocol, such as HTTP or FTP, but can be registered to handle a request to a specific server or path on a server. + + The class throws a when errors occur while accessing an Internet resource. The property is one of the values that indicates the source of the error. When is , the property contains the received from the Internet resource. + + Because the class is an `abstract` class, the actual behavior of instances at run time is determined by the descendant class returned by method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . + > [!NOTE] -> Use the method to initialize new instances. Do not use the constructor. - +> Use the method to initialize new instances. Do not use the constructor. + > [!NOTE] > If the application that creates the WebRequest object runs with the credentials of a Normal user, the application will not be able to access certificates installed in the local machine store unless permission has been explicitly given to the user to do so. - -## Examples - The following example shows how to create a instance and return the response. - + +## Examples + The following example shows how to create a instance and return the response. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NCLWebRequestSimple/CPP/webrequestget.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Net/WebRequest/Overview/webrequestget.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NCLWebRequestSimple/VB/webrequestget.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NCLWebRequestSimple/VB/webrequestget.vb" id="Snippet1"::: + ]]> @@ -166,18 +166,18 @@ Initializes a new instance of the class. - method to initialize new instances. Do not use the constructor. - -## Examples - The following example shows how to create a instance by calling the method on the class. - + +## Examples + The following example shows how to create a instance by calling the method on the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/Classic WebRequest.WebRequest Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Net/WebRequest/.ctor/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic WebRequest.WebRequest Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic WebRequest.WebRequest Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -231,22 +231,22 @@ - - + + The information required to serialize the new instance. A that indicates the source of the serialized stream associated with the new instance. Initializes a new instance of the class from the specified instances of the and classes. - interface for the descendant. - + interface for the descendant. + > [!NOTE] -> An application must run in full trust mode when using serialization. - +> An application must run in full trust mode when using serialization. + ]]> Any attempt is made to access the constructor, when the constructor is not overridden in a descendant class. @@ -299,14 +299,14 @@ Aborts the request. - method cancels asynchronous requests to Internet resources started with the method. - + method cancels asynchronous requests to Internet resources started with the method. + > [!NOTE] -> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . - +> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . + ]]> Any attempt is made to access the method, when the method is not overridden in a descendant class. @@ -360,22 +360,22 @@ Gets or sets values indicating the level of authentication and impersonation used for this request. - A bitwise combination of the values. The default value is . - - In mutual authentication, both the client and server present credentials to establish their identity. The and values are relevant for Kerberos authentication. Kerberos authentication can be supported directly, or can be used if the Negotiate security protocol is used to select the actual security protocol. For more information about authentication protocols, see [Internet Authentication](/dotnet/framework/network-programming/internet-authentication). - - To determine whether mutual authentication occurred, check the property. - + A bitwise combination of the values. The default value is . + + In mutual authentication, both the client and server present credentials to establish their identity. The and values are relevant for Kerberos authentication. Kerberos authentication can be supported directly, or can be used if the Negotiate security protocol is used to select the actual security protocol. For more information about authentication protocols, see [Internet Authentication](/dotnet/framework/network-programming/internet-authentication). + + To determine whether mutual authentication occurred, check the property. + If you specify the authentication flag value and mutual authentication does not occur, your application will receive an with a inner exception indicating that mutual authentication failed. - @@ -439,23 +439,23 @@ When overridden in a descendant class, provides an asynchronous version of the method. An that references the asynchronous request. - method starts an asynchronous request for a stream used to send data to an Internet resource. The callback method that implements the delegate uses the method to return the request stream. - + method starts an asynchronous request for a stream used to send data to an Internet resource. The callback method that implements the delegate uses the method to return the request stream. + > [!NOTE] -> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . - - - -## Examples - The following example uses the to asynchronously obtain the request stream. - +> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . + + + +## Examples + The following example uses the to asynchronously obtain the request stream. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/WebRequest_BeginGetRequest/CPP/webrequest_begingetrequest.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Net/WebRequest/BeginGetRequestStream/webrequest_begingetrequest.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/WebRequest_BeginGetRequest/VB/webrequest_begingetrequest.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/WebRequest_BeginGetRequest/VB/webrequest_begingetrequest.vb" id="Snippet3"::: + ]]> Any attempt is made to access the method, when the method is not overridden in a descendant class. @@ -522,26 +522,26 @@ When overridden in a descendant class, begins an asynchronous request for an Internet resource. An that references the asynchronous request. - method starts an asynchronous request for a response. The callback method that implements the delegate uses the method to return the from the Internet resource. - + method starts an asynchronous request for a response. The callback method that implements the delegate uses the method to return the from the Internet resource. + > [!NOTE] -> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . - +> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . + > [!NOTE] -> If a WebException is thrown, use the and properties of the exception to determine the response from the server. - - - -## Examples - The following example uses to asynchronously request the target resource. When the resource has been obtained, the specified callback method will be executed. - +> If a WebException is thrown, use the and properties of the exception to determine the response from the server. + + + +## Examples + The following example uses to asynchronously request the target resource. When the resource has been obtained, the specified callback method will be executed. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/WebRequest_BeginGetResponse/CPP/webrequest_begingetresponse.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Net/WebRequest/BeginGetResponse/webrequest_begingetresponse.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/WebRequest_BeginGetResponse/VB/webrequest_begingetresponse.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/WebRequest_BeginGetResponse/VB/webrequest_begingetresponse.vb" id="Snippet2"::: + ]]> Any attempt is made to access the method, when the method is not overridden in a descendant class. @@ -613,23 +613,23 @@ Gets or sets the cache policy for this request. A object that defines a cache policy. - property for requests that use the Hypertext Transfer Protocol (HTTP) or Secure Hypertext Transfer Protocol (HTTPS) URI scheme. - - A copy of a resource is only added to the cache if the response stream for the resource is retrieved and read to the end of the stream. So another request for the same resource could use a cached copy, depending on the cache policy level for this request. - - - -## Examples - The following code example demonstrates setting the cache policy for a Web request. - + property for requests that use the Hypertext Transfer Protocol (HTTP) or Secure Hypertext Transfer Protocol (HTTPS) URI scheme. + + A copy of a resource is only added to the cache if the response stream for the resource is retrieved and read to the end of the stream. So another request for the same resource could use a cached copy, depending on the cache policy level for this request. + + + +## Examples + The following code example demonstrates setting the cache policy for a Web request. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NCLSimpleCache/CPP/NCLSimpleCache.cpp" id="Snippet2"::: - :::code language="csharp" source="~/snippets/csharp/System.Net/WebRequest/CachePolicy/example.cs" id="Snippet2"::: - + :::code language="csharp" source="~/snippets/csharp/System.Net/WebRequest/CachePolicy/example.cs" id="Snippet2"::: + ]]> @@ -695,14 +695,14 @@ When overridden in a descendant class, gets or sets the name of the connection group for the request. The name of the connection group for the request. - property associates specific requests within an application to one or more connection pools. - + property associates specific requests within an application to one or more connection pools. + > [!NOTE] -> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . - +> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . + ]]> Any attempt is made to get or set the property, when the property is not overridden in a descendant class. @@ -755,23 +755,23 @@ When overridden in a descendant class, gets or sets the content length of the request data being sent. The number of bytes of request data being sent. - property contains the number of bytes of data sent to the Internet resource by the instance. - + property contains the number of bytes of data sent to the Internet resource by the instance. + > [!NOTE] -> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . - - - -## Examples - The following example sets the property to the amount of bytes in the outgoing byte buffer. - +> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . + + + +## Examples + The following example sets the property to the amount of bytes in the outgoing byte buffer. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/WebRequest_ContentType/CPP/webrequest_contenttype.cpp" id="Snippet4"::: :::code language="csharp" source="~/snippets/csharp/System.Net/WebRequest/ContentLength/webrequest_contenttype.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/WebRequest_ContentType/VB/webrequest_contenttype.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/WebRequest_ContentType/VB/webrequest_contenttype.vb" id="Snippet4"::: + ]]> Any attempt is made to get or set the property, when the property is not overridden in a descendant class. @@ -838,23 +838,23 @@ When overridden in a descendant class, gets or sets the content type of the request data being sent. The content type of the request data. - property contains the media type of the request. This is typically the MIME encoding of the content. - + property contains the media type of the request. This is typically the MIME encoding of the content. + > [!NOTE] -> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . - - - -## Examples - The following example sets the property to the appropriate media type. - +> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . + + + +## Examples + The following example sets the property to the appropriate media type. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/WebRequest_ContentType/CPP/webrequest_contenttype.cpp" id="Snippet4"::: :::code language="csharp" source="~/snippets/csharp/System.Net/WebRequest/ContentLength/webrequest_contenttype.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/WebRequest_ContentType/VB/webrequest_contenttype.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/WebRequest_ContentType/VB/webrequest_contenttype.vb" id="Snippet4"::: + ]]> Any attempt is made to get or set the property, when the property is not overridden in a descendant class. @@ -923,39 +923,39 @@ Initializes a new instance for the specified URI scheme. A descendant for the specific URI scheme. - method returns a descendant of the class determined at run time as the closest registered match for `requestUri`. - - For example, when a URI beginning with `http://` or `https://` is passed in `requestUri`, an is returned by . If a URI beginning with `ftp://` is passed instead, the method will return a instance. If a URI beginning with `file://` is passed instead, the method will return a instance. - - The pre-registered reserve types already registered include the following: - -- `http://` - -- `https://` - -- `ftp://` - -- `file://` - - .NET includes support for the `http://`, `https://`, `ftp://`, and `file://` URI schemes. Custom descendants to handle other requests are registered with the method. - - The method uses the `requestUriString` parameter to create a instance that it passes to the new . - + method returns a descendant of the class determined at run time as the closest registered match for `requestUri`. + + For example, when a URI beginning with `http://` or `https://` is passed in `requestUri`, an is returned by . If a URI beginning with `ftp://` is passed instead, the method will return a instance. If a URI beginning with `file://` is passed instead, the method will return a instance. + + The pre-registered reserve types already registered include the following: + +- `http://` + +- `https://` + +- `ftp://` + +- `file://` + + .NET includes support for the `http://`, `https://`, `ftp://`, and `file://` URI schemes. Custom descendants to handle other requests are registered with the method. + + The method uses the `requestUriString` parameter to create a instance that it passes to the new . + > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). - - - -## Examples - The following example uses to instantiate an instance. A string representing the target URL is used as the constructor parameter. - + + + +## Examples + The following example uses to instantiate an instance. A string representing the target URL is used as the constructor parameter. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/WebResponse_ResponseUri/CPP/webresponse_responseuri.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Net/WebRequest/Create/webresponse_responseuri.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/WebResponse_ResponseUri/VB/webresponse_responseuri.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/WebResponse_ResponseUri/VB/webresponse_responseuri.vb" id="Snippet1"::: + ]]> The request scheme specified in has not been registered. @@ -1021,41 +1021,41 @@ Note: In .NET for Win Initializes a new instance for the specified URI scheme. A descendant for the specified URI scheme. - method returns a descendant of the class determined at run time as the closest registered match for `requestUri`. - - For example, if you create a descendant, Handler1, to handle requests to `http://www.contoso.com/text/` and another named Handler2 to handle requests to `http://www.contoso.com/code/`, you can use method to return the WebRequest descendant associated with either specified URI. - - To return a descendant of the class based on only the scheme portion of a URI, use the method. - - For example, when a URI beginning with `http://` or `https://` is passed in `requestUri`, an is returned by . If a URI beginning with `ftp://` is passed instead, the method will return a instance. If a URI beginning with `file://` is passed instead, the method will return a instance. - - The pre-registered reserve types already registered include the following: - -- `http://` - -- `https://` - -- `ftp://` - -- `file://` - - .NET includes support for the `http://`, `https://`, `ftp://`, and `file://` URI schemes. Custom descendants to handle other requests are registered with the method. - + method returns a descendant of the class determined at run time as the closest registered match for `requestUri`. + + For example, if you create a descendant, Handler1, to handle requests to `http://www.contoso.com/text/` and another named Handler2 to handle requests to `http://www.contoso.com/code/`, you can use method to return the WebRequest descendant associated with either specified URI. + + To return a descendant of the class based on only the scheme portion of a URI, use the method. + + For example, when a URI beginning with `http://` or `https://` is passed in `requestUri`, an is returned by . If a URI beginning with `ftp://` is passed instead, the method will return a instance. If a URI beginning with `file://` is passed instead, the method will return a instance. + + The pre-registered reserve types already registered include the following: + +- `http://` + +- `https://` + +- `ftp://` + +- `file://` + + .NET includes support for the `http://`, `https://`, `ftp://`, and `file://` URI schemes. Custom descendants to handle other requests are registered with the method. + > [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). - - - -## Examples - The following example uses to instantiate an instance. A Uri representing the target URL is used as the constructor parameter. - +> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). + + + +## Examples + The following example uses to instantiate an instance. A Uri representing the target URL is used as the constructor parameter. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/WebRequest_Create/CPP/webrequest_create.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Net/WebRequest/Create/webrequest_create.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/WebRequest_Create/VB/webrequest_create.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/WebRequest_Create/VB/webrequest_create.vb" id="Snippet1"::: + ]]> The request scheme specified in is not registered. @@ -1108,23 +1108,23 @@ Note: In .NET for Win System.Net.WebRequest - + A containing the URI of the requested resource. Initializes a new instance for the specified URI scheme. A descendant for the specified URI scheme. - method returns a descendant instance based on only the scheme portion of a URI. - - For example, when a URI beginning with `http://` is passed in `requestUri`, an is returned by . If a URI beginning with `file://` is passed instead, the method will return a . - + method returns a descendant instance based on only the scheme portion of a URI. + + For example, when a URI beginning with `http://` is passed in `requestUri`, an is returned by . If a URI beginning with `file://` is passed instead, the method will return a . + > [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET](/dotnet/framework/network-programming/network-tracing). - +> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET](/dotnet/framework/network-programming/network-tracing). + ]]> The request scheme specified in is not registered. @@ -1193,17 +1193,17 @@ Note: In .NET for Win Initializes a new instance for the specified URI string. An instance for the specific URI string. - method returns an instance of the class for the `requestUriString`. - - When a URI that begins with `http://` or `https://` is passed in the `requestUriString` parameter, a is returned by . Any other scheme will throw a . - - The method uses the `requestUriString` parameter to create a instance that it passes to the new . If the method is successful, the property on the returned instance is set to `false`. - - .NET includes support for the `http://` and `https://` URI schemes. Custom descendants to handle other requests are registered with the method. The method can be used to create a descendant of the class for other schemes. - + method returns an instance of the class for the `requestUriString`. + + When a URI that begins with `http://` or `https://` is passed in the `requestUriString` parameter, a is returned by . Any other scheme will throw a . + + The method uses the `requestUriString` parameter to create a instance that it passes to the new . If the method is successful, the property on the returned instance is set to `false`. + + .NET includes support for the `http://` and `https://` URI schemes. Custom descendants to handle other requests are registered with the method. The method can be used to create a descendant of the class for other schemes. + ]]> The request scheme specified in is the http or https scheme. @@ -1263,17 +1263,17 @@ Note: In .NET for Win Initializes a new instance for the specified URI. An instance for the specific URI string. - method returns an instance of the class for the `requestUri`. - - When a URI that begins with `http://` or `http://` is passed in the `requestUri` parameter, an is returned by . Another other scheme will throw a . - - The method uses the `requestUri` parameter to create a new instance. If the method is successful, the property on the returned instance is set to `false`. - - .NET includes support for the `http://` and `https://` URI schemes. Custom descendants to handle other requests are registered with the method. The method can be used to create a descendant of the class for other schemes. - + method returns an instance of the class for the `requestUri`. + + When a URI that begins with `http://` or `http://` is passed in the `requestUri` parameter, an is returned by . Another other scheme will throw a . + + The method uses the `requestUri` parameter to create a new instance. If the method is successful, the property on the returned instance is set to `false`. + + .NET includes support for the `http://` and `https://` URI schemes. Custom descendants to handle other requests are registered with the method. The method can be used to create a descendant of the class for other schemes. + ]]> The request scheme specified in is the http or https scheme. @@ -1321,11 +1321,11 @@ Note: In .NET for Win When overridden in a descendant class, gets the factory object derived from the class used to create the instantiated for making the request to the specified URI. The derived type returned by the method. - derived factory object was used to create the request. This object may be [System.Net.Browser.WebRequestCreator.BrowserHttp](https://msdn.microsoft.com/library/system.net.browser.webrequestcreator.browserhttp(v=vs.95)) or [System.Net.Browser.WebRequestCreator.ClientHttp](https://msdn.microsoft.com/library/system.net.browser.webrequestcreator.clienthttp(v=vs.95)), but it may also be a custom instance derived from . This allows an application to determine whether the browser hosting Silverlight, the Silverlight client, or some custom object handles HTTP requests and responses for the instance. The method allows an application to configure which derived type will be instantiated when making a request to a specific URI. creators are typically registered to handle a specific protocol, such HTTP or HTTPS, but can be registered to handle a request to a specific server or path on a server. This is useful when more than one derived type can process requests for the same protocol. The Microsoft Silverlight 3 and later runtime supports multiple HTTP handlers each having different capabilities. For example, a web service that uses Representational State Transfer (REST) might require the [System.Net.Browser.WebRequestCreator.ClientHttp](https://msdn.microsoft.com/library/system.net.browser.webrequestcreator.clienthttp(v=vs.95)) handler while a SOAP web service might be able to use the default [System.Net.Browser.WebRequestCreator.BrowserHttp](https://msdn.microsoft.com/library/system.net.browser.webrequestcreator.browserhttp(v=vs.95)) handler. - + ]]> @@ -1387,23 +1387,23 @@ This property allows an application to determine which When overridden in a descendant class, gets or sets the network credentials used for authenticating the request with the Internet resource. An containing the authentication credentials associated with the request. The default is . - property contains the authentication credentials required to access the Internet resource. - + property contains the authentication credentials required to access the Internet resource. + > [!NOTE] -> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . - - - -## Examples - The following example sets the property using the default credentials of the current user. When the request is made, credentials stored in this property are used to validate the client. This is identical to setting the property to `true`. - +> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . + + + +## Examples + The following example sets the property using the default credentials of the current user. When the request is made, credentials stored in this property are used to validate the client. This is identical to setting the property to `true`. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NCLWebRequestSimple/CPP/webrequestget.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Net/WebRequest/Overview/webrequestget.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NCLWebRequestSimple/VB/webrequestget.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NCLWebRequestSimple/VB/webrequestget.vb" id="Snippet2"::: + ]]> Any attempt is made to get or set the property, when the property is not overridden in a descendant class. @@ -1467,27 +1467,27 @@ This property allows an application to determine which Gets or sets the default cache policy for this request. A that specifies the cache policy in effect for this request when no other policy is applicable. - property specified for this request. - -- The machine and application configuration files do not specify a cache policy that is applicable to the Uniform Resource Identifier (URI) used to create this request. - - The cache policy determines whether the requested resource can be taken from a cache instead of sending the request to the resource host computer. - - A copy of a resource is only added to the cache if the response stream for the resource is retrieved and read to the end of the stream. So another request for the same resource could use a cached copy, depending on the cache policy level for this request. - - - -## Examples - The following code example demonstrates setting the default cache policy for Web requests. - + property specified for this request. + +- The machine and application configuration files do not specify a cache policy that is applicable to the Uniform Resource Identifier (URI) used to create this request. + + The cache policy determines whether the requested resource can be taken from a cache instead of sending the request to the resource host computer. + + A copy of a resource is only added to the cache if the response stream for the resource is retrieved and read to the end of the stream. So another request for the same resource could use a cached copy, depending on the cache policy level for this request. + + + +## Examples + The following code example demonstrates setting the default cache policy for Web requests. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NCLSimpleCache/CPP/NCLSimpleCache.cpp" id="Snippet15"::: - :::code language="csharp" source="~/snippets/csharp/System.Net/WebRequest/CachePolicy/example.cs" id="Snippet15"::: - + :::code language="csharp" source="~/snippets/csharp/System.Net/WebRequest/CachePolicy/example.cs" id="Snippet15"::: + ]]> @@ -1553,15 +1553,15 @@ This property allows an application to determine which Gets or sets the global HTTP proxy. An used by every call to instances of . - property gets or sets the global proxy. The property determines the default proxy that all instances use if the request supports proxies and no proxy is set explicitly using the property. Proxies are currently supported by and . - - The property reads proxy settings from the app.config file. If there is no config file, the current user's Internet Explorer (IE) proxy settings are used. - - If the property is set to null, all subsequent instances of the class created by the or methods do not have a proxy. - + property gets or sets the global proxy. The property determines the default proxy that all instances use if the request supports proxies and no proxy is set explicitly using the property. Proxies are currently supported by and . + + The property reads proxy settings from the app.config file. If there is no config file, the current user's Internet Explorer (IE) proxy settings are used. + + If the property is set to null, all subsequent instances of the class created by the or methods do not have a proxy. + ]]> @@ -1616,26 +1616,26 @@ This property allows an application to determine which When overridden in a descendant class, returns a for writing data to the Internet resource. A to write data to. - method completes an asynchronous stream request that was started by the method. - + method completes an asynchronous stream request that was started by the method. + > [!NOTE] -> To avoid timing issues with garbage collection, be sure to close the response stream by calling the method on the stream returned by after calling . - +> To avoid timing issues with garbage collection, be sure to close the response stream by calling the method on the stream returned by after calling . + > [!NOTE] -> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . - - - -## Examples - The following example obtains and uses the request stream by calling the . The method completes the asynchronous call to . - +> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . + + + +## Examples + The following example obtains and uses the request stream by calling the . The method completes the asynchronous call to . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/WebRequest_BeginGetRequest/CPP/webrequest_begingetrequest.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Net/WebRequest/BeginGetRequestStream/webrequest_begingetrequest.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/WebRequest_BeginGetRequest/VB/webrequest_begingetrequest.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/WebRequest_BeginGetRequest/VB/webrequest_begingetrequest.vb" id="Snippet3"::: + ]]> Any attempt is made to access the method, when the method is not overridden in a descendant class. @@ -1693,23 +1693,23 @@ This property allows an application to determine which When overridden in a descendant class, returns a . A that contains a response to the Internet request. - method completes an asynchronous request for an Internet resource that was started with the method. - + method completes an asynchronous request for an Internet resource that was started with the method. + > [!NOTE] -> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . - - - -## Examples - The following example calls the to retrieve the target resource. - +> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . + + + +## Examples + The following example calls the to retrieve the target resource. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/WebRequest_BeginGetResponse/CPP/webrequest_begingetresponse.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Net/WebRequest/BeginGetResponse/webrequest_begingetresponse.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/WebRequest_BeginGetResponse/VB/webrequest_begingetresponse.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/WebRequest_BeginGetResponse/VB/webrequest_begingetresponse.vb" id="Snippet1"::: + ]]> Any attempt is made to access the method, when the method is not overridden in a descendant class. @@ -1760,19 +1760,19 @@ This property allows an application to determine which System.Void - - + + The to populate with data. A that specifies the destination for this serialization. Populates a with the data needed to serialize the target object. - are automatically tracked and serialized by the formatter. - + are automatically tracked and serialized by the formatter. + ]]> @@ -1819,25 +1819,25 @@ This property allows an application to determine which When overridden in a descendant class, returns a for writing data to the Internet resource. A for writing data to the Internet resource. - method initiates a request to send data to the Internet resource and returns a instance for sending data to the Internet resource. - - The method provides synchronous access to the . For asynchronous access, use the and methods. - + method initiates a request to send data to the Internet resource and returns a instance for sending data to the Internet resource. + + The method provides synchronous access to the . For asynchronous access, use the and methods. + > [!NOTE] -> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . - - - -## Examples - The following example uses the method to obtain a stream and then writes data that stream. - +> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . + + + +## Examples + The following example uses the method to obtain a stream and then writes data that stream. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/WebRequest_ContentType/CPP/webrequest_contenttype.cpp" id="Snippet4"::: :::code language="csharp" source="~/snippets/csharp/System.Net/WebRequest/ContentLength/webrequest_contenttype.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/WebRequest_ContentType/VB/webrequest_contenttype.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/WebRequest_ContentType/VB/webrequest_contenttype.vb" id="Snippet4"::: + ]]> Any attempt is made to access the method, when the method is not overridden in a descendant class. @@ -1886,13 +1886,13 @@ This property allows an application to determine which When overridden in a descendant class, returns a for writing data to the Internet resource as an asynchronous operation. The task object representing the asynchronous operation. - object will complete when the for writing data to the Internet resource is available. - - After you call , make sure you close the request stream before you call . - + object will complete when the for writing data to the Internet resource is available. + + After you call , make sure you close the request stream before you call . + 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 . ]]> @@ -1941,28 +1941,28 @@ This property allows an application to determine which When overridden in a descendant class, returns a response to an Internet request. A containing the response to the Internet request. - method sends a request to an Internet resource and returns a instance. If the request has already been initiated by a call to , the method completes the request and returns any response. - - The method provides synchronous access to the . For asynchronous access, use the and methods. - + method sends a request to an Internet resource and returns a instance. If the request has already been initiated by a call to , the method completes the request and returns any response. + + The method provides synchronous access to the . For asynchronous access, use the and methods. + > [!NOTE] -> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . - +> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . + > [!NOTE] -> If a WebException is thrown, use the and properties of the exception to determine the response from the server. - - - -## Examples - The following example sets the property to 10000 milliseconds. If the timeout period expires before the resource can be returned, a is thrown. - +> If a WebException is thrown, use the and properties of the exception to determine the response from the server. + + + +## Examples + The following example sets the property to 10000 milliseconds. If the timeout period expires before the resource can be returned, a is thrown. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/WebRequest_Timeout/CPP/webrequest_timeout.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Net/WebRequest/GetResponse/webrequest_timeout.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/WebRequest_Timeout/VB/webrequest_timeout.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/WebRequest_Timeout/VB/webrequest_timeout.vb" id="Snippet1"::: + ]]> Any attempt is made to access the method, when the method is not overridden in a descendant class. @@ -2011,11 +2011,11 @@ This property allows an application to determine which When overridden in a descendant class, returns a response to an Internet request as an asynchronous operation. The task object representing the asynchronous operation. - object will complete after a response to an Internet request is available. - + object will complete after a response to an Internet request is available. + 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 . ]]> @@ -2063,13 +2063,13 @@ This property allows an application to determine which Returns a proxy configured with the Internet Explorer settings of the currently impersonated user. An used by every call to instances of . - method reads the current user's Internet Explorer (IE) proxy settings. This process includes the IE options to automatically detect proxy settings, use an automatic configuration script, manual proxy server settings, and advanced manual proxy server settings. - - If your application is impersonating several users, you can use the method to retrieve a proxy for each impersonated user. - + method reads the current user's Internet Explorer (IE) proxy settings. This process includes the IE options to automatically detect proxy settings, use an automatic configuration script, manual proxy server settings, and advanced manual proxy server settings. + + If your application is impersonating several users, you can use the method to retrieve a proxy for each impersonated user. + ]]> @@ -2119,23 +2119,23 @@ This property allows an application to determine which When overridden in a descendant class, gets or sets the collection of header name/value pairs associated with the request. A containing the header name/value pairs associated with this request. - property contains a instance containing the header information to send to the Internet resource. - + property contains a instance containing the header information to send to the Internet resource. + > [!NOTE] -> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . - - - -## Examples - The following example displays the header name/value pairs associated with this request. - +> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . + + + +## Examples + The following example displays the header name/value pairs associated with this request. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/WebRequest_Headers/CPP/webrequest_headers.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Net/WebRequest/Headers/webrequest_headers.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/WebRequest_Headers/VB/webrequest_headers.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/WebRequest_Headers/VB/webrequest_headers.vb" id="Snippet1"::: + ]]> Any attempt is made to get or set the property, when the property is not overridden in a descendant class. @@ -2193,11 +2193,11 @@ This property allows an application to determine which Gets or sets the impersonation level for the current request. A value. - @@ -2247,23 +2247,23 @@ This property allows an application to determine which When overridden in a descendant class, gets or sets the protocol method to use in this request. The protocol method to use in this request. - property contains the request method to use in this request. - + property contains the request method to use in this request. + > [!NOTE] -> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . - - - -## Examples - The following example sets the property to POST to indicate that the request will post data to the target host. - +> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . + + + +## Examples + The following example sets the property to POST to indicate that the request will post data to the target host. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/WebRequest_BeginGetRequest/CPP/webrequest_begingetrequest.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Net/WebRequest/BeginGetRequestStream/webrequest_begingetrequest.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/WebRequest_BeginGetRequest/VB/webrequest_begingetrequest.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/WebRequest_BeginGetRequest/VB/webrequest_begingetrequest.vb" id="Snippet3"::: + ]]> If the property is not overridden in a descendant class, any attempt is made to get or set the property. @@ -2315,23 +2315,23 @@ This property allows an application to determine which to pre-authenticate; otherwise, . - property indicates whether to send authentication information with subsequent requests without waiting to be challenged by the server. When is `false`, the waits for an authentication challenge before sending authentication information. - + property indicates whether to send authentication information with subsequent requests without waiting to be challenged by the server. When is `false`, the waits for an authentication challenge before sending authentication information. + > [!NOTE] -> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . - - - -## Examples - The following example sets the property to `true` so that the stored in the property will be sent to along with the resource request. - +> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . + + + +## Examples + The following example sets the property to `true` so that the stored in the property will be sent to along with the resource request. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/WebRequest_PreAuthenticate/CPP/webrequest_preauthenticate.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Net/WebRequest/PreAuthenticate/webrequest_preauthenticate.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/WebRequest_PreAuthenticate/VB/webrequest_preauthenticate.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/WebRequest_PreAuthenticate/VB/webrequest_preauthenticate.vb" id="Snippet1"::: + ]]> Any attempt is made to get or set the property, when the property is not overridden in a descendant class. @@ -2395,23 +2395,23 @@ This property allows an application to determine which When overridden in a descendant class, gets or sets the network proxy to use to access this Internet resource. The to use to access the Internet resource. - property identifies the network proxy that the request uses to access the Internet resource. The request is made through the proxy server rather than directly to the Internet resource. - + property identifies the network proxy that the request uses to access the Internet resource. The request is made through the proxy server rather than directly to the Internet resource. + > [!NOTE] -> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . - - - -## Examples - The following example displays the current network proxy address and allows the user to assign a new network proxy address and port number. - +> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . + + + +## Examples + The following example displays the current network proxy address and allows the user to assign a new network proxy address and port number. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/WebRequest_Proxy/CPP/webrequest_proxy.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Net/WebRequest/Proxy/webrequest_proxy.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/WebRequest_Proxy/VB/webrequest_proxy.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/WebRequest_Proxy/VB/webrequest_proxy.vb" id="Snippet1"::: + ]]> Any attempt is made to get or set the property, when the property is not overridden in a descendant class. @@ -2455,7 +2455,7 @@ This property allows an application to determine which System.Void - + The object to register. @@ -2512,35 +2512,35 @@ This property allows an application to determine which if registration is successful; otherwise, . - method registers descendants to service requests. descendants are typically registered to handle a specific protocol, such HTTP or FTP, but can be registered to handle a request to a specific server or path on a server. - - The pre-registered reserve types already registered include the following: - -- `http://` - -- `https://` - -- `ftp://` - -- `file://` - - For more information, see the and methods. - - Duplicate prefixes are not allowed. returns `false` if an attempt is made to register a duplicate prefix. - + method registers descendants to service requests. descendants are typically registered to handle a specific protocol, such HTTP or FTP, but can be registered to handle a request to a specific server or path on a server. + + The pre-registered reserve types already registered include the following: + +- `http://` + +- `https://` + +- `ftp://` + +- `file://` + + For more information, see the and methods. + + Duplicate prefixes are not allowed. returns `false` if an attempt is made to register a duplicate prefix. + > [!NOTE] -> The class is registered to service requests for HTTP and HTTPS schemes by default. Attempts to register a different descendant for these schemes will fail. - +> The class is registered to service requests for HTTP and HTTPS schemes by default. Attempts to register a different descendant for these schemes will fail. + ]]> - is - - -or- - + is + + -or- + is . @@ -2589,23 +2589,23 @@ This property allows an application to determine which When overridden in a descendant class, gets the URI of the Internet resource associated with the request. A representing the resource associated with the request. - property contains the instance that method uses to create the request. - + property contains the instance that method uses to create the request. + > [!NOTE] -> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . - - - -## Examples - The following example checks the property to determine the site originally requested. - +> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . + + + +## Examples + The following example checks the property to determine the site originally requested. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/WebRequest_RequestUri1/CPP/webrequest_requesturi.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Net/WebRequest/RequestUri/webrequest_requesturi.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/WebRequest_RequestUri1/VB/webrequest_requesturi.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/WebRequest_RequestUri1/VB/webrequest_requesturi.vb" id="Snippet1"::: + ]]> Any attempt is made to get or set the property, when the property is not overridden in a descendant class. @@ -2668,8 +2668,8 @@ This property allows an application to determine which System.Void - - + + A , which holds the serialized data for the . @@ -2720,23 +2720,23 @@ This property allows an application to determine which Gets or sets the length of time, in milliseconds, before the request times out. The length of time, in milliseconds, until the request times out, or the value to indicate that the request does not time out. The default value is defined by the descendant class. - property indicates the length of time, in milliseconds, until the request times out and throws a . The property affects only synchronous requests made with the method. To time out asynchronous requests, use the method. - + property indicates the length of time, in milliseconds, until the request times out and throws a . The property affects only synchronous requests made with the method. To time out asynchronous requests, use the method. + > [!NOTE] -> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . - - - -## Examples - The following example sets the property to 10000 milliseconds. If the timeout period expires before the resource can be returned, a is thrown. - +> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . + + + +## Examples + The following example sets the property to 10000 milliseconds. If the timeout period expires before the resource can be returned, a is thrown. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/WebRequest_Timeout/CPP/webrequest_timeout.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Net/WebRequest/GetResponse/webrequest_timeout.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/WebRequest_Timeout/VB/webrequest_timeout.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/WebRequest_Timeout/VB/webrequest_timeout.vb" id="Snippet1"::: + ]]> Any attempt is made to get or set the property, when the property is not overridden in a descendant class. @@ -2788,11 +2788,11 @@ This property allows an application to determine which if the default credentials are used; otherwise . The default value is . - object should, if requested by the server, be authenticated using the credentials of the currently logged on user. For client applications, this is the desired behavior in most scenarios. For middle tier applications, such as ASP.NET applications, instead of using this property, you would typically set the property to the credentials of the client on whose behalf the request is made. - + object should, if requested by the server, be authenticated using the credentials of the currently logged on user. For client applications, this is the desired behavior in most scenarios. For middle tier applications, such as ASP.NET applications, instead of using this property, you would typically set the property to the credentials of the client on whose behalf the request is made. + ]]> You attempted to set this property after the request was sent. diff --git a/xml/System.Net/WebResponse.xml b/xml/System.Net/WebResponse.xml index 54e65f9d7f4..b3431a6f2a7 100644 --- a/xml/System.Net/WebResponse.xml +++ b/xml/System.Net/WebResponse.xml @@ -78,22 +78,22 @@ Provides a response from a Uniform Resource Identifier (URI). This is an class. - class is the `abstract` base class from which protocol-specific response classes are derived. Applications can participate in request and response transactions in a protocol-agnostic manner using instances of the class while protocol-specific classes derived from carry out the details of the request. - - Client applications do not create objects directly; they are created by calling the method on a instance. - - - -## Examples - The following example creates a instance from a . - + class is the `abstract` base class from which protocol-specific response classes are derived. Applications can participate in request and response transactions in a protocol-agnostic manner using instances of the class while protocol-specific classes derived from carry out the details of the request. + + Client applications do not create objects directly; they are created by calling the method on a instance. + + + +## Examples + The following example creates a instance from a . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/Classic WebRequest Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Net/WebResponse/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic WebRequest Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic WebRequest Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -155,11 +155,11 @@ Initializes a new instance of the class. - constructor directly; use the method on a instance. - + constructor directly; use the method on a instance. + ]]> @@ -216,19 +216,19 @@ - - + + An instance of the class that contains the information required to serialize the new instance. An instance of the class that indicates the source of the serialized stream that is associated with the new instance. Initializes a new instance of the class from the specified instances of the and classes. - interface for the descendant. - + interface for the descendant. + ]]> Any attempt is made to access the constructor, when the constructor is not overridden in a descendant class. @@ -275,26 +275,26 @@ When overridden by a descendant class, closes the response stream. - method cleans up the resources used by a and closes the underlying stream by calling the method. - + method cleans up the resources used by a and closes the underlying stream by calling the method. + > [!NOTE] -> The response must be closed to avoid running out of system resources. The response stream can be closed by calling or . - +> The response must be closed to avoid running out of system resources. The response stream can be closed by calling or . + > [!NOTE] -> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by . For more information about default values and exceptions, please see the documentation for the descendant classes, such as and . - - - -## Examples - The following example uses the method to close the `WebResponse`. - +> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by . For more information about default values and exceptions, please see the documentation for the descendant classes, such as and . + + + +## Examples + The following example uses the method to close the `WebResponse`. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/WebResponse_Close/CPP/webresponse_close.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Net/WebResponse/Close/webresponse_close.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/WebResponse_Close/VB/webresponse_close.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/WebResponse_Close/VB/webresponse_close.vb" id="Snippet1"::: + ]]> Any attempt is made to access the method, when the method is not overridden in a descendant class. @@ -347,23 +347,23 @@ When overridden in a descendant class, gets or sets the content length of data being received. The number of bytes returned from the Internet resource. - property contains the length, in bytes, of the response from the Internet resource. For request methods that contain header information, the does not include the length of the header information. - + property contains the length, in bytes, of the response from the Internet resource. For request methods that contain header information, the does not include the length of the header information. + > [!NOTE] -> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by . For more information about default values and exceptions, please see the documentation for the descendant classes, such as and . - - - -## Examples - The following example uses the property to obtain the Length of the resource returned. - +> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by . For more information about default values and exceptions, please see the documentation for the descendant classes, such as and . + + + +## Examples + The following example uses the property to obtain the Length of the resource returned. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/WebResponse_ContentLength_Type/CPP/webresponse_contentlength_type.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Net/WebResponse/ContentLength/webresponse_contentlength_type.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/WebResponse_ContentLength_Type/VB/webresponse_contentlength_type.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/WebResponse_ContentLength_Type/VB/webresponse_contentlength_type.vb" id="Snippet1"::: + ]]> Any attempt is made to get or set the property, when the property is not overridden in a descendant class. @@ -416,23 +416,23 @@ When overridden in a derived class, gets or sets the content type of the data being received. A string that contains the content type of the response. - property contains the MIME content type of the response from the Internet resource, if known. - + property contains the MIME content type of the response from the Internet resource, if known. + > [!NOTE] -> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by . For more information about default values and exceptions, please see the documentation for the descendant classes, such as and . - - - -## Examples - The following example uses the property to obtain the content type of the response. - +> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by . For more information about default values and exceptions, please see the documentation for the descendant classes, such as and . + + + +## Examples + The following example uses the property to obtain the content type of the response. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/WebResponse_ContentLength_Type/CPP/webresponse_contentlength_type.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Net/WebResponse/ContentLength/webresponse_contentlength_type.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/WebResponse_ContentLength_Type/VB/webresponse_contentlength_type.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/WebResponse_ContentLength_Type/VB/webresponse_contentlength_type.vb" id="Snippet1"::: + ]]> Any attempt is made to get or set the property, when the property is not overridden in a descendant class. @@ -538,16 +538,16 @@ to release both managed and unmanaged resources; to releases only unmanaged resources. Releases the unmanaged resources used by the object, and optionally disposes of the managed resources. - method, if it has been overridden. `Dispose()` invokes this method with the `disposing` parameter set to `true`. `Finalize` invokes this method with `disposing` set to `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. - + + 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. + > [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). - +> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). + ]]> @@ -595,19 +595,19 @@ System.Void - - + + The to populate with data. A that specifies the destination for this serialization. Populates a with the data that is needed to serialize the target object. - are automatically tracked and serialized by the formatter. - + are automatically tracked and serialized by the formatter. + ]]> @@ -659,23 +659,23 @@ When overridden in a descendant class, returns the data stream from the Internet resource. An instance of the class for reading data from the Internet resource. - method returns the data stream from the Internet resource. - + method returns the data stream from the Internet resource. + > [!NOTE] -> The response stream must be closed to avoid running out of system resources. The response stream can be closed by calling or - - - -## Examples - The following example uses to return a instance. A small local buffer is used to read data from the and output it to the console. - +> The response stream must be closed to avoid running out of system resources. The response stream can be closed by calling or + + + +## Examples + The following example uses to return a instance. A small local buffer is used to read data from the and output it to the console. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/WebResponse_GetResponseStream/CPP/webresponse_getresponsestream.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Net/WebResponse/GetResponseStream/webresponse_getresponsestream.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/WebResponse_GetResponseStream/VB/webresponse_getresponsestream.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/WebResponse_GetResponseStream/VB/webresponse_getresponsestream.vb" id="Snippet1"::: + ]]> Any attempt is made to access the method, when the method is not overridden in a descendant class. @@ -724,23 +724,23 @@ When overridden in a derived class, gets a collection of header name-value pairs associated with this request. An instance of the class that contains header values associated with this response. - property contains the name-value header pairs returned in the response. - + property contains the name-value header pairs returned in the response. + > [!NOTE] -> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by . For more information about default values and exceptions, please see the documentation for the descendant classes, such as and . - - - -## Examples - The following example displays all of the header name-value pairs returned in the . - +> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by . For more information about default values and exceptions, please see the documentation for the descendant classes, such as and . + + + +## Examples + The following example displays all of the header name-value pairs returned in the . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/WebResponse_Headers/CPP/webresponse_headers.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Net/WebResponse/Headers/webresponse_headers.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/WebResponse_Headers/VB/webresponse_headers.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/WebResponse_Headers/VB/webresponse_headers.vb" id="Snippet1"::: + ]]> Any attempt is made to get or set the property, when the property is not overridden in a descendant class. @@ -795,13 +795,13 @@ if the response was taken from the cache; otherwise, . - property to set and the class to enumerate the current caching policy. - - Note that getting this property can throw . - + property to set and the class to enumerate the current caching policy. + + Note that getting this property can throw . + ]]> @@ -847,21 +847,21 @@ if both client and server were authenticated; otherwise, . - property using the or enumeration value. The default value for the property contains and . - - Note that getting this property can throw . - - - -## Examples - The following code example checks the value of this property. - + property using the or enumeration value. The default value for the property contains and . + + Note that getting this property can throw . + + + +## Examples + The following code example checks the value of this property. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NCLCredPolicy/CPP/NCLCredPolicy.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/Microsoft.Win32/IntranetZoneCredentialPolicy/Overview/websample.cs" id="Snippet1"::: - + :::code language="csharp" source="~/snippets/csharp/Microsoft.Win32/IntranetZoneCredentialPolicy/Overview/websample.cs" id="Snippet1"::: + ]]> @@ -911,23 +911,23 @@ When overridden in a derived class, gets the URI of the Internet resource that actually responded to the request. An instance of the class that contains the URI of the Internet resource that actually responded to the request. - property contains the URI of the Internet resource that actually provided the response data. This resource might not be the originally requested URI if the underlying protocol allows redirection of the request. - + property contains the URI of the Internet resource that actually provided the response data. This resource might not be the originally requested URI if the underlying protocol allows redirection of the request. + > [!NOTE] -> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by . For more information about default values and exceptions, please see the documentation for the descendant classes, such as and . - - - -## Examples - The following example uses the property to determine the location from which the originated. - +> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by . For more information about default values and exceptions, please see the documentation for the descendant classes, such as and . + + + +## Examples + The following example uses the property to determine the location from which the originated. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/WebResponse_ResponseUri/CPP/webresponse_responseuri.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Net/WebRequest/Create/webresponse_responseuri.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/WebResponse_ResponseUri/VB/webresponse_responseuri.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/WebResponse_ResponseUri/VB/webresponse_responseuri.vb" id="Snippet1"::: + ]]> Any attempt is made to get or set the property, when the property is not overridden in a descendant class. @@ -971,15 +971,15 @@ Gets a value that indicates if headers are supported. - Returns . - + Returns . + if headers are supported; otherwise, . - @@ -1080,8 +1080,8 @@ This member is an explicit interface member implementation. It can be used only System.Void - - + + A that will hold the serialized data for the . diff --git a/xml/System.Net/WebUtility.xml b/xml/System.Net/WebUtility.xml index f9125c54eb7..756ee0bc9b3 100644 --- a/xml/System.Net/WebUtility.xml +++ b/xml/System.Net/WebUtility.xml @@ -193,7 +193,7 @@ System.Void - + [System.Runtime.CompilerServices.Nullable(2)] @@ -201,7 +201,7 @@ - + The string to decode. @@ -338,7 +338,7 @@ System.Void - + [System.Runtime.CompilerServices.Nullable(2)] @@ -346,7 +346,7 @@ - + The string to encode. diff --git a/xml/System.Numerics/BigInteger.xml b/xml/System.Numerics/BigInteger.xml index d2222cb07b1..7ab175e7139 100644 --- a/xml/System.Numerics/BigInteger.xml +++ b/xml/System.Numerics/BigInteger.xml @@ -1250,7 +1250,7 @@ System.Int32 - + The object to compare. diff --git a/xml/System.Reflection.Emit/AssemblyBuilder.xml b/xml/System.Reflection.Emit/AssemblyBuilder.xml index f9c60cde8eb..72f9e1ec33b 100644 --- a/xml/System.Reflection.Emit/AssemblyBuilder.xml +++ b/xml/System.Reflection.Emit/AssemblyBuilder.xml @@ -92,13 +92,9 @@ The following code example shows how to define and use a dynamic assembly. The e - - - - - + Constructor @@ -160,8 +156,8 @@ The following code example shows how to define and use a dynamic assembly. The e System.Void - - + + The logical name of the resource. @@ -241,9 +237,9 @@ The following code example shows how to define and use a dynamic assembly. The e System.Void - - - + + + The logical name of the resource. @@ -651,8 +647,8 @@ The following code example shows how to define and use a dynamic assembly. The e System.Reflection.Emit.ModuleBuilder - - + + The name of the dynamic module. @@ -736,8 +732,8 @@ The following code example shows how to define and use a dynamic assembly. The e System.Reflection.Emit.ModuleBuilder - - + + The name of the dynamic module. @@ -827,9 +823,9 @@ The following code example shows how to define and use a dynamic assembly. The e System.Reflection.Emit.ModuleBuilder - - - + + + The name of the dynamic module. @@ -1003,9 +999,9 @@ The following code example shows how to define and use a dynamic assembly. The e System.Resources.IResourceWriter - - - + + + The logical name of the resource. @@ -1090,10 +1086,10 @@ The following code example shows how to define and use a dynamic assembly. The e System.Resources.IResourceWriter - - - - + + + + The logical name of the resource. @@ -1170,7 +1166,7 @@ The following code example shows how to define and use a dynamic assembly. The e System.Void - + The opaque blob of bytes representing the unmanaged resource. @@ -1228,7 +1224,7 @@ The following code example shows how to define and use a dynamic assembly. The e System.Void - + The name of the resource file. @@ -1365,11 +1361,11 @@ The following code example shows how to define and use a dynamic assembly. The e System.Void - - - - - + + + + + The name of the product with which this assembly is distributed. @@ -3128,7 +3124,7 @@ The following code example shows how to define and use a dynamic assembly. The e System.Void - + The file name of the assembly. @@ -3218,9 +3214,9 @@ The following code example shows how to define and use a dynamic assembly. The e System.Void - - - + + + The file name of the assembly. @@ -3587,7 +3583,7 @@ For information on how to format `binaryAttribute`, see the metadata specificati System.Void - + A reference to the method that represents the entry point for this dynamic assembly. @@ -3624,8 +3620,8 @@ For information on how to format `binaryAttribute`, see the metadata specificati System.Void - - + + A reference to the method that represents the entry point for this dynamic assembly. @@ -3675,11 +3671,11 @@ For information on how to format `binaryAttribute`, see the metadata specificati System.Void - - - - - + + + + + Reserved for future use. Must be IID_NULL. @@ -3726,9 +3722,9 @@ For information on how to format `binaryAttribute`, see the metadata specificati System.Void - - - + + + The type information to return. @@ -3773,7 +3769,7 @@ For information on how to format `binaryAttribute`, see the metadata specificati System.Void - + Points to a location that receives the number of type information interfaces provided by the object. @@ -3816,14 +3812,14 @@ For information on how to format `binaryAttribute`, see the metadata specificati System.Void - - - - - - - - + + + + + + + + Identifies the member. diff --git a/xml/System.Reflection.Emit/ConstructorBuilder.xml b/xml/System.Reflection.Emit/ConstructorBuilder.xml index 9c9f0064478..998ecdf0366 100644 --- a/xml/System.Reflection.Emit/ConstructorBuilder.xml +++ b/xml/System.Reflection.Emit/ConstructorBuilder.xml @@ -77,38 +77,38 @@ Defines and represents a constructor of a dynamic class. - is used to fully describe a constructor in Microsoft intermediate language (MSIL), including the name, attributes, signature, and constructor body. It is used in conjunction with the class to create classes at run time. Call to get an instance of . - - If you do not define a constructor for your dynamic type, a parameterless constructor is provided automatically, and it calls the parameterless constructor of the base class. - - If you use to define a constructor for your dynamic type, a parameterless constructor is not provided. You have the following options for providing a parameterless constructor in addition to the constructor you defined: - -- If you want a parameterless constructor that simply calls the parameterless constructor of the base class, you can use the method to create one (and optionally restrict access to it). Do not provide an implementation for this parameterless constructor. If you do, an exception is thrown when you try to use the constructor. No exception is thrown when the method is called. - -- If you want a parameterless constructor that does something more than simply calling the parameterless constructor of the base class, or that calls another constructor of the base class, or that does something else entirely, you must use the method to create a , and provide your own implementation. - - - -## Examples - The following code sample illustrates the contextual usage of a `ConstructorBuilder`. - + is used to fully describe a constructor in Microsoft intermediate language (MSIL), including the name, attributes, signature, and constructor body. It is used in conjunction with the class to create classes at run time. Call to get an instance of . + + If you do not define a constructor for your dynamic type, a parameterless constructor is provided automatically, and it calls the parameterless constructor of the base class. + + If you use to define a constructor for your dynamic type, a parameterless constructor is not provided. You have the following options for providing a parameterless constructor in addition to the constructor you defined: + +- If you want a parameterless constructor that simply calls the parameterless constructor of the base class, you can use the method to create one (and optionally restrict access to it). Do not provide an implementation for this parameterless constructor. If you do, an exception is thrown when you try to use the constructor. No exception is thrown when the method is called. + +- If you want a parameterless constructor that does something more than simply calling the parameterless constructor of the base class, or that calls another constructor of the base class, or that does something else entirely, you must use the method to create a , and provide your own implementation. + + + +## Examples + The following code sample illustrates the contextual usage of a `ConstructorBuilder`. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Reflection.Emit.ConstructorBuilder Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/ConstructorBuilder/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Reflection.Emit.ConstructorBuilder Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Reflection.Emit.ConstructorBuilder Example/VB/source.vb" id="Snippet1"::: + ]]> - - - - - + + + + + Constructor mscorlib @@ -158,39 +158,39 @@ System.Void - - + + The security action to be taken, such as Demand, Assert, and so on. The set of permissions the action applies to. Adds declarative security to this constructor. - can be called several times, with each call specifying a security action (such as `Demand`, `Assert`, and `Deny`) and a set of permissions that the action applies to. - + can be called several times, with each call specifying a security action (such as `Demand`, `Assert`, and `Deny`) and a set of permissions that the action applies to. + > [!NOTE] -> In the .NET Framework versions 1.0, 1.1, and 2.0, the declarative security attributes applied to a constructor by using this method are stored in the old XML metadata format. See Emitting Declarative Security Attributes. - - - -## Examples - The following code sample illustrates the use of `AddDeclarativeSecurity`. - +> In the .NET Framework versions 1.0, 1.1, and 2.0, the declarative security attributes applied to a constructor by using this method are stored in the old XML metadata format. See Emitting Declarative Security Attributes. + + + +## Examples + The following code sample illustrates the use of `AddDeclarativeSecurity`. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/ConstructorBuilder_Attributes_4/CPP/constructorbuilder_attributes_4.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/ConstructorBuilder/AddDeclarativeSecurity/constructorbuilder_attributes_4.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ConstructorBuilder_Attributes_4/VB/constructorbuilder_attributes_4.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ConstructorBuilder_Attributes_4/VB/constructorbuilder_attributes_4.vb" id="Snippet1"::: + ]]> is invalid (RequestMinimum, RequestOptional, and RequestRefuse are invalid). - The containing type has been previously created using . - - -or- - + The containing type has been previously created using . + + -or- + The permission set contains an action that was added earlier by . is . @@ -234,15 +234,15 @@ Gets the attributes for this constructor. The attributes for this constructor. - @@ -336,17 +336,17 @@ Gets a reference to the object for the type that declares this member. The type that declares this member. - @@ -405,11 +405,11 @@ Defines a parameter of this constructor. An object that represents the new parameter of this constructor. - instead of throwing an exception. There is nothing useful that you can do with this . - + instead of throwing an exception. There is nothing useful that you can do with this . + ]]> @@ -504,13 +504,13 @@ Returns all the custom attributes defined for this constructor. An array of objects representing all the custom attributes of the constructor represented by this instance. - , retrieve the constructor by calling the method on the returned type, and then call the method on the returned . - + , retrieve the constructor by calling the method on the returned type, and then call the method on the returned . + ]]> This method is not currently supported. @@ -559,13 +559,13 @@ Returns the custom attributes identified by the given type. An object array that represents the attributes of this constructor. - , retrieve the constructor by calling the method on the returned type, and then call the method on the returned . - + , retrieve the constructor by calling the method on the returned type, and then call the method on the returned . + ]]> This method is not currently supported. @@ -620,26 +620,26 @@ Gets an for this constructor. An object for this constructor. - - The constructor is a parameterless constructor. - - -or- - + The constructor is a parameterless constructor. + + -or- + The constructor has or flags indicating that it should not have a method body. @@ -684,17 +684,17 @@ Gets an object, with the specified MSIL stream size, that can be used to build a method body for this constructor. An for this constructor. - - The constructor is a parameterless constructor. - - -or- - + The constructor is a parameterless constructor. + + -or- + The constructor has or flags indicating that it should not have a method body. @@ -768,15 +768,15 @@ Returns the method implementation flags for this constructor. The method implementation flags for this constructor. - @@ -810,15 +810,15 @@ Returns a reference to the module that contains this constructor. The module that contains this constructor. - @@ -862,20 +862,20 @@ Returns the parameters of this constructor. An array that represents the parameters of this constructor. - method has been called. In the .NET Framework versions 1.0 and 1.1, is thrown. In the .NET Framework version 2.0, is thrown. - - - -## Examples - The code sample illustrates the use of `GetParameters`. - + method has been called. In the .NET Framework versions 1.0 and 1.1, is thrown. In the .NET Framework version 2.0, is thrown. + + + +## Examples + The code sample illustrates the use of `GetParameters`. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/ConstructorBuilder_GetModule_4/CPP/constructorbuilder_getmodule_4.cpp" id="Snippet4"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/MethodBase/GetMethodImplementationFlags/constructorbuilder_getmodule_4.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ConstructorBuilder_GetModule_4/VB/constructorbuilder_getmodule_4.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ConstructorBuilder_GetModule_4/VB/constructorbuilder_getmodule_4.vb" id="Snippet4"::: + ]]> @@ -913,15 +913,15 @@ Returns the that represents the token for this constructor. The of this constructor. - @@ -1059,16 +1059,16 @@ Dynamically invokes the constructor represented by this instance on the given object, passing along the specified parameters, and under the constraints of the given binder. The value returned by the invoked constructor. - with length 2. - + with length 2. + > [!NOTE] -> Access restrictions are ignored for fully-trusted code. That is, private constructors, methods, fields, and properties can be accessed and invoked using Reflection whenever the code is fully trusted. - +> Access restrictions are ignored for fully-trusted code. That is, private constructors, methods, fields, and properties can be accessed and invoked using Reflection whenever the code is fully trusted. + ]]> This method is not currently supported. You can retrieve the constructor using and call on the returned . @@ -1132,15 +1132,15 @@ Dynamically invokes the constructor reflected by this instance with the specified arguments, under the constraints of the specified . An instance of the class associated with the constructor. - This method is not currently supported. You can retrieve the constructor using and call on the returned . @@ -1192,11 +1192,11 @@ if the specified custom attribute type is defined; otherwise, . - This method is not currently supported. You can retrieve the constructor using and call on the returned . @@ -1230,14 +1230,14 @@ Gets a token that identifies the current dynamic module in metadata. An integer token that identifies the current module in metadata. - [!NOTE] > Information about metadata tokens can be found in the Common Language Infrastructure (CLI) documentation, especially "Partition II: Metadata Definition and Semantics". For more information, see [ECMA 335 Common Language Infrastructure (CLI)](https://www.ecma-international.org/publications-and-standards/standards/ecma-335/). - + ]]> @@ -1345,11 +1345,11 @@ Gets the dynamic module in which this constructor is defined. A object that represents the dynamic module in which this constructor is defined. - method. - + method. + ]]> @@ -1393,15 +1393,15 @@ Retrieves the name of this constructor. The name of this constructor. - @@ -1454,11 +1454,11 @@ Holds a reference to the object from which this object was obtained. The object from which this object was obtained. - object represents a constructor on a particular class. In order to obtain a object, the object that represents the class that supports the constructor is queried. This property holds a reference to that object. - + object represents a constructor on a particular class. In order to obtain a object, the object that represents the class that supports the constructor is queried. This property holds a reference to that object. + ]]> @@ -1497,11 +1497,11 @@ Gets . Returns . - @@ -1557,15 +1557,15 @@ An instance of a helper class to define the custom attribute. Set a custom attribute using a custom attribute builder. - , passing a . - + , passing a . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/ConstructorBuilder_SetCustomAttribute1/CPP/constructorbuilder_setcustomattribute1.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/ConstructorBuilder/SetCustomAttribute/constructorbuilder_setcustomattribute1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ConstructorBuilder_SetCustomAttribute1/VB/constructorbuilder_setcustomattribute1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ConstructorBuilder_SetCustomAttribute1/VB/constructorbuilder_setcustomattribute1.vb" id="Snippet1"::: + ]]> @@ -1625,21 +1625,21 @@ A byte blob representing the attributes. Set a custom attribute using a specified custom attribute blob. - , passing a byte blob. - + + + +## Examples + The following code sample illustrates the use of `SetCustomAttribute` of the context of a , passing a byte blob. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/ConstructorBuilder_SetCustomAttribute2/CPP/constructorbuilder_setcustomattribute2.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/ConstructorBuilder/SetCustomAttribute/constructorbuilder_setcustomattribute2.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ConstructorBuilder_SetCustomAttribute2/VB/constructorbuilder_setcustomattribute2.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ConstructorBuilder_SetCustomAttribute2/VB/constructorbuilder_setcustomattribute2.vb" id="Snippet1"::: + ]]> @@ -1733,15 +1733,15 @@ For information on how to format `binaryAttribute`, see the metadata specificati The method implementation flags. Sets the method implementation flags for this constructor. - The containing type has been created using . @@ -1801,11 +1801,11 @@ For information on how to format `binaryAttribute`, see the metadata specificati System.Void - - - - - + + + + + An array that contains valid MSIL instructions. @@ -1818,19 +1818,19 @@ For information on how to format `binaryAttribute`, see the metadata specificati is . - is negative. - - -or- - - One of specifies an offset outside of . - - -or- - + is negative. + + -or- + + One of specifies an offset outside of . + + -or- + One of specifies an offset that is outside the array. - The containing type was previously created using the method. - - -or- - + The containing type was previously created using the method. + + -or- + This method was called previously on this object. @@ -1858,29 +1858,29 @@ For information on how to format `binaryAttribute`, see the metadata specificati System.Void - - + + The name of the custom attribute. The value of the custom attribute. Sets this constructor's custom attribute associated with symbolic information. - - The containing type has been created using . - - -or- - + The containing type has been created using . + + -or- + The module does not have a symbol writer defined. For example, the module is not a debug module. @@ -1941,11 +1941,11 @@ For information on how to format `binaryAttribute`, see the metadata specificati System.Void - - - - - + + + + + Reserved for future use. Must be IID_NULL. @@ -1955,11 +1955,11 @@ For information on how to format `binaryAttribute`, see the metadata specificati Caller-allocated array which receives the IDs corresponding to the names. Maps a set of names to a corresponding set of dispatch identifiers. - Late-bound access using the COM IDispatch interface is not supported. @@ -1992,9 +1992,9 @@ For information on how to format `binaryAttribute`, see the metadata specificati System.Void - - - + + + The type information to return. @@ -2002,11 +2002,11 @@ For information on how to format `binaryAttribute`, see the metadata specificati Receives a pointer to the requested type information object. Retrieves the type information for an object, which can then be used to get the type information for an interface. - Late-bound access using the COM IDispatch interface is not supported. @@ -2039,17 +2039,17 @@ For information on how to format `binaryAttribute`, see the metadata specificati System.Void - + Points to a location that receives the number of type information interfaces provided by the object. Retrieves the number of type information interfaces that an object provides (either 0 or 1). - Late-bound access using the COM IDispatch interface is not supported. @@ -2082,14 +2082,14 @@ For information on how to format `binaryAttribute`, see the metadata specificati System.Void - - - - - - - - + + + + + + + + Identifies the member. @@ -2102,11 +2102,11 @@ For information on how to format `binaryAttribute`, see the metadata specificati The index of the first argument that has an error. Provides access to properties and methods exposed by an object. - Late-bound access using the COM IDispatch interface is not supported. diff --git a/xml/System.Reflection.Emit/CustomAttributeBuilder.xml b/xml/System.Reflection.Emit/CustomAttributeBuilder.xml index 01c5df3eeef..48c1b344a35 100644 --- a/xml/System.Reflection.Emit/CustomAttributeBuilder.xml +++ b/xml/System.Reflection.Emit/CustomAttributeBuilder.xml @@ -73,20 +73,20 @@ Helps build custom attributes. - and its argument. Then call on an `AssemblyBuilder` to establish the association. - - - -## Examples - The following code sample illustrates the use of `CustomAttributeBuilder`. - + and its argument. Then call on an `AssemblyBuilder` to establish the association. + + + +## Examples + The following code sample illustrates the use of `CustomAttributeBuilder`. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Reflection.Emit.CustomAttributeBuilder Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/CustomAttributeBuilder/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Reflection.Emit.CustomAttributeBuilder Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Reflection.Emit.CustomAttributeBuilder Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -149,26 +149,26 @@ The arguments to the constructor of the custom attribute. Initializes an instance of the class given the constructor for the custom attribute and the arguments to the constructor. - - is static or private. - - -or- - - The number of supplied arguments does not match the number of parameters of the constructor as required by the calling convention of the constructor. - - -or- - - The type of supplied argument does not match the type of the parameter declared in the constructor. - - -or- - + is static or private. + + -or- + + The number of supplied arguments does not match the number of parameters of the constructor as required by the calling convention of the constructor. + + -or- + + The type of supplied argument does not match the type of the parameter declared in the constructor. + + -or- + A supplied argument is a reference type other than or . or is . @@ -234,40 +234,40 @@ Values for the named fields of the custom attribute. Initializes an instance of the class given the constructor for the custom attribute, the arguments to the constructor, and a set of named field/value pairs. - [!IMPORTANT] -> Do not include private fields in `namedFields`. Doing so will cause to be thrown when the method is later called on the completed type. - +> Do not include private fields in `namedFields`. Doing so will cause to be thrown when the method is later called on the completed type. + ]]> - The lengths of the and arrays are different. - - -or- - - is static or private. - - -or- - - The number of supplied arguments does not match the number of parameters of the constructor as required by the calling convention of the constructor. - - -or- - - The type of supplied argument does not match the type of the parameter declared in the constructor. - - -or- - - The types of the field values do not match the types of the named fields. - - -or- - - The field does not belong to the same class or base class as the constructor. - - -or- - + The lengths of the and arrays are different. + + -or- + + is static or private. + + -or- + + The number of supplied arguments does not match the number of parameters of the constructor as required by the calling convention of the constructor. + + -or- + + The type of supplied argument does not match the type of the parameter declared in the constructor. + + -or- + + The types of the field values do not match the types of the named fields. + + -or- + + The field does not belong to the same class or base class as the constructor. + + -or- + A supplied argument or named field is a reference type other than or . One of the parameters is . @@ -332,44 +332,44 @@ Values for the named properties of the custom attribute. Initializes an instance of the class given the constructor for the custom attribute, the arguments to the constructor, and a set of named property or value pairs. - [!IMPORTANT] -> Do not include private properties in `namedProperties`. Doing so will cause to be thrown when the method is later called on the completed type. - +> Do not include private properties in `namedProperties`. Doing so will cause to be thrown when the method is later called on the completed type. + ]]> - The lengths of the and arrays are different. - - -or- - - is static or private. - - -or- - - The number of supplied arguments does not match the number of parameters of the constructor as required by the calling convention of the constructor. - - -or- - - The type of supplied argument does not match the type of the parameter declared in the constructor. - - -or- - - The types of the property values do not match the types of the named properties. - - -or- - - A property has no setter method. - - -or- - - The property does not belong to the same class or base class as the constructor. - - -or- - + The lengths of the and arrays are different. + + -or- + + is static or private. + + -or- + + The number of supplied arguments does not match the number of parameters of the constructor as required by the calling convention of the constructor. + + -or- + + The type of supplied argument does not match the type of the parameter declared in the constructor. + + -or- + + The types of the property values do not match the types of the named properties. + + -or- + + A property has no setter method. + + -or- + + The property does not belong to the same class or base class as the constructor. + + -or- + A supplied argument or named property is a reference type other than or . One of the parameters is . @@ -445,52 +445,52 @@ Values for the named fields of the custom attribute. Initializes an instance of the class given the constructor for the custom attribute, the arguments to the constructor, a set of named property or value pairs, and a set of named field or value pairs. - [!IMPORTANT] -> Do not include private properties or fields in `namedProperties` or `namedFields`. Doing so will cause to be thrown when the method is later called on the completed type. - +> Do not include private properties or fields in `namedProperties` or `namedFields`. Doing so will cause to be thrown when the method is later called on the completed type. + ]]> - The lengths of the and arrays are different. - - -or- - - The lengths of the and arrays are different. - - -or- - - is static or private. - - -or- - - The number of supplied arguments does not match the number of parameters of the constructor as required by the calling convention of the constructor. - - -or- - - The type of supplied argument does not match the type of the parameter declared in the constructor. - - -or- - - The types of the property values do not match the types of the named properties. - - -or- - - The types of the field values do not match the types of the corresponding field types. - - -or- - - A property has no setter. - - -or- - - The property or field does not belong to the same class or base class as the constructor. - - -or- - + The lengths of the and arrays are different. + + -or- + + The lengths of the and arrays are different. + + -or- + + is static or private. + + -or- + + The number of supplied arguments does not match the number of parameters of the constructor as required by the calling convention of the constructor. + + -or- + + The type of supplied argument does not match the type of the parameter declared in the constructor. + + -or- + + The types of the property values do not match the types of the named properties. + + -or- + + The types of the field values do not match the types of the corresponding field types. + + -or- + + A property has no setter. + + -or- + + The property or field does not belong to the same class or base class as the constructor. + + -or- + A supplied argument, named property, or named field is a reference type other than or . One of the parameters is . @@ -522,11 +522,11 @@ System.Void - - - - - + + + + + Reserved for future use. Must be IID_NULL. @@ -536,11 +536,11 @@ Caller-allocated array which receives the IDs corresponding to the names. Maps a set of names to a corresponding set of dispatch identifiers. - The method is called late-bound using the COM IDispatch interface. @@ -573,9 +573,9 @@ System.Void - - - + + + The type information to return. @@ -583,11 +583,11 @@ Receives a pointer to the requested type information object. Retrieves the type information for an object, which can then be used to get the type information for an interface. - The method is called late-bound using the COM IDispatch interface. @@ -620,17 +620,17 @@ System.Void - + Points to a location that receives the number of type information interfaces provided by the object. Retrieves the number of type information interfaces that an object provides (either 0 or 1). - The method is called late-bound using the COM IDispatch interface. @@ -663,14 +663,14 @@ System.Void - - - - - - - - + + + + + + + + Identifies the member. @@ -683,11 +683,11 @@ The index of the first argument that has an error. Provides access to properties and methods exposed by an object. - The method is called late-bound using the COM IDispatch interface. diff --git a/xml/System.Reflection.Emit/EnumBuilder.xml b/xml/System.Reflection.Emit/EnumBuilder.xml index 476f1a859de..989396ea283 100644 --- a/xml/System.Reflection.Emit/EnumBuilder.xml +++ b/xml/System.Reflection.Emit/EnumBuilder.xml @@ -112,11 +112,11 @@ - - - - - + + + + + Constructor mscorlib @@ -2544,7 +2544,7 @@ The following code sample demonstrates the use of the `AssemblyQualifiedName` pr System.Boolean - + [System.Diagnostics.CodeAnalysis.NotNullWhen(true)] @@ -3775,11 +3775,11 @@ For information on how to format `binaryAttribute`, see the metadata specificati System.Void - - - - - + + + + + Reserved for future use. Must be IID_NULL. @@ -3826,9 +3826,9 @@ For information on how to format `binaryAttribute`, see the metadata specificati System.Void - - - + + + The type information to return. @@ -3873,7 +3873,7 @@ For information on how to format `binaryAttribute`, see the metadata specificati System.Void - + Points to a location that receives the number of type information interfaces provided by the object. @@ -3916,14 +3916,14 @@ For information on how to format `binaryAttribute`, see the metadata specificati System.Void - - - - - - - - + + + + + + + + Identifies the member. diff --git a/xml/System.Reflection.Emit/EventBuilder.xml b/xml/System.Reflection.Emit/EventBuilder.xml index 9cb29901be5..8b61e669229 100644 --- a/xml/System.Reflection.Emit/EventBuilder.xml +++ b/xml/System.Reflection.Emit/EventBuilder.xml @@ -77,23 +77,19 @@ Defines events for a class. - - - - - - + Constructor @@ -431,12 +427,12 @@ A byte blob representing the attributes. Set a custom attribute using a specified custom attribute blob. - @@ -686,11 +682,11 @@ For information on how to format `binaryAttribute`, see the metadata specificati System.Void - - - - - + + + + + Reserved for future use. Must be IID_NULL. @@ -700,11 +696,11 @@ For information on how to format `binaryAttribute`, see the metadata specificati Caller-allocated array which receives the IDs corresponding to the names. Maps a set of names to a corresponding set of dispatch identifiers. - The method is called late-bound using the COM IDispatch interface. @@ -737,9 +733,9 @@ For information on how to format `binaryAttribute`, see the metadata specificati System.Void - - - + + + The type information to return. @@ -747,11 +743,11 @@ For information on how to format `binaryAttribute`, see the metadata specificati Receives a pointer to the requested type information object. Retrieves the type information for an object, which can then be used to get the type information for an interface. - The method is called late-bound using the COM IDispatch interface. @@ -784,17 +780,17 @@ For information on how to format `binaryAttribute`, see the metadata specificati System.Void - + Points to a location that receives the number of type information interfaces provided by the object. Retrieves the number of type information interfaces that an object provides (either 0 or 1). - The method is called late-bound using the COM IDispatch interface. @@ -827,14 +823,14 @@ For information on how to format `binaryAttribute`, see the metadata specificati System.Void - - - - - - - - + + + + + + + + Identifies the member. @@ -847,11 +843,11 @@ For information on how to format `binaryAttribute`, see the metadata specificati The index of the first argument that has an error. Provides access to properties and methods exposed by an object. - The method is called late-bound using the COM IDispatch interface. diff --git a/xml/System.Reflection.Emit/EventToken.xml b/xml/System.Reflection.Emit/EventToken.xml index 89b80b73eac..5af7717eb95 100644 --- a/xml/System.Reflection.Emit/EventToken.xml +++ b/xml/System.Reflection.Emit/EventToken.xml @@ -125,7 +125,7 @@ System.Boolean - + The to compare to the current instance. @@ -184,8 +184,8 @@ System.Boolean - - + + The to compare to . @@ -219,8 +219,8 @@ System.Boolean - - + + The to compare to . diff --git a/xml/System.Reflection.Emit/FieldBuilder.xml b/xml/System.Reflection.Emit/FieldBuilder.xml index 3532fac4b8e..7aaa9315213 100644 --- a/xml/System.Reflection.Emit/FieldBuilder.xml +++ b/xml/System.Reflection.Emit/FieldBuilder.xml @@ -77,32 +77,32 @@ Defines and represents a field. This class cannot be inherited. - , , or . - + , , or . + > [!NOTE] -> The method is currently not supported. As a workaround, retrieve the by reflecting on the finished type and call to set the value of the field. - - - -## Examples - The following example illustrates the use of the `FieldBuilder` class. - +> The method is currently not supported. As a workaround, retrieve the by reflecting on the finished type and call to set the value of the field. + + + +## Examples + The following example illustrates the use of the `FieldBuilder` class. + :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/FieldBuilder/Overview/FieldBuilder.cs"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/FieldBuilder_Class_Name/FieldBuilder.vb"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/FieldBuilder_Class_Name/FieldBuilder.vb"::: + ]]> - - - - - + + + + + Constructor mscorlib @@ -160,15 +160,15 @@ Indicates the attributes of this field. This property is read-only. The attributes of this field. - @@ -484,15 +484,15 @@ Retrieves the value of the field supported by the given object. An containing the value of the field reflected by this instance. - is . For example, if the field holds a Boolean primitive value, an instance of with the appropriate Boolean value is returned. Before returning the value, checks to see if the user has access permission. - - Access restrictions are ignored for fully-trusted code. `Private` constructors, methods, fields, and properties can be accessed and invoked using Reflection whenever the code is fully-trusted. - + is . For example, if the field holds a Boolean primitive value, an instance of with the appropriate Boolean value is returned. Before returning the value, checks to see if the user has access permission. + + Access restrictions are ignored for fully-trusted code. `Private` constructors, methods, fields, and properties can be accessed and invoked using Reflection whenever the code is fully-trusted. + ]]> This method is not supported. @@ -573,14 +573,14 @@ Gets a token that identifies the current dynamic module in metadata. An integer token that identifies the current module in metadata. - [!NOTE] > Information about metadata tokens can be found in the Common Language Infrastructure (CLI) documentation, especially "Partition II: Metadata Definition and Semantics". For more information, see [ECMA 335 Common Language Infrastructure (CLI)](https://www.ecma-international.org/publications-and-standards/standards/ecma-335/). - + ]]> @@ -660,14 +660,14 @@ Indicates the name of this field. This property is read-only. A containing the name of this field. - @@ -720,17 +720,17 @@ Indicates the reference to the object from which this object was obtained. This property is read-only. A reference to the object from which this instance was obtained. - object represents a field of a particular class. In order to obtain a object, the object that represents the class that supports the field is queried. This property holds a reference to that object. - - The following code sample illustrates the use of `ReflectedType`. - + object represents a field of a particular class. In order to obtain a object, the object that represents the class that supports the field is queried. This property holds a reference to that object. + + The following code sample illustrates the use of `ReflectedType`. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/FieldBuilder_ReflectedType/CPP/fieldbuilder_reflectedtype.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/FieldBuilder/Attributes/fieldbuilder_reflectedtype.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/FieldBuilder_ReflectedType/VB/fieldbuilder_reflectedtype.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/FieldBuilder_ReflectedType/VB/fieldbuilder_reflectedtype.vb" id="Snippet1"::: + ]]> @@ -787,22 +787,22 @@ The new default value for this field. Sets the default value of this field. - . This is not CLS-compliant, but it can be useful in interop scenarios. - + . This is not CLS-compliant, but it can be useful in interop scenarios. + ]]> The containing type has been created using . - The field is not one of the supported types. - - -or- - - The type of does not match the type of the field. - - -or- - + The field is not one of the supported types. + + -or- + + The type of does not match the type of the field. + + -or- + The field is of type or other reference type, is not , and the value cannot be assigned to the reference type. @@ -900,15 +900,15 @@ An instance of a helper class to define the custom attribute. Sets a custom attribute using a custom attribute builder. - , using a . - + , using a . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/FieldBuilder_SetCustomAttributes/CPP/fieldbuilder_setcustomattributes.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/FieldBuilder/SetCustomAttribute/fieldbuilder_setcustomattributes.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/FieldBuilder_SetCustomAttributes/VB/fieldbuilder_setcustomattributes.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/FieldBuilder_SetCustomAttributes/VB/fieldbuilder_setcustomattributes.vb" id="Snippet1"::: + ]]> @@ -969,21 +969,21 @@ A byte blob representing the attributes. Sets a custom attribute using a specified custom attribute blob. - , using a byte blob. - + + + +## Examples + The following code sample illustrates the use of `SetCustomAttribute` in the context of , using a byte blob. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/FieldBuilder_SetCustomAttributes/CPP/fieldbuilder_setcustomattributes.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/FieldBuilder/SetCustomAttribute/fieldbuilder_setcustomattributes.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/FieldBuilder_SetCustomAttributes/VB/fieldbuilder_setcustomattributes.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/FieldBuilder_SetCustomAttributes/VB/fieldbuilder_setcustomattributes.vb" id="Snippet1"::: + ]]> @@ -1071,21 +1071,21 @@ For information on how to format `binaryAttribute`, see the metadata specificati System.Void - + A descriptor specifying the native marshaling of this field. Describes the native marshaling of the field. - @@ -1140,15 +1140,15 @@ For information on how to format `binaryAttribute`, see the metadata specificati The offset of the field within the type containing this field. Specifies the field layout. - The containing type has been created using . @@ -1242,18 +1242,18 @@ For information on how to format `binaryAttribute`, see the metadata specificati The software preferences of a particular culture. Sets the value of the field supported by the given object. - `obj`. If the field is static, `obj` will be ignored. For non-static fields, `obj` should be an instance of a class that inherits or declares the field. - - The new value is passed as an . For example, if the field's type is Boolean, an instance of with the appropriate Boolean value is passed. Before setting the value, checks to see if the user has access permission. - - Access restrictions are ignored for fully-trusted code. `Private` constructors, methods, fields, and properties can be accessed and invoked using Reflection whenever the code is fully-trusted. - + `obj`. If the field is static, `obj` will be ignored. For non-static fields, `obj` should be an instance of a class that inherits or declares the field. + + The new value is passed as an . For example, if the field's type is Boolean, an instance of with the appropriate Boolean value is passed. Before setting the value, checks to see if the user has access permission. + + Access restrictions are ignored for fully-trusted code. `Private` constructors, methods, fields, and properties can be accessed and invoked using Reflection whenever the code is fully-trusted. + > [!NOTE] -> This method is currently not supported. As a workaround, retrieve the by reflecting on the finished type and call to set the value of the field. - +> This method is currently not supported. As a workaround, retrieve the by reflecting on the finished type and call to set the value of the field. + ]]> This method is not supported. @@ -1286,11 +1286,11 @@ For information on how to format `binaryAttribute`, see the metadata specificati System.Void - - - - - + + + + + Reserved for future use. Must be IID_NULL. @@ -1300,11 +1300,11 @@ For information on how to format `binaryAttribute`, see the metadata specificati Caller-allocated array which receives the IDs corresponding to the names. Maps a set of names to a corresponding set of dispatch identifiers. - The method is called late-bound using the COM IDispatch interface. @@ -1337,9 +1337,9 @@ For information on how to format `binaryAttribute`, see the metadata specificati System.Void - - - + + + The type information to return. @@ -1347,11 +1347,11 @@ For information on how to format `binaryAttribute`, see the metadata specificati Receives a pointer to the requested type information object. Retrieves the type information for an object, which can then be used to get the type information for an interface. - The method is called late-bound using the COM IDispatch interface. @@ -1384,17 +1384,17 @@ For information on how to format `binaryAttribute`, see the metadata specificati System.Void - + Points to a location that receives the number of type information interfaces provided by the object. Retrieves the number of type information interfaces that an object provides (either 0 or 1). - The method is called late-bound using the COM IDispatch interface. @@ -1427,14 +1427,14 @@ For information on how to format `binaryAttribute`, see the metadata specificati System.Void - - - - - - - - + + + + + + + + Identifies the member. @@ -1447,11 +1447,11 @@ For information on how to format `binaryAttribute`, see the metadata specificati The index of the first argument that has an error. Provides access to properties and methods exposed by an object. - The method is called late-bound using the COM IDispatch interface. diff --git a/xml/System.Reflection.Emit/FieldToken.xml b/xml/System.Reflection.Emit/FieldToken.xml index f0d668f5388..da3d7a27fcf 100644 --- a/xml/System.Reflection.Emit/FieldToken.xml +++ b/xml/System.Reflection.Emit/FieldToken.xml @@ -125,7 +125,7 @@ System.Boolean - + The to compare to the current instance. @@ -184,8 +184,8 @@ System.Boolean - - + + The to compare to . @@ -219,8 +219,8 @@ System.Boolean - - + + The to compare to . diff --git a/xml/System.Reflection.Emit/GenericTypeParameterBuilder.xml b/xml/System.Reflection.Emit/GenericTypeParameterBuilder.xml index ee42b9fdd4b..d544250f09d 100644 --- a/xml/System.Reflection.Emit/GenericTypeParameterBuilder.xml +++ b/xml/System.Reflection.Emit/GenericTypeParameterBuilder.xml @@ -65,28 +65,28 @@ Defines and creates generic type parameters for dynamically defined generic types and methods. This class cannot be inherited. - objects by using the method to add type parameters to a dynamic type, thus making it a generic type, or by using the method to add type parameters to a dynamic method. Use the objects to add constraints to the type parameters. Constraints are of three kinds: - -- The base type constraint specifies that any type assigned to the generic type parameter must derive from a particular base type. Set this constraint by using the method. - -- An interface constraint specifies that any type assigned to the generic type parameter must implement a particular interface. Set the interface constraints by using the method. - -- Special constraints specify that any type assigned to the generic type parameter must have a parameterless constructor, must be a reference type, or must be a value type. Set the special constraints for a type parameter by using the method. - - Interface constraints and special constraints cannot be retrieved using methods of the class. Once you have created the generic type that contains the type parameters, you can use its object to reflect the constraints. Use the method to get the type parameters, and for each type parameter use the method to get the base type constraint and interface constraints, and the property to get the special constraints. - - - -## Examples - The following code example creates a generic type with two type parameters, and saves them in the assembly GenericEmitExample1.dll. You can use the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler) to view the generated types. For a more detailed explanation of the steps involved in defining a dynamic generic type, see [How to: Define a Generic Type with Reflection Emit](/dotnet/framework/reflection-and-codedom/how-to-define-a-generic-type-with-reflection-emit). - + objects by using the method to add type parameters to a dynamic type, thus making it a generic type, or by using the method to add type parameters to a dynamic method. Use the objects to add constraints to the type parameters. Constraints are of three kinds: + +- The base type constraint specifies that any type assigned to the generic type parameter must derive from a particular base type. Set this constraint by using the method. + +- An interface constraint specifies that any type assigned to the generic type parameter must implement a particular interface. Set the interface constraints by using the method. + +- Special constraints specify that any type assigned to the generic type parameter must have a parameterless constructor, must be a reference type, or must be a value type. Set the special constraints for a type parameter by using the method. + + Interface constraints and special constraints cannot be retrieved using methods of the class. Once you have created the generic type that contains the type parameters, you can use its object to reflect the constraints. Use the method to get the type parameters, and for each type parameter use the method to get the base type constraint and interface constraints, and the property to get the special constraints. + + + +## Examples + The following code example creates a generic type with two type parameters, and saves them in the assembly GenericEmitExample1.dll. You can use the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler) to view the generated types. For a more detailed explanation of the steps involved in defining a dynamic generic type, see [How to: Define a Generic Type with Reflection Emit](/dotnet/framework/reflection-and-codedom/how-to-define-a-generic-type-with-reflection-emit). + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/EmitGenericType/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/GenericTypeParameterBuilder/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/EmitGenericType/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/EmitGenericType/VB/source.vb" id="Snippet1"::: + ]]> @@ -94,11 +94,11 @@ - - - - - + + + + + Constructor mscorlib @@ -205,11 +205,11 @@ Gets in all cases. A null reference ( in Visual Basic) in all cases. - @@ -290,11 +290,11 @@ Gets the base type constraint of the current generic type parameter. A object that represents the base type constraint of the generic type parameter, or if the type parameter has no base type constraint. - method. - + method. + ]]> @@ -337,11 +337,11 @@ in all cases. - object always represents a generic type parameter. The value of the property reflects that fact and does not imply anything about any generic type argument that might be assigned to the type parameter. - + object always represents a generic type parameter. The value of the property reflects that fact and does not imply anything about any generic type argument that might be assigned to the type parameter. + ]]> @@ -394,11 +394,11 @@ Gets a that represents the declaring method, if the current represents a type parameter of a generic method. A that represents the declaring method, if the current represents a type parameter of a generic method; otherwise, . - property is not `null`, then the declaring method is a generic method definition and `DeclaringMethod.IsGenericMethodDefinition` is `true`. - + property is not `null`, then the declaring method is a generic method definition and `DeclaringMethod.IsGenericMethodDefinition` is `true`. + ]]> @@ -451,11 +451,11 @@ Gets the generic type definition or generic method definition to which the generic type parameter belongs. If the type parameter belongs to a generic type, a object representing that generic type; if the type parameter belongs to a generic method, a object representing that type that declared that generic method. - @@ -559,11 +559,11 @@ Gets in all cases. A null reference ( in Visual Basic) in all cases. - @@ -863,11 +863,11 @@ Not supported for incomplete generic type parameters. Not supported for incomplete generic type parameters. - In all cases. @@ -923,11 +923,11 @@ Not supported for incomplete generic type parameters. Not supported for incomplete generic type parameters. - In all cases. @@ -975,11 +975,11 @@ Not supported for incomplete generic type parameters. Not supported for incomplete generic type parameters. - In all cases. @@ -1023,11 +1023,11 @@ Throws a in all cases. The type referred to by the current array type, pointer type, or type; or if the current type is not an array type, is not a pointer type, and is not passed by reference. - . - + . + ]]> In all cases. @@ -1081,11 +1081,11 @@ Not supported for incomplete generic type parameters. Not supported for incomplete generic type parameters. - In all cases. @@ -1144,11 +1144,11 @@ Not supported for incomplete generic type parameters. Not supported for incomplete generic type parameters. - In all cases. @@ -1200,11 +1200,11 @@ Not supported for incomplete generic type parameters. Not supported for incomplete generic type parameters. - In all cases. @@ -1258,11 +1258,11 @@ Not supported for incomplete generic type parameters. Not supported for incomplete generic type parameters. - In all cases. @@ -1314,11 +1314,11 @@ Not supported for incomplete generic type parameters. Not supported for incomplete generic type parameters. - In all cases. @@ -1361,11 +1361,11 @@ Not valid for generic type parameters. Not valid for generic type parameters. - In all cases. @@ -1439,11 +1439,11 @@ Not valid for generic type parameters. Not valid for generic type parameters. - In all cases. @@ -1538,11 +1538,11 @@ Not supported for incomplete generic type parameters. Not supported for incomplete generic type parameters. - In all cases. @@ -1601,11 +1601,11 @@ Not supported for incomplete generic type parameters. Not supported for incomplete generic type parameters. - In all cases. @@ -1654,11 +1654,11 @@ Not supported for incomplete generic type parameters. Not supported for incomplete generic type parameters. - In all cases. @@ -1718,11 +1718,11 @@ Not supported for incomplete generic type parameters. Not supported for incomplete generic type parameters. - In all cases. @@ -1778,11 +1778,11 @@ Not supported for incomplete generic type parameters. Not supported for incomplete generic type parameters. - In all cases. @@ -1915,11 +1915,11 @@ Not supported for incomplete generic type parameters. Not supported for incomplete generic type parameters. - In all cases. @@ -1973,11 +1973,11 @@ Not supported for incomplete generic type parameters. Not supported for incomplete generic type parameters. - In all cases. @@ -2029,11 +2029,11 @@ Not supported for incomplete generic type parameters. Not supported for incomplete generic type parameters. - In all cases. @@ -2085,11 +2085,11 @@ Not supported for incomplete generic type parameters. Not supported for incomplete generic type parameters. - In all cases. @@ -2210,11 +2210,11 @@ Not supported for incomplete generic type parameters. Not supported for incomplete generic type parameters. - In all cases. @@ -2339,11 +2339,11 @@ Not supported for incomplete generic type parameters. Not supported for incomplete generic type parameters. - In all cases. @@ -2433,7 +2433,7 @@ System.Boolean - + [System.Diagnostics.CodeAnalysis.NotNullWhen(true)] @@ -2447,11 +2447,11 @@ Throws a exception in all cases. Throws a exception in all cases. - In all cases. @@ -2511,11 +2511,11 @@ Throws a exception in all cases. Throws a exception in all cases. - In all cases. @@ -2712,11 +2712,11 @@ Not supported for incomplete generic type parameters. Not supported for incomplete generic type parameters. - In all cases. @@ -2827,11 +2827,11 @@ in all cases. - @@ -2874,11 +2874,11 @@ in all cases. - @@ -3037,11 +3037,11 @@ Not supported for incomplete generic type parameters. Not supported for incomplete generic type parameters. - In all cases. @@ -3235,20 +3235,20 @@ Returns the type of a one-dimensional array whose element type is the generic type parameter. A object that represents the type of a one-dimensional array whose element type is the generic type parameter. - method provides a way to generate array types for parameter lists. - - - -## Examples - The following code example creates a dynamic module, an abstract generic type named `Sample` with one type parameter, `T`, and an abstract method named `TestMethod`. `TestMethod` takes a `ref` parameter (`ByRef` in Visual Basic) of type `T`, a pointer to type `T`, and an array of `T`. This method returns a two-dimensional array of `T`. The code example saves the dynamic module to disk, so you can examine it using the MSIL Disassembler (Ildasm.exe). - + method provides a way to generate array types for parameter lists. + + + +## Examples + The following code example creates a dynamic module, an abstract generic type named `Sample` with one type parameter, `T`, and an abstract method named `TestMethod`. `TestMethod` takes a `ref` parameter (`ByRef` in Visual Basic) of type `T`, a pointer to type `T`, and an array of `T`. This method returns a two-dimensional array of `T`. The code example saves the dynamic module to disk, so you can examine it using the MSIL Disassembler (Ildasm.exe). + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/MakeXxxGenericTypeParameterBuilder/cpp/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/GenericTypeParameterBuilder/MakeArrayType/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/MakeXxxGenericTypeParameterBuilder/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/MakeXxxGenericTypeParameterBuilder/VB/source.vb" id="Snippet1"::: + ]]> @@ -3302,20 +3302,20 @@ Returns the type of an array whose element type is the generic type parameter, with the specified number of dimensions. A object that represents the type of an array whose element type is the generic type parameter, with the specified number of dimensions. - method provides a way to generate array types for parameter lists. - - - -## Examples - The following code example creates a dynamic module, an abstract generic type named `Sample` with one type parameter, `T`, and an abstract method named `TestMethod`. `TestMethod` takes a `ref` parameter (`ByRef` in Visual Basic) of type `T`, a pointer to type `T`, and an array of `T`. This method returns a two-dimensional array of `T`. The code example saves the dynamic module to disk, so you can examine it using the MSIL Disassembler (Ildasm.exe). - + method provides a way to generate array types for parameter lists. + + + +## Examples + The following code example creates a dynamic module, an abstract generic type named `Sample` with one type parameter, `T`, and an abstract method named `TestMethod`. `TestMethod` takes a `ref` parameter (`ByRef` in Visual Basic) of type `T`, a pointer to type `T`, and an array of `T`. This method returns a two-dimensional array of `T`. The code example saves the dynamic module to disk, so you can examine it using the MSIL Disassembler (Ildasm.exe). + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/MakeXxxGenericTypeParameterBuilder/cpp/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/GenericTypeParameterBuilder/MakeArrayType/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/MakeXxxGenericTypeParameterBuilder/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/MakeXxxGenericTypeParameterBuilder/VB/source.vb" id="Snippet1"::: + ]]> @@ -3362,20 +3362,20 @@ Returns a object that represents the current generic type parameter when passed as a reference parameter. A object that represents the current generic type parameter when passed as a reference parameter. - method provides a way to generate `ref` types (`ByRef` in Visual Basic) for parameter lists. - - - -## Examples - The following code example creates a dynamic module, an abstract generic type named `Sample` with one type parameter, `T`, and an abstract method named `TestMethod`. `TestMethod` takes a `ref` parameter (`ByRef` in Visual Basic) of type `T`, a pointer to type `T`, and an array of `T`. This method returns a two-dimensional array of `T`. The code example saves the dynamic module to disk, so you can examine it using the MSIL Disassembler (Ildasm.exe). - + method provides a way to generate `ref` types (`ByRef` in Visual Basic) for parameter lists. + + + +## Examples + The following code example creates a dynamic module, an abstract generic type named `Sample` with one type parameter, `T`, and an abstract method named `TestMethod`. `TestMethod` takes a `ref` parameter (`ByRef` in Visual Basic) of type `T`, a pointer to type `T`, and an array of `T`. This method returns a two-dimensional array of `T`. The code example saves the dynamic module to disk, so you can examine it using the MSIL Disassembler (Ildasm.exe). + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/MakeXxxGenericTypeParameterBuilder/cpp/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/GenericTypeParameterBuilder/MakeArrayType/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/MakeXxxGenericTypeParameterBuilder/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/MakeXxxGenericTypeParameterBuilder/VB/source.vb" id="Snippet1"::: + ]]> @@ -3481,20 +3481,20 @@ Returns a object that represents a pointer to the current generic type parameter. A object that represents a pointer to the current generic type parameter. - method provides a way to generate pointer types for parameter lists. - - - -## Examples - The following code example creates a dynamic module, an abstract generic type named `Sample` with one type parameter, `T`, and an abstract method named `TestMethod`. `TestMethod` takes a `ref` parameter (`ByRef` in Visual Basic) of type `T`, a pointer to type `T`, and an array of `T`. This method returns a two-dimensional array of `T`. The code example saves the dynamic module to disk, so you can examine it using the MSIL Disassembler (Ildasm.exe). - + method provides a way to generate pointer types for parameter lists. + + + +## Examples + The following code example creates a dynamic module, an abstract generic type named `Sample` with one type parameter, `T`, and an abstract method named `TestMethod`. `TestMethod` takes a `ref` parameter (`ByRef` in Visual Basic) of type `T`, a pointer to type `T`, and an array of `T`. This method returns a two-dimensional array of `T`. The code example saves the dynamic module to disk, so you can examine it using the MSIL Disassembler (Ildasm.exe). + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/MakeXxxGenericTypeParameterBuilder/cpp/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/GenericTypeParameterBuilder/MakeArrayType/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/MakeXxxGenericTypeParameterBuilder/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/MakeXxxGenericTypeParameterBuilder/VB/source.vb" id="Snippet1"::: + ]]> @@ -3529,14 +3529,14 @@ Gets a token that identifies the current dynamic module in metadata. An integer token that identifies the current module in metadata. - [!NOTE] > Information about metadata tokens can be found in the Common Language Infrastructure (CLI) documentation, especially "Partition II: Metadata Definition and Semantics". For more information, see [ECMA 335 Common Language Infrastructure (CLI)](https://www.ecma-international.org/publications-and-standards/standards/ecma-335/). - + ]]> @@ -3776,22 +3776,22 @@ The that must be inherited by any type that is to be substituted for the type parameter. Sets the base type that a type must inherit in order to be substituted for the type parameter. - property. - - Once you have created the generic type that contains the type parameter, you can use its object to reflect the type parameter and their constraints. To get the type parameters of a completed generic type, use the method. For each type parameter, get the base type constraint and interface constraints by using the method, and get the special constraints by using the property. - - - -## Examples - The following code example creates a generic type with two type parameters, the second of which has a base type constraint, and saves them in the assembly GenericEmitExample1.dll. You can use the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler) to view the generated types. For a more detailed explanation of the steps involved in defining a dynamic generic type, see [How to: Define a Generic Type with Reflection Emit](/dotnet/framework/reflection-and-codedom/how-to-define-a-generic-type-with-reflection-emit). - + property. + + Once you have created the generic type that contains the type parameter, you can use its object to reflect the type parameter and their constraints. To get the type parameters of a completed generic type, use the method. For each type parameter, get the base type constraint and interface constraints by using the method, and get the special constraints by using the property. + + + +## Examples + The following code example creates a generic type with two type parameters, the second of which has a base type constraint, and saves them in the assembly GenericEmitExample1.dll. You can use the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler) to view the generated types. For a more detailed explanation of the steps involved in defining a dynamic generic type, see [How to: Define a Generic Type with Reflection Emit](/dotnet/framework/reflection-and-codedom/how-to-define-a-generic-type-with-reflection-emit). + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/EmitGenericType/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/GenericTypeParameterBuilder/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/EmitGenericType/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/EmitGenericType/VB/source.vb" id="Snippet1"::: + ]]> How to: Define a Generic Type with Reflection Emit @@ -3937,19 +3937,19 @@ A byte blob representing the attribute. Sets a custom attribute using a specified custom attribute blob. - - is . - - -or- - + is . + + -or- + is a null reference. @@ -4039,24 +4039,24 @@ For information on how to format `binaryAttribute`, see the metadata specificati A bitwise combination of values that represent the variance characteristics and special constraints of the generic type parameter. Sets the variance characteristics and special constraints of the generic parameter, such as the parameterless constructor constraint. - class. Once you have created the generic type that contains the type parameter, you can use its object to reflect the type parameters and their constraints. To get the type parameters of a completed generic type, use the method. To get the special constraints for each type parameter, use the property. - - The enumeration values that refer to the variance characteristics of a type parameter are relevant only in languages that support covariance and contravariance, such as Microsoft intermediate language (MSIL). Visual Basic and C# currently do not support covariance and contravariance. - - - -## Examples - The following code example creates a generic type with two type parameters, the first of which is constrained to have a parameterless constructor and to be a reference type, and saves them in the assembly GenericEmitExample1.dll. You can use the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler) to view the generated types. For a more detailed explanation of the steps involved in defining a dynamic generic type, see [How to: Define a Generic Type with Reflection Emit](/dotnet/framework/reflection-and-codedom/how-to-define-a-generic-type-with-reflection-emit). - + class. Once you have created the generic type that contains the type parameter, you can use its object to reflect the type parameters and their constraints. To get the type parameters of a completed generic type, use the method. To get the special constraints for each type parameter, use the property. + + The enumeration values that refer to the variance characteristics of a type parameter are relevant only in languages that support covariance and contravariance, such as Microsoft intermediate language (MSIL). Visual Basic and C# currently do not support covariance and contravariance. + + + +## Examples + The following code example creates a generic type with two type parameters, the first of which is constrained to have a parameterless constructor and to be a reference type, and saves them in the assembly GenericEmitExample1.dll. You can use the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler) to view the generated types. For a more detailed explanation of the steps involved in defining a dynamic generic type, see [How to: Define a Generic Type with Reflection Emit](/dotnet/framework/reflection-and-codedom/how-to-define-a-generic-type-with-reflection-emit). + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/EmitGenericType/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/GenericTypeParameterBuilder/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/EmitGenericType/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/EmitGenericType/VB/source.vb" id="Snippet1"::: + ]]> How to: Define a Generic Type with Reflection Emit @@ -4155,20 +4155,20 @@ For information on how to format `binaryAttribute`, see the metadata specificati An array of objects that represent the interfaces a type must implement in order to be substituted for the type parameter. Sets the interfaces a type must implement in order to be substituted for the type parameter. - class. Once you have created the generic type that contains the type parameter, you can use its object to reflect the type parameters and their constraints. To get the type parameters of a completed generic type, use the method. For each type parameter, get the base type constraint and interface constraints by using the method. - - - -## Examples - The following code example creates a generic type with two type parameters, the second of which has two interface constraints, and saves them in the assembly GenericEmitExample1.dll. You can use the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler) to view the generated types. For a more detailed explanation of the steps involved in defining a dynamic generic type, see [How to: Define a Generic Type with Reflection Emit](/dotnet/framework/reflection-and-codedom/how-to-define-a-generic-type-with-reflection-emit). - + class. Once you have created the generic type that contains the type parameter, you can use its object to reflect the type parameters and their constraints. To get the type parameters of a completed generic type, use the method. For each type parameter, get the base type constraint and interface constraints by using the method. + + + +## Examples + The following code example creates a generic type with two type parameters, the second of which has two interface constraints, and saves them in the assembly GenericEmitExample1.dll. You can use the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler) to view the generated types. For a more detailed explanation of the steps involved in defining a dynamic generic type, see [How to: Define a Generic Type with Reflection Emit](/dotnet/framework/reflection-and-codedom/how-to-define-a-generic-type-with-reflection-emit). + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/EmitGenericType/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/GenericTypeParameterBuilder/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/EmitGenericType/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/EmitGenericType/VB/source.vb" id="Snippet1"::: + ]]> How to: Define a Generic Type with Reflection Emit @@ -4292,11 +4292,11 @@ For information on how to format `binaryAttribute`, see the metadata specificati Not supported for incomplete generic type parameters. Not supported for incomplete generic type parameters. - In all cases. diff --git a/xml/System.Reflection.Emit/ILGenerator.xml b/xml/System.Reflection.Emit/ILGenerator.xml index a07d6b06943..cb845ed0659 100644 --- a/xml/System.Reflection.Emit/ILGenerator.xml +++ b/xml/System.Reflection.Emit/ILGenerator.xml @@ -2553,11 +2553,11 @@ The following code example emits two methods, a `varargs` method and a method th System.Void - - - - - + + + + + The document for which the sequence point is being defined. @@ -2610,11 +2610,11 @@ The following code example emits two methods, a `varargs` method and a method th System.Void - - - - - + + + + + Reserved for future use. Must be IID_NULL. @@ -2661,9 +2661,9 @@ The following code example emits two methods, a `varargs` method and a method th System.Void - - - + + + The type information to return. @@ -2708,7 +2708,7 @@ The following code example emits two methods, a `varargs` method and a method th System.Void - + Points to a location that receives the number of type information interfaces provided by the object. @@ -2751,14 +2751,14 @@ The following code example emits two methods, a `varargs` method and a method th System.Void - - - - - - - - + + + + + + + + Identifies the member. diff --git a/xml/System.Reflection.Emit/LocalBuilder.xml b/xml/System.Reflection.Emit/LocalBuilder.xml index 54d1328ec6b..a7dffb58739 100644 --- a/xml/System.Reflection.Emit/LocalBuilder.xml +++ b/xml/System.Reflection.Emit/LocalBuilder.xml @@ -83,20 +83,20 @@ Represents a local variable within a method or constructor. - method. - - - -## Examples - The following example creates a `static` method (`Shared` in Visual Basic) named `Function1` that returns a string and has a parameter of type . In the body of the method, the code example creates objects representing two local variables, and sets symbol information for the local variables. The method does not do anything significant, but the method body demonstrates storing a parameter to a local variable, storing a literal string to a local variable, and loading a local variable. - + method. + + + +## Examples + The following example creates a `static` method (`Shared` in Visual Basic) named `Function1` that returns a string and has a parameter of type . In the body of the method, the code example creates objects representing two local variables, and sets symbol information for the local variables. The method does not do anything significant, but the method body demonstrates storing a parameter to a local variable, storing a literal string to a local variable, and loading a local variable. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/LocalBuilder_Sample_SetLocalSymInfo/CPP/localbuilder_sample_4.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/ILGenerator/DeclareLocal/localbuilder_sample_4.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/LocalBuilder_Sample_SetLocalSymInfo/VB/localbuilder_sample_4.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/LocalBuilder_Sample_SetLocalSymInfo/VB/localbuilder_sample_4.vb" id="Snippet1"::: + ]]> @@ -162,11 +162,11 @@ if the object referred to by the local variable is pinned in memory; otherwise, . - @@ -208,11 +208,11 @@ Gets the zero-based index of the local variable within the method body. An integer value that represents the order of declaration of the local variable within the method body. - @@ -258,15 +258,15 @@ Gets the type of the local variable. The of the local variable. - class. - + class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/LocalBuilder_Sample_SetLocalSymInfo/CPP/localbuilder_sample_4.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/ILGenerator/DeclareLocal/localbuilder_sample_4.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/LocalBuilder_Sample_SetLocalSymInfo/VB/localbuilder_sample_4.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/LocalBuilder_Sample_SetLocalSymInfo/VB/localbuilder_sample_4.vb" id="Snippet2"::: + ]]> @@ -305,32 +305,32 @@ System.Void - + The name of the local variable. Sets the name of this local variable. - method is supported for methods defined in dynamic types. It is not supported for dynamic methods defined using the class. - - - -## Examples - The following code sample illustrates the use of the method. This code is part of a larger example for the class. - + method is supported for methods defined in dynamic types. It is not supported for dynamic methods defined using the class. + + + +## Examples + The following code sample illustrates the use of the method. This code is part of a larger example for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/LocalBuilder_Sample_SetLocalSymInfo/CPP/localbuilder_sample_4.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/ILGenerator/DeclareLocal/localbuilder_sample_4.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/LocalBuilder_Sample_SetLocalSymInfo/VB/localbuilder_sample_4.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/LocalBuilder_Sample_SetLocalSymInfo/VB/localbuilder_sample_4.vb" id="Snippet2"::: + ]]> - The containing type has been created with . - - -or- - + The containing type has been created with . + + -or- + There is no symbolic writer defined for the containing module. This local is defined in a dynamic method, rather than in a method of a dynamic type. @@ -365,9 +365,9 @@ System.Void - - - + + + The name of the local variable. @@ -375,26 +375,26 @@ The ending offset of the lexical scope of the local variable. Sets the name and lexical scope of this local variable. - method is supported for methods defined in dynamic types. It is not supported for dynamic methods defined using the class. - - - -## Examples - The following code sample illustrates the use of the method. This code is part of a larger example for the class. - + method is supported for methods defined in dynamic types. It is not supported for dynamic methods defined using the class. + + + +## Examples + The following code sample illustrates the use of the method. This code is part of a larger example for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/LocalBuilder_Sample_SetLocalSymInfo/CPP/localbuilder_sample_4.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/ILGenerator/DeclareLocal/localbuilder_sample_4.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/LocalBuilder_Sample_SetLocalSymInfo/VB/localbuilder_sample_4.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/LocalBuilder_Sample_SetLocalSymInfo/VB/localbuilder_sample_4.vb" id="Snippet2"::: + ]]> - The containing type has been created with . - - -or- - + The containing type has been created with . + + -or- + There is no symbolic writer defined for the containing module. This local is defined in a dynamic method, rather than in a method of a dynamic type. @@ -426,11 +426,11 @@ System.Void - - - - - + + + + + Reserved for future use. Must be IID_NULL. @@ -440,11 +440,11 @@ Caller-allocated array which receives the IDs corresponding to the names. Maps a set of names to a corresponding set of dispatch identifiers. - Late-bound access using the COM IDispatch interface is not supported. @@ -477,9 +477,9 @@ System.Void - - - + + + The type information to return. @@ -487,11 +487,11 @@ Receives a pointer to the requested type information object. Retrieves the type information for an object, which can then be used to get the type information for an interface. - Late-bound access using the COM IDispatch interface is not supported. @@ -524,17 +524,17 @@ System.Void - + Points to a location that receives the number of type information interfaces provided by the object. Retrieves the number of type information interfaces that an object provides (either 0 or 1). - Late-bound access using the COM IDispatch interface is not supported. @@ -567,14 +567,14 @@ System.Void - - - - - - - - + + + + + + + + Identifies the member. @@ -587,11 +587,11 @@ The index of the first argument that has an error. Provides access to properties and methods exposed by an object. - Late-bound access using the COM IDispatch interface is not supported. diff --git a/xml/System.Reflection.Emit/MethodBuilder.xml b/xml/System.Reflection.Emit/MethodBuilder.xml index f16d7296322..809c6c3398e 100644 --- a/xml/System.Reflection.Emit/MethodBuilder.xml +++ b/xml/System.Reflection.Emit/MethodBuilder.xml @@ -89,11 +89,11 @@ The following example uses the class - - - - - + + + + + Constructor mscorlib @@ -143,8 +143,8 @@ The following example uses the class System.Void - - + + The security action to be taken (Demand, Assert, and so on). @@ -340,8 +340,8 @@ The following example uses the class System.Void - - + + An array containing valid MSIL instructions. If this parameter is , the method's body is cleared. @@ -2648,7 +2648,7 @@ For information on how to format `binaryAttribute`, see the metadata specificati System.Void - + Marshaling information for the return type of this method. @@ -2695,11 +2695,11 @@ For information on how to format `binaryAttribute`, see the metadata specificati System.Void - - - - - + + + + + An array that contains valid MSIL instructions. @@ -3120,8 +3120,8 @@ For information on how to format `binaryAttribute`, see the metadata specificati System.Void - - + + The name of the symbolic custom attribute. @@ -3218,11 +3218,11 @@ For information on how to format `binaryAttribute`, see the metadata specificati System.Void - - - - - + + + + + Reserved for future use. Must be IID_NULL. @@ -3269,9 +3269,9 @@ For information on how to format `binaryAttribute`, see the metadata specificati System.Void - - - + + + The type information to return. @@ -3316,7 +3316,7 @@ For information on how to format `binaryAttribute`, see the metadata specificati System.Void - + Points to a location that receives the number of type information interfaces provided by the object. @@ -3359,14 +3359,14 @@ For information on how to format `binaryAttribute`, see the metadata specificati System.Void - - - - - - - - + + + + + + + + Identifies the member. diff --git a/xml/System.Reflection.Emit/MethodToken.xml b/xml/System.Reflection.Emit/MethodToken.xml index 0187111e1f0..a26d2936927 100644 --- a/xml/System.Reflection.Emit/MethodToken.xml +++ b/xml/System.Reflection.Emit/MethodToken.xml @@ -125,7 +125,7 @@ System.Boolean - + The to compare to the current instance. @@ -184,8 +184,8 @@ System.Boolean - - + + The to compare to . @@ -219,8 +219,8 @@ System.Boolean - - + + The to compare to . diff --git a/xml/System.Reflection.Emit/ModuleBuilder.xml b/xml/System.Reflection.Emit/ModuleBuilder.xml index 93eee62b738..228d8a6969c 100644 --- a/xml/System.Reflection.Emit/ModuleBuilder.xml +++ b/xml/System.Reflection.Emit/ModuleBuilder.xml @@ -77,30 +77,30 @@ Defines and represents a module in a dynamic assembly. - , use the method. - - - -## Examples - The following code sample demonstrates the use of `ModuleBuilder` to create a dynamic module. Note that the ModuleBuilder is created by calling in , rather than through a constructor. - + , use the method. + + + +## Examples + The following code sample demonstrates the use of `ModuleBuilder` to create a dynamic module. Note that the ModuleBuilder is created by calling in , rather than through a constructor. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/ModuleBuilder_Class/CPP/modulebuilder.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/ModuleBuilder/Overview/modulebuilder.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ModuleBuilder_Class/VB/modulebuilder.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ModuleBuilder_Class/VB/modulebuilder.vb" id="Snippet1"::: + ]]> - - - - - + + + + + Constructor mscorlib @@ -156,11 +156,11 @@ Gets the dynamic assembly that defined this instance of . The dynamic assembly that defined the current dynamic module. - object that is returned is the that defined this instance of . - + object that is returned is the that defined this instance of . + ]]> @@ -203,23 +203,23 @@ Completes the global function definitions and global data definitions for this dynamic module. - [!NOTE] -> Starting with the .NET Framework 2.0 Service Pack 1, this member no longer requires with the flag. (See [Security Issues in Reflection Emit](/dotnet/framework/reflection-and-codedom/security-issues-in-reflection-emit).) To use this functionality, your application should target the .NET Framework 3.5 or later. - - - -## Examples - The following sample illustrates the use of `CreateGlobalFunctions` to create a static global method from a implemented with . - +> Starting with the .NET Framework 2.0 Service Pack 1, this member no longer requires with the flag. (See [Security Issues in Reflection Emit](/dotnet/framework/reflection-and-codedom/security-issues-in-reflection-emit).) To use this functionality, your application should target the .NET Framework 3.5 or later. + + + +## Examples + The following sample illustrates the use of `CreateGlobalFunctions` to create a static global method from a implemented with . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/ModuleBuilder_CreateGlobalFunctions/CPP/modulebuilder_createglobalfunctions.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/ModuleBuilder/CreateGlobalFunctions/modulebuilder_createglobalfunctions.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ModuleBuilder_CreateGlobalFunctions/VB/modulebuilder_createglobalfunctions.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ModuleBuilder_CreateGlobalFunctions/VB/modulebuilder_createglobalfunctions.vb" id="Snippet2"::: + ]]> This method was called previously. @@ -283,10 +283,10 @@ System.Diagnostics.SymbolStore.ISymbolDocumentWriter - - - - + + + + The URL for the document. @@ -296,22 +296,22 @@ Defines a document for source. The defined document. - [!IMPORTANT] -> Earlier versions of the .NET Framework throw instead of when `url` is `null`. - - - -## Examples - The following code sample illustrates the use of `DefineDocument` to attach an external symbol document (in this case, a raw IL file) to a dynamic module. - +> Earlier versions of the .NET Framework throw instead of when `url` is `null`. + + + +## Examples + The following code sample illustrates the use of `DefineDocument` to attach an external symbol document (in this case, a raw IL file) to a dynamic module. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/ModuleBuilder_DefineDocument/CPP/modulebuilder_definedocument.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics.SymbolStore/ISymbolDocumentWriter/Overview/modulebuilder_definedocument.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ModuleBuilder_DefineDocument/VB/modulebuilder_definedocument.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ModuleBuilder_DefineDocument/VB/modulebuilder_definedocument.vb" id="Snippet1"::: + ]]> @@ -371,41 +371,41 @@ Defines an enumeration type that is a value type with a single non-static field called of the specified type. The defined enumeration. - . The `value__` field has and attributes set. - - For more information about the built-in integer types that can be specified as the underlying types of enumerations, see [Class Library Overview](/dotnet/standard/class-library-overview). - + . The `value__` field has and attributes set. + + For more information about the built-in integer types that can be specified as the underlying types of enumerations, see [Class Library Overview](/dotnet/standard/class-library-overview). + > [!NOTE] -> In the .NET Framework versions 1.0 and 1.1, it is necessary to define enumerations using because emits enumerations whose elements are of type instead of the enumeration type. In the .NET Framework version 2.0, emits enumerations whose elements have the correct type. - +> In the .NET Framework versions 1.0 and 1.1, it is necessary to define enumerations using because emits enumerations whose elements are of type instead of the enumeration type. In the .NET Framework version 2.0, emits enumerations whose elements have the correct type. + > [!NOTE] -> Starting with the .NET Framework 2.0 Service Pack 1, this member no longer requires with the flag. (See [Security Issues in Reflection Emit](/dotnet/framework/reflection-and-codedom/security-issues-in-reflection-emit).) To use this functionality, your application should target the .NET Framework 3.5 or later. - - - -## Examples - The following example illustrates the use of `DefineEnum` to implement an enumeration class in a dynamic module. The example defines an enumeration named `Elevation` that has an underlying type of , and creates two elements: `Low`, with a value of 0, and `High`, with a value of 1. After the type has been created, the assembly is saved with the name `TempAssembly.dll`. You can use the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler) to examine the contents of this assembly. - +> Starting with the .NET Framework 2.0 Service Pack 1, this member no longer requires with the flag. (See [Security Issues in Reflection Emit](/dotnet/framework/reflection-and-codedom/security-issues-in-reflection-emit).) To use this functionality, your application should target the .NET Framework 3.5 or later. + + + +## Examples + The following example illustrates the use of `DefineEnum` to implement an enumeration class in a dynamic module. The example defines an enumeration named `Elevation` that has an underlying type of , and creates two elements: `Low`, with a value of 0, and `High`, with a value of 1. After the type has been created, the assembly is saved with the name `TempAssembly.dll`. You can use the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler) to examine the contents of this assembly. + > [!NOTE] -> Prior to the .NET Framework version 2.0, this code example does not produce a correct enumeration. - +> Prior to the .NET Framework version 2.0, this code example does not produce a correct enumeration. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/ModuleBuilder_DefineEnum/CPP/modulebuilder_defineenum.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/EnumBuilder/Overview/modulebuilder_defineenum.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ModuleBuilder_DefineEnum/VB/modulebuilder_defineenum.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ModuleBuilder_DefineEnum/VB/modulebuilder_defineenum.vb" id="Snippet1"::: + ]]> - Attributes other than visibility attributes are provided. - - -or- - - An enumeration with the given name exists in the parent assembly of this module. - - -or- - + Attributes other than visibility attributes are provided. + + -or- + + An enumeration with the given name exists in the parent assembly of this module. + + -or- + The visibility attributes do not match the scope of the enumeration. For example, is specified for , but the enumeration is not a nested type. is . @@ -520,33 +520,33 @@ Defines a global method with the specified name, attributes, return type, and parameter types. The defined global method. - . - + . + > [!NOTE] -> Starting with the .NET Framework 2.0 Service Pack 1, this member no longer requires with the flag. (See [Security Issues in Reflection Emit](/dotnet/framework/reflection-and-codedom/security-issues-in-reflection-emit).) To use this functionality, your application should target the .NET Framework 3.5 or later. - - - -## Examples - The following example illustrates the use of `DefineGlobalMethod` to create a type-independent method tied to the current . After building the global method, must be called in order to complete it. - +> Starting with the .NET Framework 2.0 Service Pack 1, this member no longer requires with the flag. (See [Security Issues in Reflection Emit](/dotnet/framework/reflection-and-codedom/security-issues-in-reflection-emit).) To use this functionality, your application should target the .NET Framework 3.5 or later. + + + +## Examples + The following example illustrates the use of `DefineGlobalMethod` to create a type-independent method tied to the current . After building the global method, must be called in order to complete it. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/ModuleBuilder_CreateGlobalFunctions/CPP/modulebuilder_createglobalfunctions.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/ModuleBuilder/CreateGlobalFunctions/modulebuilder_createglobalfunctions.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ModuleBuilder_CreateGlobalFunctions/VB/modulebuilder_createglobalfunctions.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ModuleBuilder_CreateGlobalFunctions/VB/modulebuilder_createglobalfunctions.vb" id="Snippet1"::: + ]]> - The method is not static. That is, does not include . - - -or- - - The length of is zero - - -or- - + The method is not static. That is, does not include . + + -or- + + The length of is zero + + -or- + An element in the array is . is . @@ -619,29 +619,29 @@ Defines a global method with the specified name, attributes, calling convention, return type, and parameter types. The defined global method. - . - + . + > [!NOTE] -> Starting with the .NET Framework 2.0 Service Pack 1, this member no longer requires with the flag. (See [Security Issues in Reflection Emit](/dotnet/framework/reflection-and-codedom/security-issues-in-reflection-emit).) To use this functionality, your application should target the .NET Framework 3.5 or later. - - - -## Examples - The following code sample illustrates the use of `DefineGlobalMethod` to create a type-independent method tied to the current . After building the global method, must be called in order to complete it. - +> Starting with the .NET Framework 2.0 Service Pack 1, this member no longer requires with the flag. (See [Security Issues in Reflection Emit](/dotnet/framework/reflection-and-codedom/security-issues-in-reflection-emit).) To use this functionality, your application should target the .NET Framework 3.5 or later. + + + +## Examples + The following code sample illustrates the use of `DefineGlobalMethod` to create a type-independent method tied to the current . After building the global method, must be called in order to complete it. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/ModuleBuilder_CreateGlobalFunctions/CPP/modulebuilder_createglobalfunctions.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/ModuleBuilder/CreateGlobalFunctions/modulebuilder_createglobalfunctions.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ModuleBuilder_CreateGlobalFunctions/VB/modulebuilder_createglobalfunctions.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ModuleBuilder_CreateGlobalFunctions/VB/modulebuilder_createglobalfunctions.vb" id="Snippet1"::: + ]]> - The method is not static. That is, does not include . - - -or- - + The method is not static. That is, does not include . + + -or- + An element in the array is . is . @@ -749,22 +749,22 @@ Defines a global method with the specified name, attributes, calling convention, return type, custom modifiers for the return type, parameter types, and custom modifiers for the parameter types. The defined global method. - . - + . + > [!NOTE] -> Starting with the .NET Framework 2.0 Service Pack 1, this member no longer requires with the flag. (See [Security Issues in Reflection Emit](/dotnet/framework/reflection-and-codedom/security-issues-in-reflection-emit).) To use this functionality, your application should target the .NET Framework 3.5 or later. - +> Starting with the .NET Framework 2.0 Service Pack 1, this member no longer requires with the flag. (See [Security Issues in Reflection Emit](/dotnet/framework/reflection-and-codedom/security-issues-in-reflection-emit).) To use this functionality, your application should target the .NET Framework 3.5 or later. + ]]> - The method is not static. That is, does not include . - - -or- - + The method is not static. That is, does not include . + + -or- + An element in the array is . is . @@ -913,31 +913,31 @@ Defines an initialized data field in the .sdata section of the portable executable (PE) file. A field to reference the data. - is automatically included in `attributes`. - - The data defined by this method is not created until the method is called. - + is automatically included in `attributes`. + + The data defined by this method is not created until the method is called. + > [!NOTE] -> Starting with the .NET Framework 2.0 Service Pack 1, this member no longer requires with the flag. (See [Security Issues in Reflection Emit](/dotnet/framework/reflection-and-codedom/security-issues-in-reflection-emit).) To use this functionality, your application should target the .NET Framework 3.5 or later. - - - -## Examples - The following example uses the method to define an initialized data field in the `.sdata` section of the portable executable (PE) file. - +> Starting with the .NET Framework 2.0 Service Pack 1, this member no longer requires with the flag. (See [Security Issues in Reflection Emit](/dotnet/framework/reflection-and-codedom/security-issues-in-reflection-emit).) To use this functionality, your application should target the .NET Framework 3.5 or later. + + + +## Examples + The following example uses the method to define an initialized data field in the `.sdata` section of the portable executable (PE) file. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/ModuleBuilder_DefineInitializedData/CPP/modulebuilder_defineinitializeddata.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/ModuleBuilder/DefineInitializedData/modulebuilder_defineinitializeddata.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ModuleBuilder_DefineInitializedData/VB/modulebuilder_defineinitializeddata.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ModuleBuilder_DefineInitializedData/VB/modulebuilder_defineinitializeddata.vb" id="Snippet1"::: + ]]> - The length of is zero. - - -or- - + The length of is zero. + + -or- + The size of is less than or equal to zero or greater than or equal to 0x3f0000. or is . @@ -1004,9 +1004,9 @@ System.Void - - - + + + The case-sensitive name for the resource. @@ -1014,43 +1014,43 @@ An enumeration value that specifies whether the resource is public or private. Defines a binary large object (BLOB) that represents a manifest resource to be embedded in the dynamic assembly. - method to get a resource writer, and use the method to add the resource. - -- To link a managed resource into a dynamic assembly, use the method to get a resource writer, and use the method to add the linked resource. - -- To link a manifest resource BLOB into a dynamic assembly, use the method to add the linked resource. - - In addition, a single Win32 resource can be attached to an assembly by using the method or the method. This resource does not appear in the assembly manifest. - - - -## Examples - The following example generates and saves a dynamic assembly named `EmittedManifestResourceAssembly.exe`, which contains an embedded unmanaged resource. The example creates the assembly, which consists of one module, and opens a memory stream to contain the unmanaged resource. The code then calls the method to define the resource. - + method to get a resource writer, and use the method to add the resource. + +- To link a managed resource into a dynamic assembly, use the method to get a resource writer, and use the method to add the linked resource. + +- To link a manifest resource BLOB into a dynamic assembly, use the method to add the linked resource. + + In addition, a single Win32 resource can be attached to an assembly by using the method or the method. This resource does not appear in the assembly manifest. + + + +## Examples + The following example generates and saves a dynamic assembly named `EmittedManifestResourceAssembly.exe`, which contains an embedded unmanaged resource. The example creates the assembly, which consists of one module, and opens a memory stream to contain the unmanaged resource. The code then calls the method to define the resource. + > [!NOTE] -> You can use any kind of stream for your resource; for example, you can read the unmanaged binary data from a file. - - The example defines a type in the dynamic module with a `Main` method, and generates MSIL for the method body. After the body for the `Main` method has been generated and the type has been created, the code example writes five bytes to the stream associated with the manifest resource. When the assembly is saved, the resource is appended to it. - - After running the example, you can run the emitted assembly. The code in the emitted assembly's `Main` method reads the embedded manifest resource and prints the byte values to the console. You can use the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler) to view the information in the assembly manifest. - +> You can use any kind of stream for your resource; for example, you can read the unmanaged binary data from a file. + + The example defines a type in the dynamic module with a `Main` method, and generates MSIL for the method body. After the body for the `Main` method has been generated and the type has been created, the code example writes five bytes to the stream associated with the manifest resource. When the assembly is saved, the resource is appended to it. + + After running the example, you can run the emitted assembly. The code in the emitted assembly's `Main` method reads the embedded manifest resource and prints the byte values to the console. You can use the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler) to view the information in the assembly manifest. + :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/ModuleBuilder/DefineManifestResource/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/DefineManifestResource/vb/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/DefineManifestResource/vb/source.vb" id="Snippet1"::: + ]]> - is . - - -or- - + is . + + -or- + is . is a zero-length string. @@ -1152,36 +1152,36 @@ Defines a method with the specified name, the name of the DLL in which the method is defined, the attributes of the method, the calling convention of the method, the return type of the method, the types of the parameters of the method, and the flags. The defined method. - [!NOTE] -> Starting with the .NET Framework 2.0 Service Pack 1, this member no longer requires with the flag. (See [Security Issues in Reflection Emit](/dotnet/framework/reflection-and-codedom/security-issues-in-reflection-emit).) To use this functionality, your application should target the .NET Framework 3.5 or later. - - - -## Examples - The following example illustrates the use of the `DefinePInvokeMethod` method to create a for an external unmanaged method, `MessageBoxA`, in the Windows API. The example displays a message box with **Retry** and **Cancel** buttons, and displays the return value from the message box. - +> Starting with the .NET Framework 2.0 Service Pack 1, this member no longer requires with the flag. (See [Security Issues in Reflection Emit](/dotnet/framework/reflection-and-codedom/security-issues-in-reflection-emit).) To use this functionality, your application should target the .NET Framework 3.5 or later. + + + +## Examples + The following example illustrates the use of the `DefinePInvokeMethod` method to create a for an external unmanaged method, `MessageBoxA`, in the Windows API. The example displays a message box with **Retry** and **Cancel** buttons, and displays the return value from the message box. + > [!IMPORTANT] -> To get a non-zero return value, you must add to the method implementation flags after you create the , by using the and methods. - +> To get a non-zero return value, you must add to the method implementation flags after you create the , by using the and methods. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/ModuleBuilder_DefinePInvokeMethod1/CPP/modulebuilder_definepinvokemethod1.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/ModuleBuilder/DefinePInvokeMethod/modulebuilder_definepinvokemethod1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ModuleBuilder_DefinePInvokeMethod1/VB/modulebuilder_definepinvokemethod1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ModuleBuilder_DefinePInvokeMethod1/VB/modulebuilder_definepinvokemethod1.vb" id="Snippet1"::: + ]]> - The method is not static or if the containing type is an interface. - - -or- - - The method is abstract. - - -or- - + The method is not static or if the containing type is an interface. + + -or- + + The method is abstract. + + -or- + The method was previously defined. or is . @@ -1269,28 +1269,28 @@ Defines a method with the specified name, the name of the DLL in which the method is defined, the attributes of the method, the calling convention of the method, the return type of the method, the types of the parameters of the method, and the flags. The defined method. - ) cannot be specified as arguments to this method. Such attributes should be set by emitting a custom attribute for the method. For example, the DLL import attribute `PreserveSig` is set by emitting a custom attribute. - + ) cannot be specified as arguments to this method. Such attributes should be set by emitting a custom attribute for the method. For example, the DLL import attribute `PreserveSig` is set by emitting a custom attribute. + > [!NOTE] -> Starting with the .NET Framework 2.0 Service Pack 1, this member no longer requires with the flag. (See [Security Issues in Reflection Emit](/dotnet/framework/reflection-and-codedom/security-issues-in-reflection-emit).) To use this functionality, your application should target the .NET Framework 3.5 or later. - - - -## Examples - The following example illustrates the use of the `DefinePInvokeMethod` method to create a for an external unmanaged method, `MessageBoxA`, in the Windows API. The example displays a message box with **Retry** and **Cancel** buttons, and displays the return value from the message box. - +> Starting with the .NET Framework 2.0 Service Pack 1, this member no longer requires with the flag. (See [Security Issues in Reflection Emit](/dotnet/framework/reflection-and-codedom/security-issues-in-reflection-emit).) To use this functionality, your application should target the .NET Framework 3.5 or later. + + + +## Examples + The following example illustrates the use of the `DefinePInvokeMethod` method to create a for an external unmanaged method, `MessageBoxA`, in the Windows API. The example displays a message box with **Retry** and **Cancel** buttons, and displays the return value from the message box. + > [!IMPORTANT] -> To get a non-zero return value, you must add to the method implementation flags after you create the , by using the and methods. - - This example uses a different overload of the method, but the technique is the same. - +> To get a non-zero return value, you must add to the method implementation flags after you create the , by using the and methods. + + This example uses a different overload of the method, but the technique is the same. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/ModuleBuilder_DefinePInvokeMethod1/CPP/modulebuilder_definepinvokemethod1.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/ModuleBuilder/DefinePInvokeMethod/modulebuilder_definepinvokemethod1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ModuleBuilder_DefinePInvokeMethod1/VB/modulebuilder_definepinvokemethod1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ModuleBuilder_DefinePInvokeMethod1/VB/modulebuilder_definepinvokemethod1.vb" id="Snippet1"::: + ]]> The method is not static or if the containing type is an interface or if the method is abstract of if the method was previously defined. @@ -1401,8 +1401,8 @@ System.Resources.IResourceWriter - - + + The name of the resource. cannot contain embedded nulls. @@ -1410,34 +1410,34 @@ Defines the named managed embedded resource to be stored in this module. A resource writer for the defined resource. - method. For a summary of embedding and linking managed resources and manifest resource blobs, see the method. - + method. For a summary of embedding and linking managed resources and manifest resource blobs, see the method. + > [!NOTE] -> Starting with the .NET Framework 2.0 Service Pack 1, this member no longer requires with the flag. (See [Security Issues in Reflection Emit](/dotnet/framework/reflection-and-codedom/security-issues-in-reflection-emit).) To use this functionality, your application should target the .NET Framework 3.5 or later. - - - -## Examples - The following example illustrates the use of `DefineResource` to add an external resource to the current . - +> Starting with the .NET Framework 2.0 Service Pack 1, this member no longer requires with the flag. (See [Security Issues in Reflection Emit](/dotnet/framework/reflection-and-codedom/security-issues-in-reflection-emit).) To use this functionality, your application should target the .NET Framework 3.5 or later. + + + +## Examples + The following example illustrates the use of `DefineResource` to add an external resource to the current . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/ModuleBuilder_DefineResource1/CPP/modulebuilder_defineresource1.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/ModuleBuilder/DefineResource/modulebuilder_defineresource1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ModuleBuilder_DefineResource1/VB/modulebuilder_defineresource1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ModuleBuilder_DefineResource1/VB/modulebuilder_defineresource1.vb" id="Snippet1"::: + ]]> Length of is zero. is null. - This module is transient. - - -or- - + This module is transient. + + -or- + The containing assembly is not persistable. @@ -1466,9 +1466,9 @@ System.Resources.IResourceWriter - - - + + + The name of the resource. cannot contain embedded nulls. @@ -1477,34 +1477,34 @@ Defines the named managed embedded resource with the given attributes that is to be stored in this module. A resource writer for the defined resource. - method. For a summary of embedding and linking managed resources and manifest resource blobs, see the method. - + method. For a summary of embedding and linking managed resources and manifest resource blobs, see the method. + > [!NOTE] -> Starting with the .NET Framework 2.0 Service Pack 1, this member no longer requires with the flag. (See [Security Issues in Reflection Emit](/dotnet/framework/reflection-and-codedom/security-issues-in-reflection-emit).) To use this functionality, your application should target the .NET Framework 3.5 or later. - - - -## Examples - The following example illustrates the use of DefineResource to add an external resource to the current . - +> Starting with the .NET Framework 2.0 Service Pack 1, this member no longer requires with the flag. (See [Security Issues in Reflection Emit](/dotnet/framework/reflection-and-codedom/security-issues-in-reflection-emit).) To use this functionality, your application should target the .NET Framework 3.5 or later. + + + +## Examples + The following example illustrates the use of DefineResource to add an external resource to the current . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/ModuleBuilder_DefineResource2/CPP/modulebuilder_defineresource2.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/ModuleBuilder/DefineResource/modulebuilder_defineresource2.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ModuleBuilder_DefineResource2/VB/modulebuilder_defineresource2.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ModuleBuilder_DefineResource2/VB/modulebuilder_defineresource2.vb" id="Snippet1"::: + ]]> Length of is zero. is null. - This module is transient. - - -or- - + This module is transient. + + -or- + The containing assembly is not persistable. @@ -1567,29 +1567,29 @@ Constructs a for a private type with the specified name in this module. A private type with the specified name. - [!NOTE] -> Starting with the .NET Framework 2.0 Service Pack 1, this member no longer requires with the flag. (See [Security Issues in Reflection Emit](/dotnet/framework/reflection-and-codedom/security-issues-in-reflection-emit).) To use this functionality, your application should target the .NET Framework 3.5 or later. - - - -## Examples - The following example creates a in the current dynamic module using `CreateType`, builds and completes the type, and saves the assembly. - +> Starting with the .NET Framework 2.0 Service Pack 1, this member no longer requires with the flag. (See [Security Issues in Reflection Emit](/dotnet/framework/reflection-and-codedom/security-issues-in-reflection-emit).) To use this functionality, your application should target the .NET Framework 3.5 or later. + + + +## Examples + The following example creates a in the current dynamic module using `CreateType`, builds and completes the type, and saves the assembly. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic ModuleBuilder.DefineType Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/ModuleBuilder/DefineType/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic ModuleBuilder.DefineType Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic ModuleBuilder.DefineType Example/VB/source.vb" id="Snippet1"::: + ]]> - A type with the given name exists in the parent assembly of this module. - - -or- - + A type with the given name exists in the parent assembly of this module. + + -or- + Nested type attributes are set on a type that is not nested. is . @@ -1645,29 +1645,29 @@ Constructs a given the type name and the type attributes. A created with all of the requested attributes. - [!NOTE] -> Starting with the .NET Framework 2.0 Service Pack 1, this member no longer requires with the flag. (See [Security Issues in Reflection Emit](/dotnet/framework/reflection-and-codedom/security-issues-in-reflection-emit).) To use this functionality, your application should target the .NET Framework 3.5 or later. - - - -## Examples - The following example creates a in the current dynamic module using `CreateType`, builds and completes the type, and saves the assembly. - +> Starting with the .NET Framework 2.0 Service Pack 1, this member no longer requires with the flag. (See [Security Issues in Reflection Emit](/dotnet/framework/reflection-and-codedom/security-issues-in-reflection-emit).) To use this functionality, your application should target the .NET Framework 3.5 or later. + + + +## Examples + The following example creates a in the current dynamic module using `CreateType`, builds and completes the type, and saves the assembly. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic ModuleBuilder.DefineType Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/ModuleBuilder/DefineType/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic ModuleBuilder.DefineType Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic ModuleBuilder.DefineType Example/VB/source.vb" id="Snippet1"::: + ]]> - A type with the given name exists in the parent assembly of this module. - - -or- - + A type with the given name exists in the parent assembly of this module. + + -or- + Nested type attributes are set on a type that is not nested. is . @@ -1737,29 +1737,29 @@ Constructs a given type name, its attributes, and the type that the defined type extends. A created with all of the requested attributes. - [!NOTE] -> Starting with the .NET Framework 2.0 Service Pack 1, this member no longer requires with the flag. (See [Security Issues in Reflection Emit](/dotnet/framework/reflection-and-codedom/security-issues-in-reflection-emit).) To use this functionality, your application should target the .NET Framework 3.5 or later. - - - -## Examples - The following example creates a in the current dynamic module using `CreateType`, builds and completes the type, and saves the assembly. - +> Starting with the .NET Framework 2.0 Service Pack 1, this member no longer requires with the flag. (See [Security Issues in Reflection Emit](/dotnet/framework/reflection-and-codedom/security-issues-in-reflection-emit).) To use this functionality, your application should target the .NET Framework 3.5 or later. + + + +## Examples + The following example creates a in the current dynamic module using `CreateType`, builds and completes the type, and saves the assembly. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic ModuleBuilder.DefineType Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/ModuleBuilder/DefineType/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic ModuleBuilder.DefineType Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic ModuleBuilder.DefineType Example/VB/source.vb" id="Snippet1"::: + ]]> - A type with the given name exists in the parent assembly of this module. - - -or- - + A type with the given name exists in the parent assembly of this module. + + -or- + Nested type attributes are set on a type that is not nested. is . @@ -1831,29 +1831,29 @@ Constructs a given the type name, the attributes, the type that the defined type extends, and the total size of the type. A object. - [!NOTE] -> Starting with the .NET Framework 2.0 Service Pack 1, this member no longer requires with the flag. (See [Security Issues in Reflection Emit](/dotnet/framework/reflection-and-codedom/security-issues-in-reflection-emit).) To use this functionality, your application should target the .NET Framework 3.5 or later. - - - -## Examples - The following example creates a in the current dynamic module using `CreateType`, builds and completes the type, and saves the assembly. - +> Starting with the .NET Framework 2.0 Service Pack 1, this member no longer requires with the flag. (See [Security Issues in Reflection Emit](/dotnet/framework/reflection-and-codedom/security-issues-in-reflection-emit).) To use this functionality, your application should target the .NET Framework 3.5 or later. + + + +## Examples + The following example creates a in the current dynamic module using `CreateType`, builds and completes the type, and saves the assembly. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic ModuleBuilder.DefineType Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/ModuleBuilder/DefineType/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic ModuleBuilder.DefineType Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic ModuleBuilder.DefineType Example/VB/source.vb" id="Snippet1"::: + ]]> - A type with the given name exists in the parent assembly of this module. - - -or- - + A type with the given name exists in the parent assembly of this module. + + -or- + Nested type attributes are set on a type that is not nested. is . @@ -1925,29 +1925,29 @@ Constructs a given the type name, the attributes, the type that the defined type extends, and the packing size of the type. A object. - [!NOTE] -> Starting with the .NET Framework 2.0 Service Pack 1, this member no longer requires with the flag. (See [Security Issues in Reflection Emit](/dotnet/framework/reflection-and-codedom/security-issues-in-reflection-emit).) To use this functionality, your application should target the .NET Framework 3.5 or later. - - - -## Examples - The following example creates a in the current dynamic module using `CreateType`, builds and completes the type, and saves the assembly. - +> Starting with the .NET Framework 2.0 Service Pack 1, this member no longer requires with the flag. (See [Security Issues in Reflection Emit](/dotnet/framework/reflection-and-codedom/security-issues-in-reflection-emit).) To use this functionality, your application should target the .NET Framework 3.5 or later. + + + +## Examples + The following example creates a in the current dynamic module using `CreateType`, builds and completes the type, and saves the assembly. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic ModuleBuilder.DefineType Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/ModuleBuilder/DefineType/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic ModuleBuilder.DefineType Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic ModuleBuilder.DefineType Example/VB/source.vb" id="Snippet1"::: + ]]> - A type with the given name exists in the parent assembly of this module. - - -or- - + A type with the given name exists in the parent assembly of this module. + + -or- + Nested type attributes are set on a type that is not nested. is . @@ -2030,29 +2030,29 @@ Constructs a given the type name, attributes, the type that the defined type extends, and the interfaces that the defined type implements. A created with all of the requested attributes. - [!NOTE] -> Starting with the .NET Framework 2.0 Service Pack 1, this member no longer requires with the flag. (See [Security Issues in Reflection Emit](/dotnet/framework/reflection-and-codedom/security-issues-in-reflection-emit).) To use this functionality, your application should target the .NET Framework 3.5 or later. - - - -## Examples - The following example creates a in the current dynamic module using `CreateType`, builds and completes the type, and saves the assembly. - +> Starting with the .NET Framework 2.0 Service Pack 1, this member no longer requires with the flag. (See [Security Issues in Reflection Emit](/dotnet/framework/reflection-and-codedom/security-issues-in-reflection-emit).) To use this functionality, your application should target the .NET Framework 3.5 or later. + + + +## Examples + The following example creates a in the current dynamic module using `CreateType`, builds and completes the type, and saves the assembly. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic ModuleBuilder.DefineType Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/ModuleBuilder/DefineType/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic ModuleBuilder.DefineType Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic ModuleBuilder.DefineType Example/VB/source.vb" id="Snippet1"::: + ]]> - A type with the given name exists in the parent assembly of this module. - - -or- - + A type with the given name exists in the parent assembly of this module. + + -or- + Nested type attributes are set on a type that is not nested. is . @@ -2126,29 +2126,29 @@ Constructs a given the type name, attributes, the type that the defined type extends, the packing size of the defined type, and the total size of the defined type. A created with all of the requested attributes. - [!NOTE] -> Starting with the .NET Framework 2.0 Service Pack 1, this member no longer requires with the flag. (See [Security Issues in Reflection Emit](/dotnet/framework/reflection-and-codedom/security-issues-in-reflection-emit).) To use this functionality, your application should target the .NET Framework 3.5 or later. - - - -## Examples - The following example creates a in the current dynamic module using `CreateType`, builds and completes the type, and saves the assembly. - +> Starting with the .NET Framework 2.0 Service Pack 1, this member no longer requires with the flag. (See [Security Issues in Reflection Emit](/dotnet/framework/reflection-and-codedom/security-issues-in-reflection-emit).) To use this functionality, your application should target the .NET Framework 3.5 or later. + + + +## Examples + The following example creates a in the current dynamic module using `CreateType`, builds and completes the type, and saves the assembly. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic ModuleBuilder.DefineType Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/ModuleBuilder/DefineType/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic ModuleBuilder.DefineType Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic ModuleBuilder.DefineType Example/VB/source.vb" id="Snippet1"::: + ]]> - A type with the given name exists in the parent assembly of this module. - - -or- - + A type with the given name exists in the parent assembly of this module. + + -or- + Nested type attributes are set on a type that is not nested. is . @@ -2266,22 +2266,22 @@ Defines an uninitialized data field in the .sdata section of the portable executable (PE) file. A field to reference the data. - is automatically included in `attributes`. - - The data defined by this method is not created until the method is called. - + is automatically included in `attributes`. + + The data defined by this method is not created until the method is called. + > [!NOTE] -> Starting with the .NET Framework 2.0 Service Pack 1, this member no longer requires with the flag. (See [Security Issues in Reflection Emit](/dotnet/framework/reflection-and-codedom/security-issues-in-reflection-emit).) To use this functionality, your application should target the .NET Framework 3.5 or later. - +> Starting with the .NET Framework 2.0 Service Pack 1, this member no longer requires with the flag. (See [Security Issues in Reflection Emit](/dotnet/framework/reflection-and-codedom/security-issues-in-reflection-emit).) To use this functionality, your application should target the .NET Framework 3.5 or later. + ]]> - The length of is zero. - - -or- - + The length of is zero. + + -or- + is less than or equal to zero, or greater than or equal to 0x003f0000. is . @@ -2359,20 +2359,20 @@ System.Void - + An opaque BLOB that represents an unmanaged resource. Defines an unmanaged embedded resource given an opaque binary large object (BLOB) of bytes. - . Multiple unmanaged resources need to be merged with a tool such as the Microsoft ResMerge utility (not supplied with the common language runtime). - + . Multiple unmanaged resources need to be merged with a tool such as the Microsoft ResMerge utility (not supplied with the common language runtime). + > [!NOTE] -> Starting with the .NET Framework 2.0 Service Pack 1, this member no longer requires with the flag. (See [Security Issues in Reflection Emit](/dotnet/framework/reflection-and-codedom/security-issues-in-reflection-emit).) To use this functionality, your application should target the .NET Framework 3.5 or later. - +> Starting with the .NET Framework 2.0 Service Pack 1, this member no longer requires with the flag. (See [Security Issues in Reflection Emit](/dotnet/framework/reflection-and-codedom/security-issues-in-reflection-emit).) To use this functionality, your application should target the .NET Framework 3.5 or later. + ]]> An unmanaged resource has already been defined in the module's assembly. @@ -2410,34 +2410,34 @@ System.Void - + The name of the unmanaged resource file. Defines an unmanaged resource given the name of Win32 resource file. - . Multiple unmanaged resources need to be merged with a tool such as the Microsoft ResMerge utility (not supplied with the common language runtime). - + . Multiple unmanaged resources need to be merged with a tool such as the Microsoft ResMerge utility (not supplied with the common language runtime). + > [!NOTE] -> Starting with the .NET Framework 2.0 Service Pack 1, this member no longer requires with the flag. (See [Security Issues in Reflection Emit](/dotnet/framework/reflection-and-codedom/security-issues-in-reflection-emit).) To use this functionality, your application should target the .NET Framework 3.5 or later. - +> Starting with the .NET Framework 2.0 Service Pack 1, this member no longer requires with the flag. (See [Security Issues in Reflection Emit](/dotnet/framework/reflection-and-codedom/security-issues-in-reflection-emit).) To use this functionality, your application should target the .NET Framework 3.5 or later. + ]]> - An unmanaged resource has already been defined in the module's assembly. - - -or- - + An unmanaged resource has already been defined in the module's assembly. + + -or- + is the empty string (""). is . - is not found. - - -or- - + is not found. + + -or- + is a directory. @@ -2539,14 +2539,14 @@ Gets a representing the fully qualified name and path to this module. The fully qualified module name. - [!NOTE] -> The case of a module name is platform dependent. - +> The case of a module name is platform dependent. + ]]> @@ -2622,20 +2622,20 @@ Returns the named method on an array class. The named method on an array class. - . For example, you might define a type and want to define a method that takes an array of the type as a parameter. In order to access the elements of the array, you will need to call methods of the class. - - - -## Examples - The following example demonstrates how to use to obtain the corresponding to a method that returns an array value. - + . For example, you might define a type and want to define a method that takes an array of the type as a parameter. In order to access the elements of the array, you will need to call methods of the class. + + + +## Examples + The following example demonstrates how to use to obtain the corresponding to a method that returns an array value. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/ModuleBuilder_GetArrayMethod/CPP/modulebuilder_getarraymethod.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/ModuleBuilder/GetArrayMethod/modulebuilder_getarraymethod.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ModuleBuilder_GetArrayMethod/VB/modulebuilder_getarraymethod.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ModuleBuilder_GetArrayMethod/VB/modulebuilder_getarraymethod.vb" id="Snippet1"::: + ]]> @@ -2729,11 +2729,11 @@ System.Reflection.Emit.MethodToken - - - - - + + + + + The object for the array. @@ -2744,27 +2744,27 @@ Returns the token for the named method on an array class. The token for the named method on an array class. - , except that it returns the token of the array method instead of the method itself. - - - -## Examples - The following example demonstrates how to use to obtain the corresponding to a method that returns an array value. - + , except that it returns the token of the array method instead of the method itself. + + + +## Examples + The following example demonstrates how to use to obtain the corresponding to a method that returns an array value. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/ModuleBuilder_GetArrayMethod/CPP/modulebuilder_getarraymethod.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/ModuleBuilder/GetArrayMethod/modulebuilder_getarraymethod.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ModuleBuilder_GetArrayMethod/VB/modulebuilder_getarraymethod.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ModuleBuilder_GetArrayMethod/VB/modulebuilder_getarraymethod.vb" id="Snippet2"::: + ]]> - is not an array. - - -or- - + is not an array. + + -or- + The length of is zero. or is . @@ -2815,7 +2815,7 @@ System.Reflection.Emit.MethodToken - + The constructor to get a token for. @@ -2855,8 +2855,8 @@ System.Reflection.Emit.MethodToken - - + + The constructor to get a token for. @@ -2995,11 +2995,11 @@ Returns information about the attributes that have been applied to the current , expressed as objects. A generic list of objects representing data about the attributes that have been applied to the current module. - and cannot be used in such cases, because they create instances of the attributes. Code in the reflection-only context cannot be executed. For more information and for example code, see the class. - + and cannot be used in such cases, because they create instances of the attributes. Code in the reflection-only context cannot be executed. For more information and for example code, see the class. + ]]> @@ -3050,14 +3050,14 @@ Returns a module-level field, defined in the .sdata region of the portable executable (PE) file, that has the specified name and binding attributes. A field that has the specified name and binding attributes, or if the field does not exist. - or methods. - + or methods. + > [!IMPORTANT] -> Module-level fields cannot be retrieved until after the method has been called for the module. - +> Module-level fields cannot be retrieved until after the method has been called for the module. + ]]> The parameter is . @@ -3138,14 +3138,14 @@ Returns all fields defined in the .sdata region of the portable executable (PE) file that match the specified binding flags. An array of fields that match the specified flags; the array is empty if no such fields exist. - or methods. - + or methods. + > [!IMPORTANT] -> Module-level fields cannot be retrieved until after the method has been called for the module. - +> Module-level fields cannot be retrieved until after the method has been called for the module. + ]]> The parameter is . @@ -3182,7 +3182,7 @@ System.Reflection.Emit.FieldToken - + The field to get a token for. @@ -3270,7 +3270,7 @@ System.Reflection.MethodInfo - + [System.Runtime.CompilerServices.Nullable(1)] @@ -3278,10 +3278,10 @@ - - - - + + + + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 2, 1 })] @@ -3289,7 +3289,7 @@ - + The method name. @@ -3301,14 +3301,14 @@ Returns the module-level method that matches the specified criteria. A method that is defined at the module level, and matches the specified criteria; or if such a method does not exist. - method. Use the inherited method to get methods that have been declared at the module level. Module-level methods are defined in emitted code by using the method. - + method. Use the inherited method to get methods that have been declared at the module level. Module-level methods are defined in emitted code by using the method. + > [!IMPORTANT] -> Module-level methods cannot be retrieved until after the method has been called for the module. - +> Module-level methods cannot be retrieved until after the method has been called for the module. + ]]> @@ -3425,14 +3425,14 @@ Returns all the methods that have been defined at the module level for the current , and that match the specified binding flags. An array that contains all the module-level methods that match . - method. - + method. + > [!IMPORTANT] -> Module-level methods cannot be retrieved until after the method has been called for the module. - +> Module-level methods cannot be retrieved until after the method has been called for the module. + ]]> @@ -3478,7 +3478,7 @@ System.Reflection.Emit.MethodToken - + The method to get a token for. @@ -3519,8 +3519,8 @@ System.Reflection.Emit.MethodToken - - + + The method to get a token for. @@ -3570,11 +3570,11 @@ When this method returns, one of the values indicating the platform targeted by the module. Gets a pair of values indicating the nature of the code in a module and the platform targeted by the module. - and `machine` is always 0 (zero). - + and `machine` is always 0 (zero). + ]]> @@ -3652,18 +3652,18 @@ System.Reflection.Emit.SignatureToken - + The signature. Defines a token for the signature that is defined by the specified . A token for the defined signature. - @@ -3701,8 +3701,8 @@ System.Reflection.Emit.SignatureToken - - + + The signature binary large object (BLOB). @@ -3779,18 +3779,18 @@ System.Reflection.Emit.StringToken - + The string to add to the module's constant pool. Returns the token of the given string in the module's constant pool. The token of the string in the constant pool. - @@ -3857,13 +3857,13 @@ Returns the symbol writer associated with this dynamic module. The symbol writer associated with this dynamic module. - [!NOTE] -> Starting with the .NET Framework 2.0 Service Pack 1, this member no longer requires with the flag. (See [Security Issues in Reflection Emit](/dotnet/framework/reflection-and-codedom/security-issues-in-reflection-emit).) To use this functionality, your application should target the .NET Framework 3.5 or later. - +> Starting with the .NET Framework 2.0 Service Pack 1, this member no longer requires with the flag. (See [Security Issues in Reflection Emit](/dotnet/framework/reflection-and-codedom/security-issues-in-reflection-emit).) To use this functionality, your application should target the .NET Framework 3.5 or later. + ]]> @@ -3932,14 +3932,14 @@ Gets the named type defined in the module. The requested type, if the type is defined in this module; otherwise, . - , , and methods instead. - + , , and methods instead. + > [!NOTE] -> Starting with the .NET Framework 2.0 Service Pack 1, this member no longer requires with the flag. (See [Security Issues in Reflection Emit](/dotnet/framework/reflection-and-codedom/security-issues-in-reflection-emit).) To use this functionality, your application should target the .NET Framework 3.5 or later. - +> Starting with the .NET Framework 2.0 Service Pack 1, this member no longer requires with the flag. (See [Security Issues in Reflection Emit](/dotnet/framework/reflection-and-codedom/security-issues-in-reflection-emit).) To use this functionality, your application should target the .NET Framework 3.5 or later. + ]]> Length of is zero or is greater than 1023. @@ -4006,14 +4006,14 @@ Gets the named type defined in the module, optionally ignoring the case of the type name. The requested type, if the type is defined in this module; otherwise, . - , , and methods instead. - + , , and methods instead. + > [!NOTE] -> Starting with the .NET Framework 2.0 Service Pack 1, this member no longer requires with the flag. (See [Security Issues in Reflection Emit](/dotnet/framework/reflection-and-codedom/security-issues-in-reflection-emit).) To use this functionality, your application should target the .NET Framework 3.5 or later. - +> Starting with the .NET Framework 2.0 Service Pack 1, this member no longer requires with the flag. (See [Security Issues in Reflection Emit](/dotnet/framework/reflection-and-codedom/security-issues-in-reflection-emit).) To use this functionality, your application should target the .NET Framework 3.5 or later. + ]]> Length of is zero or is greater than 1023. @@ -4082,16 +4082,16 @@ Gets the named type defined in the module, optionally ignoring the case of the type name. Optionally throws an exception if the type is not found. The specified type, if the type is declared in this module; otherwise, . - can be thrown even if `throwOnError` is `false`. - - Do not use this method to generate array types, pointer types, or byref types. Use the , , and methods instead. - + can be thrown even if `throwOnError` is `false`. + + Do not use this method to generate array types, pointer types, or byref types. Use the , , and methods instead. + > [!NOTE] -> Starting with the .NET Framework 2.0 Service Pack 1, this member no longer requires with the flag. (See [Security Issues in Reflection Emit](/dotnet/framework/reflection-and-codedom/security-issues-in-reflection-emit).) To use this functionality, your application should target the .NET Framework 3.5 or later. - +> Starting with the .NET Framework 2.0 Service Pack 1, this member no longer requires with the flag. (See [Security Issues in Reflection Emit](/dotnet/framework/reflection-and-codedom/security-issues-in-reflection-emit).) To use this functionality, your application should target the .NET Framework 3.5 or later. + ]]> Length of is zero or is greater than 1023. @@ -4177,16 +4177,16 @@ Returns all the classes defined within this module. An array that contains the types defined within the module that is reflected by this instance. - [!NOTE] -> Starting with the .NET Framework 2.0 Service Pack 1, this member no longer requires with the flag. (See [Security Issues in Reflection Emit](/dotnet/framework/reflection-and-codedom/security-issues-in-reflection-emit).) To use this functionality, your application should target the .NET Framework 3.5 or later. - +> Starting with the .NET Framework 2.0 Service Pack 1, this member no longer requires with the flag. (See [Security Issues in Reflection Emit](/dotnet/framework/reflection-and-codedom/security-issues-in-reflection-emit).) To use this functionality, your application should target the .NET Framework 3.5 or later. + ]]> One or more classes in a module could not be loaded. @@ -4229,31 +4229,31 @@ System.Reflection.Emit.TypeToken - + The name of the class, including the namespace. Returns the token used to identify the type with the specified name. The token used to identify the type with the specified name within this module. - class who want to directly modify the body of a method. - + class who want to directly modify the body of a method. + ]]> - is the empty string (""). - - -or- - + is the empty string (""). + + -or- + represents a type. - is . - - -or- - + is . + + -or- + The type specified by could not be found. This is a non-transient module that references a transient module. @@ -4289,18 +4289,18 @@ System.Reflection.Emit.TypeToken - + The type object that represents the class type. Returns the token used to identify the specified type within this module. The token used to identify the given type within this module. - @@ -4457,13 +4457,13 @@ Gets the metadata stream version. A 32-bit integer representing the metadata stream version. The high-order two bytes represent the major version number, and the low-order two bytes represent the minor version number. - [!NOTE] > For more information on the metadata header, see "Partition II: Metadata Definition and Semantics" in the [ECMA 335 Common Language Infrastructure (CLI)](https://www.ecma-international.org/publications-and-standards/standards/ecma-335/)(https://www.ecma-international.org/publications-and-standards/standards/ecma-335/) specification. - + ]]> @@ -4501,14 +4501,14 @@ Gets a token that identifies the current dynamic module in metadata. An integer token that identifies the current module in metadata. - [!NOTE] > Information about metadata tokens can be found in the Common Language Infrastructure (CLI) documentation, especially "Partition II: Metadata Definition and Semantics". For more information, see [ECMA 335 Common Language Infrastructure (CLI)](https://www.ecma-international.org/publications-and-standards/standards/ecma-335/). - + ]]> @@ -4546,14 +4546,14 @@ Gets a universally unique identifier (UUID) that can be used to distinguish between two versions of a module. A that can be used to distinguish between two versions of a module. - property is referred to as the `mvid`, and is stored in the GUID heap. - + property is referred to as the `mvid`, and is stored in the GUID heap. + > [!NOTE] > More information about metadata can be found in the Common Language Infrastructure (CLI) documentation, especially "Partition II: Metadata Definition and Semantics". For more information, see [ECMA 335 Common Language Infrastructure (CLI)](https://www.ecma-international.org/publications-and-standards/standards/ecma-335/). - + ]]> @@ -4600,11 +4600,11 @@ A string that indicates that this is an in-memory module. Text that indicates that this is an in-memory module. - @@ -4675,23 +4675,23 @@ Returns the field identified by the specified metadata token, in the context defined by the specified generic type parameters. A object representing the field that is identified by the specified metadata token. - method on the type where `metadataToken` is in scope to obtain an array of generic type arguments for `genericTypeArguments`. Use the method on the method where `metadataToken` is in scope to obtain an array of generic type arguments for `genericTypeArguments`. It is always safe to provide these arguments, even when they are not needed. - + method on the type where `metadataToken` is in scope to obtain an array of generic type arguments for `genericTypeArguments`. Use the method on the method where `metadataToken` is in scope to obtain an array of generic type arguments for `genericTypeArguments`. It is always safe to provide these arguments, even when they are not needed. + > [!NOTE] > Information about metadata tokens can be found in the Common Language Infrastructure (CLI) documentation, especially "Partition II: Metadata Definition and Semantics". For more information, see [ECMA 335 Common Language Infrastructure (CLI)](https://www.ecma-international.org/publications-and-standards/standards/ecma-335/). - - For code that demonstrates token resolution using the generic context (that is, the generic type parameters of the generic type and/or the generic method in which the token is embedded) see the method. - + + For code that demonstrates token resolution using the generic context (that is, the generic type parameters of the generic type and/or the generic method in which the token is embedded) see the method. + ]]> - is not a token for a field in the scope of the current module. - - -or- - + is not a token for a field in the scope of the current module. + + -or- + identifies a field whose parent has a signature containing element type (a type parameter of a generic type) or (a type parameter of a generic method), and the necessary generic type arguments were not supplied for either or both of and . is not a valid token in the scope of the current module. @@ -4763,27 +4763,27 @@ Returns the type or member identified by the specified metadata token, in the context defined by the specified generic type parameters. A object representing the type or member that is identified by the specified metadata token. - method on the type where `metadataToken` is in scope to obtain an array of generic type arguments for `genericTypeArguments`. Use the method on the method where `metadataToken` is in scope to obtain an array of generic type arguments for `genericTypeArguments`. It is always safe to provide these arguments, even when they are not needed. - + method on the type where `metadataToken` is in scope to obtain an array of generic type arguments for `genericTypeArguments`. Use the method on the method where `metadataToken` is in scope to obtain an array of generic type arguments for `genericTypeArguments`. It is always safe to provide these arguments, even when they are not needed. + > [!NOTE] > Information about metadata tokens can be found in the Common Language Infrastructure (CLI) documentation, especially "Partition II: Metadata Definition and Semantics". For more information, see [ECMA 335 Common Language Infrastructure (CLI)](https://www.ecma-international.org/publications-and-standards/standards/ecma-335/). - - For code that demonstrates token resolution using the generic context (that is, the generic type parameters of the generic type and/or the generic method in which the token is embedded) see the method. - + + For code that demonstrates token resolution using the generic context (that is, the generic type parameters of the generic type and/or the generic method in which the token is embedded) see the method. + ]]> - is not a token for a type or member in the scope of the current module. - - -or- - - is a or whose signature contains element type (a type parameter of a generic type) or (a type parameter of a generic method), and the necessary generic type arguments were not supplied for either or both of and . - - -or- - + is not a token for a type or member in the scope of the current module. + + -or- + + is a or whose signature contains element type (a type parameter of a generic type) or (a type parameter of a generic method), and the necessary generic type arguments were not supplied for either or both of and . + + -or- + identifies a property or event. is not a valid token in the scope of the current module. @@ -4855,23 +4855,23 @@ Returns the method or constructor identified by the specified metadata token, in the context defined by the specified generic type parameters. A object representing the method that is identified by the specified metadata token. - method on the type where `metadataToken` is in scope to obtain an array of generic type arguments for `genericTypeArguments`. Use the method on the method where `metadataToken` is in scope to obtain an array of generic type arguments for `genericMethodArguments`. It is always safe to provide these arguments, even when they are not needed. - + method on the type where `metadataToken` is in scope to obtain an array of generic type arguments for `genericTypeArguments`. Use the method on the method where `metadataToken` is in scope to obtain an array of generic type arguments for `genericMethodArguments`. It is always safe to provide these arguments, even when they are not needed. + > [!NOTE] > Information about metadata tokens can be found in the Common Language Infrastructure (CLI) documentation, especially "Partition II: Metadata Definition and Semantics". For more information, see [ECMA 335 Common Language Infrastructure (CLI)](https://www.ecma-international.org/publications-and-standards/standards/ecma-335/). - - For code that demonstrates token resolution using the generic context (that is, the generic type parameters of the generic type and/or the generic method in which the token is embedded) see the method. - + + For code that demonstrates token resolution using the generic context (that is, the generic type parameters of the generic type and/or the generic method in which the token is embedded) see the method. + ]]> - is not a token for a method or constructor in the scope of the current module. - - -or- - + is not a token for a method or constructor in the scope of the current module. + + -or- + is a whose signature contains element type (a type parameter of a generic type) or (a type parameter of a generic method), and the necessary generic type arguments were not supplied for either or both of and . is not a valid token in the scope of the current module. @@ -4920,13 +4920,13 @@ Returns the signature blob identified by a metadata token. An array of bytes representing the signature blob. - [!NOTE] > Information about metadata tokens and signatures can be found in the Common Language Infrastructure (CLI) documentation, especially "Partition II: Metadata Definition and Semantics". For more information, see [ECMA 335 Common Language Infrastructure (CLI)](https://www.ecma-international.org/publications-and-standards/standards/ecma-335/). - + ]]> @@ -4978,13 +4978,13 @@ Returns the string identified by the specified metadata token. A containing a string value from the metadata string heap. - [!NOTE] > Information about metadata tokens can be found in the Common Language Infrastructure (CLI) documentation, especially "Partition II: Metadata Definition and Semantics". For more information, see [ECMA 335 Common Language Infrastructure (CLI)](https://www.ecma-international.org/publications-and-standards/standards/ecma-335/). - + ]]> @@ -5055,23 +5055,23 @@ Returns the type identified by the specified metadata token, in the context defined by the specified generic type parameters. A object representing the type that is identified by the specified metadata token. - method on the type where `metadataToken` is in scope to obtain an array of generic type arguments for `genericTypeArguments`. Use the method on the method where `metadataToken` is in scope to obtain an array of generic type arguments for `genericTypeArguments`. It is always safe to provide these arguments, even when they are not needed. - + method on the type where `metadataToken` is in scope to obtain an array of generic type arguments for `genericTypeArguments`. Use the method on the method where `metadataToken` is in scope to obtain an array of generic type arguments for `genericTypeArguments`. It is always safe to provide these arguments, even when they are not needed. + > [!NOTE] > Information about metadata tokens can be found in the Common Language Infrastructure (CLI) documentation, especially "Partition II: Metadata Definition and Semantics". For more information, see [ECMA 335 Common Language Infrastructure (CLI)](https://www.ecma-international.org/publications-and-standards/standards/ecma-335/). - - For code that demonstrates token resolution using the generic context (that is, the generic type parameters of the generic type and/or the generic method in which the token is embedded) see the method. - + + For code that demonstrates token resolution using the generic context (that is, the generic type parameters of the generic type and/or the generic method in which the token is embedded) see the method. + ]]> - is not a token for a type in the scope of the current module. - - -or- - + is not a token for a type in the scope of the current module. + + -or- + is a whose signature contains element type (a type parameter of a generic type) or (a type parameter of a generic method), and the necessary generic type arguments were not supplied for either or both of and . is not a valid token in the scope of the current module. @@ -5169,13 +5169,13 @@ An instance of a helper class that specifies the custom attribute to apply. Applies a custom attribute to this module by using a custom attribute builder. - [!NOTE] -> Starting with the .NET Framework 2.0 Service Pack 1, this member no longer requires with the flag. (See [Security Issues in Reflection Emit](/dotnet/framework/reflection-and-codedom/security-issues-in-reflection-emit).) To use this functionality, your application should target the .NET Framework 3.5 or later. - +> Starting with the .NET Framework 2.0 Service Pack 1, this member no longer requires with the flag. (See [Security Issues in Reflection Emit](/dotnet/framework/reflection-and-codedom/security-issues-in-reflection-emit).) To use this functionality, your application should target the .NET Framework 3.5 or later. + ]]> @@ -5235,14 +5235,14 @@ A byte BLOB representing the attribute. Applies a custom attribute to this module by using a specified binary large object (BLOB) that represents the attribute. - [!NOTE] -> Starting with the .NET Framework 2.0 Service Pack 1, this member no longer requires with the flag. (See [Security Issues in Reflection Emit](/dotnet/framework/reflection-and-codedom/security-issues-in-reflection-emit).) To use this functionality, your application should target the .NET Framework 3.5 or later. - +> Starting with the .NET Framework 2.0 Service Pack 1, this member no longer requires with the flag. (See [Security Issues in Reflection Emit](/dotnet/framework/reflection-and-codedom/security-issues-in-reflection-emit).) To use this functionality, your application should target the .NET Framework 3.5 or later. + ]]> @@ -5319,22 +5319,22 @@ System.Void - - + + The name of the custom attribute. An opaque binary large object (BLOB) of bytes that represents the value of the custom attribute. This method does nothing. - [!NOTE] -> Starting with the .NET Framework 2.0 Service Pack 1, this member no longer requires with the flag. (See [Security Issues in Reflection Emit](/dotnet/framework/reflection-and-codedom/security-issues-in-reflection-emit).) To use this functionality, your application should target the .NET Framework 3.5 or later. - +> Starting with the .NET Framework 2.0 Service Pack 1, this member no longer requires with the flag. (See [Security Issues in Reflection Emit](/dotnet/framework/reflection-and-codedom/security-issues-in-reflection-emit).) To use this functionality, your application should target the .NET Framework 3.5 or later. + ]]> @@ -5372,28 +5372,28 @@ System.Void - + The user entry point. Sets the user entry point. - [!NOTE] -> Starting with the .NET Framework 2.0 Service Pack 1, this member no longer requires with the flag. (See [Security Issues in Reflection Emit](/dotnet/framework/reflection-and-codedom/security-issues-in-reflection-emit).) To use this functionality, your application should target the .NET Framework 3.5 or later. - +> Starting with the .NET Framework 2.0 Service Pack 1, this member no longer requires with the flag. (See [Security Issues in Reflection Emit](/dotnet/framework/reflection-and-codedom/security-issues-in-reflection-emit).) To use this functionality, your application should target the .NET Framework 3.5 or later. + ]]> is . - This method is called on a dynamic module that is not a debug module. - - -or- - + This method is called on a dynamic module that is not a debug module. + + -or- + is not contained in this dynamic module. @@ -5424,11 +5424,11 @@ System.Void - - - - - + + + + + Reserved for future use. Must be IID_NULL. @@ -5438,13 +5438,13 @@ Caller-allocated array which receives the IDs corresponding to the names. For a description of this member, see . - 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. + ]]> The method is called late-bound using the COM IDispatch interface. @@ -5477,9 +5477,9 @@ System.Void - - - + + + The type information to return. @@ -5487,13 +5487,13 @@ A pointer to the requested type information object. For a description of this member, see . - 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. + ]]> The method is called late-bound using the COM IDispatch interface. @@ -5526,19 +5526,19 @@ System.Void - + The location that receives the number of type information interfaces provided by the object. For a description of this member, see . - 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. + ]]> The method is called late-bound using the COM IDispatch interface. @@ -5571,14 +5571,14 @@ System.Void - - - - - - - - + + + + + + + + The member ID. @@ -5591,13 +5591,13 @@ The index of the first argument that has an error. For a description of this member, see . - 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. + ]]> The method is called late-bound using the COM IDispatch interface. diff --git a/xml/System.Reflection.Emit/ParameterBuilder.xml b/xml/System.Reflection.Emit/ParameterBuilder.xml index 20ce24e87d0..0d87773c281 100644 --- a/xml/System.Reflection.Emit/ParameterBuilder.xml +++ b/xml/System.Reflection.Emit/ParameterBuilder.xml @@ -77,22 +77,22 @@ Creates or associates parameter information. - attributes require that you call with viable parameters in order for the Microsoft intermediate language (MSIL) to work correctly at runtime. For example, if you define a with ParameterAttributes.Out for parameter 1 of a `MethodBuilder`, then parameter 1 of must be a reference such as Type.GetType("System.String&"), rather than Type.GetType("System.String"). - - - -## Examples - The following example demonstrates how to create a dynamic method with a parameter passed by reference using `ParameterBuilder`. - + attributes require that you call with viable parameters in order for the Microsoft intermediate language (MSIL) to work correctly at runtime. For example, if you define a with ParameterAttributes.Out for parameter 1 of a `MethodBuilder`, then parameter 1 of must be a reference such as Type.GetType("System.String&"), rather than Type.GetType("System.String"). + + + +## Examples + The following example demonstrates how to create a dynamic method with a parameter passed by reference using `ParameterBuilder`. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Reflection.Emit.ParameterBuilder Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/ParameterBuilder/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Reflection.Emit.ParameterBuilder Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Reflection.Emit.ParameterBuilder Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -159,11 +159,11 @@ Retrieves the attributes for this parameter. Read-only. Retrieves the attributes for this parameter. - enumeration. - + enumeration. + ]]> @@ -237,11 +237,11 @@ Retrieves whether this is an input parameter. Read-only. Retrieves whether this is an input parameter. - @@ -455,21 +455,21 @@ The default value of this parameter. Sets the default value of the parameter. - . This is not CLS-compliant, but it can be useful in interop scenarios. - + . This is not CLS-compliant, but it can be useful in interop scenarios. + ]]> - The parameter is not one of the supported types. - - -or- - - The type of does not match the type of the parameter. - - -or- - + The parameter is not one of the supported types. + + -or- + + The type of does not match the type of the parameter. + + -or- + The parameter is of type or other reference type, is not , and the value cannot be assigned to the reference type. @@ -595,12 +595,12 @@ A byte blob representing the attributes. Set a custom attribute using a specified custom attribute blob. - @@ -687,19 +687,19 @@ For information on how to format `binaryAttribute`, see the metadata specificati System.Void - + The marshaling information for this parameter. Specifies the marshaling for this parameter. - if the containing type has been created using TypeBuilder.CreateType(). - + if the containing type has been created using TypeBuilder.CreateType(). + ]]> @@ -733,11 +733,11 @@ For information on how to format `binaryAttribute`, see the metadata specificati System.Void - - - - - + + + + + Reserved for future use. Must be IID_NULL. @@ -747,11 +747,11 @@ For information on how to format `binaryAttribute`, see the metadata specificati Caller-allocated array which receives the IDs corresponding to the names. Maps a set of names to a corresponding set of dispatch identifiers. - The method is called late-bound using the COM IDispatch interface. @@ -784,9 +784,9 @@ For information on how to format `binaryAttribute`, see the metadata specificati System.Void - - - + + + The type information to return. @@ -794,11 +794,11 @@ For information on how to format `binaryAttribute`, see the metadata specificati Receives a pointer to the requested type information object. Retrieves the type information for an object, which can then be used to get the type information for an interface. - The method is called late-bound using the COM IDispatch interface. @@ -831,17 +831,17 @@ For information on how to format `binaryAttribute`, see the metadata specificati System.Void - + Points to a location that receives the number of type information interfaces provided by the object. Retrieves the number of type information interfaces that an object provides (either 0 or 1). - The method is called late-bound using the COM IDispatch interface. @@ -874,14 +874,14 @@ For information on how to format `binaryAttribute`, see the metadata specificati System.Void - - - - - - - - + + + + + + + + Identifies the member. @@ -894,11 +894,11 @@ For information on how to format `binaryAttribute`, see the metadata specificati The index of the first argument that has an error. Provides access to properties and methods exposed by an object. - The method is called late-bound using the COM IDispatch interface. diff --git a/xml/System.Reflection.Emit/ParameterToken.xml b/xml/System.Reflection.Emit/ParameterToken.xml index 42b353fc858..2b093dbb083 100644 --- a/xml/System.Reflection.Emit/ParameterToken.xml +++ b/xml/System.Reflection.Emit/ParameterToken.xml @@ -125,7 +125,7 @@ System.Boolean - + The to compare to the current instance. @@ -184,8 +184,8 @@ System.Boolean - - + + The to compare to . @@ -219,8 +219,8 @@ System.Boolean - - + + The to compare to . diff --git a/xml/System.Reflection.Emit/PropertyBuilder.xml b/xml/System.Reflection.Emit/PropertyBuilder.xml index 61590562806..618cb3265b4 100644 --- a/xml/System.Reflection.Emit/PropertyBuilder.xml +++ b/xml/System.Reflection.Emit/PropertyBuilder.xml @@ -77,30 +77,30 @@ Defines the properties for a type. - to create the property framework and an associated to implement the IL logic within the property. - + to create the property framework and an associated to implement the IL logic within the property. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Reflection.Emit.PropertyBuilder Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/PropertyBuilder/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Reflection.Emit.PropertyBuilder Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Reflection.Emit.PropertyBuilder Example/VB/source.vb" id="Snippet1"::: + ]]> - - - - - + + + + + Constructor mscorlib @@ -283,11 +283,11 @@ if this property can be read; otherwise, . - @@ -331,11 +331,11 @@ if this property can be written to; otherwise, . - @@ -432,11 +432,11 @@ Returns an array of the public and non-public and accessors on this property. An array of type containing the matching public or non-public accessors, or an empty array if matching accessors do not exist on this property. - This method is not supported. @@ -493,11 +493,11 @@ Returns an array of all the custom attributes for this property. An array of all the custom attributes. - This method is not supported. @@ -546,11 +546,11 @@ Returns an array of custom attributes identified by . An array of custom attributes defined on this reflected member, or if no attributes are defined on this member. - This method is not supported. @@ -604,11 +604,11 @@ Returns the public and non-public get accessor for this property. A object representing the get accessor for this property, if is . Returns if is and the get accessor is non-public, or if is but no get accessors exist. - @@ -652,11 +652,11 @@ Returns an array of all the index parameters for the property. An array of type containing the parameters for the indexes. - This method is not supported. @@ -708,31 +708,31 @@ Indicates whether the accessor should be returned if it is non-public. if non-public methods are to be included; otherwise, . Returns the set accessor for this property. - The property's method, or , as shown in the following table. - - Value - - Condition - - A object representing the Set method for this property. - - The set accessor is public. - - is true and non-public methods can be returned. - - null - - is true, but the property is read-only. - - is false and the set accessor is non-public. - + The property's method, or , as shown in the following table. + + Value + + Condition + + A object representing the Set method for this property. + + The set accessor is public. + + is true and non-public methods can be returned. + + null + + is true, but the property is read-only. + + is false and the set accessor is non-public. + - @@ -798,11 +798,11 @@ Gets the value of the indexed property by calling the property's getter method. The value of the specified indexed property. - This method is not supported. @@ -864,11 +864,11 @@ Gets the value of a property having the specified binding, index, and . The property value for . - This method is not supported. @@ -918,11 +918,11 @@ if one or more instance of is defined on this property; otherwise . - This method is not supported. @@ -964,11 +964,11 @@ Gets the module in which the type that declares the current property is being defined. The in which the type that declares the current property is defined. - property to get the type in which the property is declared, and then calling the property of the resulting object. - + property to get the type in which the property is declared, and then calling the property of the resulting object. + ]]> @@ -1186,23 +1186,23 @@ The default value of this property. Sets the default value of this property. - . This is not CLS-compliant, but it can be useful in interop scenarios. - + . This is not CLS-compliant, but it can be useful in interop scenarios. + ]]> has been called on the enclosing type. - The property is not one of the supported types. - - -or- - - The type of does not match the type of the property. - - -or- - + The property is not one of the supported types. + + -or- + + The type of does not match the type of the property. + + -or- + The property is of type or other reference type, is not , and the value cannot be assigned to the reference type. @@ -1358,12 +1358,12 @@ A byte blob representing the attributes. Set a custom attribute using a specified custom attribute blob. - @@ -1465,15 +1465,15 @@ For information on how to format `binaryAttribute`, see the metadata specificati A object that represents the method that gets the property value. Sets the method that gets the property value. - @@ -1560,15 +1560,15 @@ For information on how to format `binaryAttribute`, see the metadata specificati A object that represents the method that sets the property value. Sets the method that sets the property value. - @@ -1670,11 +1670,11 @@ For information on how to format `binaryAttribute`, see the metadata specificati Optional index values for indexed properties. This value should be for non-indexed properties. Sets the value of the property with optional index values for index properties. - or , retrieve the object from the type, and call . - + or , retrieve the object from the type, and call . + ]]> This method is not supported. @@ -1737,11 +1737,11 @@ For information on how to format `binaryAttribute`, see the metadata specificati The object that represents the culture for which the resource is to be localized. Note that if the resource is not localized for this culture, the method will be called successively in search of a match. If this value is , the is obtained from the property. Sets the property value for the given object to the given value. - or , retrieve the object from the type, and call . - + or , retrieve the object from the type, and call . + ]]> This method is not supported. @@ -1774,11 +1774,11 @@ For information on how to format `binaryAttribute`, see the metadata specificati System.Void - - - - - + + + + + Reserved for future use. Must be IID_NULL. @@ -1788,11 +1788,11 @@ For information on how to format `binaryAttribute`, see the metadata specificati Caller-allocated array which receives the IDs corresponding to the names. Maps a set of names to a corresponding set of dispatch identifiers. - The method is called late-bound using the COM IDispatch interface. @@ -1825,9 +1825,9 @@ For information on how to format `binaryAttribute`, see the metadata specificati System.Void - - - + + + The type information to return. @@ -1835,11 +1835,11 @@ For information on how to format `binaryAttribute`, see the metadata specificati Receives a pointer to the requested type information object. Retrieves the type information for an object, which can then be used to get the type information for an interface. - The method is called late-bound using the COM IDispatch interface. @@ -1872,17 +1872,17 @@ For information on how to format `binaryAttribute`, see the metadata specificati System.Void - + Points to a location that receives the number of type information interfaces provided by the object. Retrieves the number of type information interfaces that an object provides (either 0 or 1). - The method is called late-bound using the COM IDispatch interface. @@ -1915,14 +1915,14 @@ For information on how to format `binaryAttribute`, see the metadata specificati System.Void - - - - - - - - + + + + + + + + Identifies the member. @@ -1935,11 +1935,11 @@ For information on how to format `binaryAttribute`, see the metadata specificati The index of the first argument that has an error. Provides access to properties and methods exposed by an object. - The method is called late-bound using the COM IDispatch interface. diff --git a/xml/System.Reflection.Emit/PropertyToken.xml b/xml/System.Reflection.Emit/PropertyToken.xml index d66dfd97995..9bccef5812d 100644 --- a/xml/System.Reflection.Emit/PropertyToken.xml +++ b/xml/System.Reflection.Emit/PropertyToken.xml @@ -125,7 +125,7 @@ System.Boolean - + The to compare to the current instance. @@ -184,8 +184,8 @@ System.Boolean - - + + The to compare to . @@ -219,8 +219,8 @@ System.Boolean - - + + The to compare to . diff --git a/xml/System.Reflection.Emit/SignatureHelper.xml b/xml/System.Reflection.Emit/SignatureHelper.xml index 208455ce17d..4e1c6a1f4ef 100644 --- a/xml/System.Reflection.Emit/SignatureHelper.xml +++ b/xml/System.Reflection.Emit/SignatureHelper.xml @@ -73,13 +73,13 @@ Provides methods for building signatures. - class to create a signature blob that can be passed to the method of the class. A object can also be passed to the method overload to insert an instruction and a signature token into a Microsoft intermediate language (MSIL) stream. For information on signature blobs and signature metadata, see the ECMA Partition II Metadata documentation. - -For more information, see [ECMA 335 Common Language Infrastructure (CLI)](https://www.ecma-international.org/publications-and-standards/standards/ecma-335/). - + class to create a signature blob that can be passed to the method of the class. A object can also be passed to the method overload to insert an instruction and a signature token into a Microsoft intermediate language (MSIL) stream. For information on signature blobs and signature metadata, see the ECMA Partition II Metadata documentation. + +For more information, see [ECMA 335 Common Language Infrastructure (CLI)](https://www.ecma-international.org/publications-and-standards/standards/ecma-335/). + ]]> @@ -135,11 +135,11 @@ For more information, see [ECMA 335 Common Language Infrastructure (CLI)](https: The type of the argument. Adds an argument to the signature. - method overload. - + method overload. + ]]> The signature has already been finished. @@ -196,11 +196,11 @@ For more information, see [ECMA 335 Common Language Infrastructure (CLI)](https: if the argument is pinned; otherwise, . Adds an argument of the specified type to the signature, specifying whether the argument is pinned. - method overload. - + method overload. + ]]> @@ -272,27 +272,27 @@ For more information, see [ECMA 335 Common Language Infrastructure (CLI)](https: An array of types representing the optional custom modifiers for the argument, such as or . If the argument has no optional custom modifiers, specify . Adds an argument to the signature, with the specified custom modifiers. - namespace for classes that represent custom modifiers. - + namespace for classes that represent custom modifiers. + ]]> - is . - - -or- - + is . + + -or- + An element of or is . - The signature has already been finished. - - -or- - - One of the specified custom modifiers is an array type. - - -or- - + The signature has already been finished. + + -or- + + One of the specified custom modifiers is an array type. + + -or- + One of the specified custom modifiers is an open generic type. That is, the property is for the custom modifier. @@ -362,32 +362,32 @@ For more information, see [ECMA 335 Common Language Infrastructure (CLI)](https: An array of arrays of types. Each array of types represents the optional custom modifiers for the corresponding argument, such as or . If a particular argument has no optional custom modifiers, specify instead of an array of types. If none of the arguments have optional custom modifiers, specify instead of an array of arrays. Adds a set of arguments to the signature, with the specified custom modifiers. - namespace for classes that represent custom modifiers. - + namespace for classes that represent custom modifiers. + ]]> - An element of is . - - -or- - + An element of is . + + -or- + One of the specified custom modifiers is . (However, can be specified for the array of custom modifiers for any argument.) - The signature has already been finished. - - -or- - - One of the specified custom modifiers is an array type. - - -or- - - One of the specified custom modifiers is an open generic type. That is, the property is for the custom modifier. - - -or- - + The signature has already been finished. + + -or- + + One of the specified custom modifiers is an array type. + + -or- + + One of the specified custom modifiers is an open generic type. That is, the property is for the custom modifier. + + -or- + The size of or does not equal the size of . @@ -574,11 +574,11 @@ For more information, see [ECMA 335 Common Language Infrastructure (CLI)](https: Creates and returns a hash code for this instance. The hash code based on the name. - @@ -772,8 +772,8 @@ For more information, see [ECMA 335 Common Language Infrastructure (CLI)](https: System.Reflection.Emit.SignatureHelper - - + + The unmanaged calling convention of the method. @@ -879,9 +879,9 @@ For more information, see [ECMA 335 Common Language Infrastructure (CLI)](https: System.Reflection.Emit.SignatureHelper - - - + + + The that contains the method for which the is requested. @@ -893,10 +893,10 @@ For more information, see [ECMA 335 Common Language Infrastructure (CLI)](https: is . - is not a . - - -or- - + is not a . + + -or- + is an unknown unmanaged calling convention. @@ -964,20 +964,20 @@ For more information, see [ECMA 335 Common Language Infrastructure (CLI)](https: Returns a signature helper for a method with a standard calling convention, given the method's module, return type, and argument types. The object for a method. - method overload and then use the or method overloads to add arguments with custom modifiers. - + method overload and then use the or method overloads to add arguments with custom modifiers. + ]]> - is . - - -or- - + is . + + -or- + An element of is . is not a . @@ -1053,18 +1053,18 @@ For more information, see [ECMA 335 Common Language Infrastructure (CLI)](https: Returns a signature helper for a property, given the dynamic module that contains the property, the property type, and the property arguments. A object for a property. - method overload. - + method overload. + ]]> - is . - - -or- - + is . + + -or- + An element of is . is not a . @@ -1169,41 +1169,41 @@ For more information, see [ECMA 335 Common Language Infrastructure (CLI)](https: Returns a signature helper for a property, given the dynamic module that contains the property, the property type, the property arguments, and custom modifiers for the return type and arguments. A object for a property. - namespace for classes that represent custom modifiers. - - If a property has no custom modifiers, use the method overload. - + namespace for classes that represent custom modifiers. + + If a property has no custom modifiers, use the method overload. + ]]> - is . - - -or- - - An element of is . - - -or- - + is . + + -or- + + An element of is . + + -or- + One of the specified custom modifiers is . (However, can be specified for the array of custom modifiers for any argument.) - The signature has already been finished. - - -or- - - is not a . - - -or- - - One of the specified custom modifiers is an array type. - - -or- - - One of the specified custom modifiers is an open generic type. That is, the property is for the custom modifier. - - -or- - + The signature has already been finished. + + -or- + + is not a . + + -or- + + One of the specified custom modifiers is an array type. + + -or- + + One of the specified custom modifiers is an open generic type. That is, the property is for the custom modifier. + + -or- + The size of or does not equal the size of . @@ -1308,44 +1308,44 @@ For more information, see [ECMA 335 Common Language Infrastructure (CLI)](https: Returns a signature helper for a property, given the dynamic module that contains the property, the calling convention, the property type, the property arguments, and custom modifiers for the return type and arguments. A object for a property. - namespace for classes that represent custom modifiers. - - If a property has no custom modifiers, use the method overload. - + namespace for classes that represent custom modifiers. + + If a property has no custom modifiers, use the method overload. + > [!NOTE] -> This method overload is introduced in the .NET Framework 3.5 or later. - +> This method overload is introduced in the .NET Framework 3.5 or later. + ]]> - is . - - -or- - - An element of is . - - -or- - + is . + + -or- + + An element of is . + + -or- + One of the specified custom modifiers is . (However, can be specified for the array of custom modifiers for any argument.) - The signature has already been finished. - - -or- - - is not a . - - -or- - - One of the specified custom modifiers is an array type. - - -or- - - One of the specified custom modifiers is an open generic type. That is, the property is for the custom modifier. - - -or- - + The signature has already been finished. + + -or- + + is not a . + + -or- + + One of the specified custom modifiers is an array type. + + -or- + + One of the specified custom modifiers is an open generic type. That is, the property is for the custom modifier. + + -or- + The size of or does not equal the size of . @@ -1417,11 +1417,11 @@ For more information, see [ECMA 335 Common Language Infrastructure (CLI)](https: System.Void - - - - - + + + + + Reserved for future use. Must be IID_NULL. @@ -1431,11 +1431,11 @@ For more information, see [ECMA 335 Common Language Infrastructure (CLI)](https: Caller-allocated array which receives the IDs corresponding to the names. Maps a set of names to a corresponding set of dispatch identifiers. - Late-bound access using the COM IDispatch interface is not supported. @@ -1468,9 +1468,9 @@ For more information, see [ECMA 335 Common Language Infrastructure (CLI)](https: System.Void - - - + + + The type information to return. @@ -1478,11 +1478,11 @@ For more information, see [ECMA 335 Common Language Infrastructure (CLI)](https: Receives a pointer to the requested type information object. Retrieves the type information for an object, which can then be used to get the type information for an interface. - Late-bound access using the COM IDispatch interface is not supported. @@ -1515,17 +1515,17 @@ For more information, see [ECMA 335 Common Language Infrastructure (CLI)](https: System.Void - + Points to a location that receives the number of type information interfaces provided by the object. Retrieves the number of type information interfaces that an object provides (either 0 or 1). - Late-bound access using the COM IDispatch interface is not supported. @@ -1558,14 +1558,14 @@ For more information, see [ECMA 335 Common Language Infrastructure (CLI)](https: System.Void - - - - - - - - + + + + + + + + Identifies the member. @@ -1578,11 +1578,11 @@ For more information, see [ECMA 335 Common Language Infrastructure (CLI)](https: The index of the first argument that has an error. Provides access to properties and methods exposed by an object. - Late-bound access using the COM IDispatch interface is not supported. diff --git a/xml/System.Reflection.Emit/SignatureToken.xml b/xml/System.Reflection.Emit/SignatureToken.xml index 408062e7b44..c30f25b2e49 100644 --- a/xml/System.Reflection.Emit/SignatureToken.xml +++ b/xml/System.Reflection.Emit/SignatureToken.xml @@ -126,7 +126,7 @@ System.Boolean - + The to compare to the current instance. @@ -185,8 +185,8 @@ System.Boolean - - + + The to compare to . @@ -220,8 +220,8 @@ System.Boolean - - + + The to compare to . @@ -259,11 +259,11 @@ Retrieves the metadata token for the local variable signature for this method. Read-only. Retrieves the metadata token of this signature. - diff --git a/xml/System.Reflection.Emit/StringToken.xml b/xml/System.Reflection.Emit/StringToken.xml index 79479b7e930..b56d7d155e6 100644 --- a/xml/System.Reflection.Emit/StringToken.xml +++ b/xml/System.Reflection.Emit/StringToken.xml @@ -99,7 +99,7 @@ System.Boolean - + The to compare to the current instance. @@ -158,8 +158,8 @@ System.Boolean - - + + The to compare to . @@ -193,8 +193,8 @@ System.Boolean - - + + The to compare to . diff --git a/xml/System.Reflection.Emit/TypeBuilder.xml b/xml/System.Reflection.Emit/TypeBuilder.xml index d04180e094d..09a915dc470 100644 --- a/xml/System.Reflection.Emit/TypeBuilder.xml +++ b/xml/System.Reflection.Emit/TypeBuilder.xml @@ -107,11 +107,11 @@ The following code sample demonstrates how to build a type dynamically by using - - - - - + + + + + Constructor mscorlib @@ -161,8 +161,8 @@ The following code sample demonstrates how to build a type dynamically by using System.Void - - + + The security action to be taken such as Demand, Assert, and so on. @@ -6537,7 +6537,7 @@ See for a description of the format of the System.Boolean - + [System.Diagnostics.CodeAnalysis.NotNullWhen(true)] @@ -8598,11 +8598,11 @@ For more information on how to format `binaryAttribute`, see [ECMA C# and Common System.Void - - - - - + + + + + Reserved for future use. Must be IID_NULL. @@ -8649,9 +8649,9 @@ For more information on how to format `binaryAttribute`, see [ECMA C# and Common System.Void - - - + + + The type information to return. @@ -8696,7 +8696,7 @@ For more information on how to format `binaryAttribute`, see [ECMA C# and Common System.Void - + Points to a location that receives the number of type information interfaces provided by the object. @@ -8739,14 +8739,14 @@ For more information on how to format `binaryAttribute`, see [ECMA C# and Common System.Void - - - - - - - - + + + + + + + + Identifies the member. diff --git a/xml/System.Reflection.Emit/TypeToken.xml b/xml/System.Reflection.Emit/TypeToken.xml index f7b32d051de..7b9ac9e4556 100644 --- a/xml/System.Reflection.Emit/TypeToken.xml +++ b/xml/System.Reflection.Emit/TypeToken.xml @@ -34,11 +34,11 @@ Represents the returned by the metadata to represent a type. - @@ -132,7 +132,7 @@ System.Boolean - + The to compare to the current instance. @@ -191,8 +191,8 @@ System.Boolean - - + + The to compare to . @@ -226,8 +226,8 @@ System.Boolean - - + + The to compare to . diff --git a/xml/System.Reflection/Assembly.xml b/xml/System.Reflection/Assembly.xml index a38ffe376b1..f61ae5680c7 100644 --- a/xml/System.Reflection/Assembly.xml +++ b/xml/System.Reflection/Assembly.xml @@ -166,11 +166,11 @@ - - - - - + + + + + Constructor mscorlib @@ -359,7 +359,7 @@ In .NET 5 and later versions, for bundled assemblies, this property throws an ex System.Object - + The of the type to locate. @@ -461,8 +461,8 @@ In .NET 5 and later versions, for bundled assemblies, this property throws an ex System.Object - - + + The of the type to locate. @@ -566,7 +566,7 @@ In .NET 5 and later versions, for bundled assemblies, this property throws an ex System.Object - + [System.Runtime.CompilerServices.Nullable(1)] @@ -574,10 +574,10 @@ In .NET 5 and later versions, for bundled assemblies, this property throws an ex - - - - + + + + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 2, 1 })] @@ -585,8 +585,8 @@ In .NET 5 and later versions, for bundled assemblies, this property throws an ex - - + + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 2, 1 })] @@ -676,8 +676,8 @@ In .NET 5 and later versions, for bundled assemblies, this property throws an ex System.String - - + + The display name of an assembly. @@ -1211,7 +1211,7 @@ In .NET 5 and later versions, for bundled assemblies, this property throws an ex System.Reflection.Assembly - + An object representing a type in the assembly that will be returned. @@ -1368,7 +1368,7 @@ In .NET 5 and later versions, for bundled assemblies, this property throws an ex System.Object[] - + This argument is ignored for objects of type . @@ -1446,8 +1446,8 @@ In .NET 5 and later versions, for bundled assemblies, this property throws an ex System.Object[] - - + + The type for which the custom attributes are to be returned. @@ -1788,7 +1788,7 @@ In .NET 5 and later versions, for bundled assemblies, this property throws an ex System.IO.FileStream - + The name of the specified file. Do not include the path to the file. @@ -1937,7 +1937,7 @@ In .NET 5 and later versions, for bundled assemblies, this method throws an exce System.IO.FileStream[] - + @@ -2153,7 +2153,7 @@ In .NET 5 and later versions, for bundled assemblies, this method throws an exce System.Reflection.Module[] - + @@ -2430,8 +2430,8 @@ Note: In .NET for Win System.IO.Stream - - + + The type whose namespace is used to scope the manifest resource name. @@ -2511,7 +2511,7 @@ Note: In .NET for Win System.Reflection.Module - + The name of the module being requested. @@ -2661,7 +2661,7 @@ Note: In .NET for Win System.Reflection.Module[] - + @@ -2783,7 +2783,7 @@ Note: In .NET for Win System.Reflection.AssemblyName - + @@ -2849,8 +2849,8 @@ Note: In .NET for Win System.Void - - + + The object to be populated with serialization information. @@ -2988,7 +2988,7 @@ Note: In .NET for Win System.Reflection.Assembly - + The specified culture. @@ -3055,8 +3055,8 @@ Note: In .NET for Win System.Reflection.Assembly - - + + [System.Runtime.CompilerServices.Nullable(2)] @@ -3287,8 +3287,8 @@ Note: In .NET for Win System.Type - - + + The full name of the type. @@ -3564,7 +3564,7 @@ Note: In .NET for Win Gets a value indicating whether the assembly was loaded from the global assembly cache (.NET Framework only). .NET Framework only: if the assembly was loaded from the global assembly cache; otherwise, . - + .NET Core and .NET 5 and later: in all cases. System.Boolean - - + + The type of the attribute to be checked for this assembly. @@ -3959,7 +3959,7 @@ This property is marked obsolete starting in .NET 5, and generates a compile-tim System.Reflection.Assembly - + A byte array that is a COFF-based image containing an emitted assembly. @@ -4122,7 +4122,7 @@ Note: In .NET for Win System.Reflection.Assembly - + The long or short form of the assembly name. @@ -4216,8 +4216,8 @@ To load the correct assembly, it's recommended to call the `Load` method by pass System.Reflection.Assembly - - + + [System.Runtime.CompilerServices.Nullable(2)] @@ -4286,8 +4286,8 @@ To load the correct assembly, it's recommended to call the `Load` method by pass System.Reflection.Assembly - - + + The object that describes the assembly to be loaded. @@ -4373,8 +4373,8 @@ To load the correct assembly, it's recommended to call the `Load` method by pass System.Reflection.Assembly - - + + The display name of the assembly. @@ -4456,9 +4456,9 @@ To load the correct assembly, it's recommended to call the `Load` method by pass System.Reflection.Assembly - - - + + + A byte array that is a COFF-based image containing an emitted assembly. @@ -4530,9 +4530,9 @@ The assembly is loaded using the supplied evidence. The raw bytes representing t System.Reflection.Assembly - - - + + + A byte array that is a COFF-based image containing an emitted assembly. @@ -4614,7 +4614,7 @@ The assembly is loaded using the supplied evidence. The raw bytes representing t System.Reflection.Assembly - + The fully qualified path of the file to load. @@ -4680,8 +4680,8 @@ The ability to execute code in remote assemblies is disabled. See - + + The fully qualified path of the assembly file. @@ -4784,7 +4784,7 @@ Starting with .NET Framework 4, the ability to execute code in assemblies loaded System.Reflection.Assembly - + The name or path of the file that contains the manifest of the assembly. @@ -4896,8 +4896,8 @@ The ability to execute code in remote assemblies is disabled. See - + + The name or path of the file that contains the manifest of the assembly. @@ -5024,8 +5024,8 @@ The ability to execute code in remote assemblies is disabled. See - + + [System.Runtime.CompilerServices.Nullable(2)] @@ -5033,7 +5033,7 @@ The ability to execute code in remote assemblies is disabled. See + The name or path of the file that contains the manifest of the assembly. @@ -5136,10 +5136,10 @@ The ability to execute code in remote assemblies is disabled. See - - - + + + + The name or path of the file that contains the manifest of the assembly. @@ -5281,8 +5281,8 @@ The ability to execute code in remote assemblies is disabled. See - + + [System.Runtime.CompilerServices.Nullable(2)] @@ -5356,8 +5356,8 @@ The ability to execute code in remote assemblies is disabled. See - + + [System.Runtime.CompilerServices.Nullable(2)] @@ -5365,7 +5365,7 @@ The ability to execute code in remote assemblies is disabled. See + [System.Runtime.CompilerServices.Nullable(2)] @@ -5467,7 +5467,7 @@ The ability to execute code in remote assemblies is disabled. See + The display name of the assembly. @@ -5532,8 +5532,8 @@ The ability to execute code in remote assemblies is disabled. See - + + The display name of the assembly. @@ -5852,8 +5852,8 @@ In .NET 5 and later versions, for bundled assemblies, the value returned is an e System.Boolean - - + + The assembly to compare to . @@ -5907,8 +5907,8 @@ In .NET 5 and later versions, for bundled assemblies, the value returned is an e System.Boolean - - + + The assembly to compare to . @@ -6079,7 +6079,7 @@ In .NET 5 and later versions, for bundled assemblies, the value returned is an e System.Reflection.Assembly - + A byte array that is a COFF-based image containing an emitted assembly. @@ -6156,7 +6156,7 @@ In .NET 5 and later versions, for bundled assemblies, the value returned is an e System.Reflection.Assembly - + The display name of the assembly, as returned by the property. @@ -6239,7 +6239,7 @@ In .NET 5 and later versions, for bundled assemblies, the value returned is an e System.Reflection.Assembly - + The path of the file that contains the manifest of the assembly. @@ -6576,7 +6576,7 @@ In .NET 5 and later versions, for bundled assemblies, the value returned is an e System.Reflection.Assembly - + The name or path of the file that contains the manifest of the assembly. diff --git a/xml/System.Reflection/AssemblyFlagsAttribute.xml b/xml/System.Reflection/AssemblyFlagsAttribute.xml index 67df42d907d..ab1f7edcbbc 100644 --- a/xml/System.Reflection/AssemblyFlagsAttribute.xml +++ b/xml/System.Reflection/AssemblyFlagsAttribute.xml @@ -61,24 +61,24 @@ Specifies a bitwise combination of flags for an assembly, describing just-in-time (JIT) compiler options, whether the assembly is retargetable, and whether it has a full or tokenized public key. This class cannot be inherited. - enumeration describes the assembly characteristics that can be set using this attribute. - - To access the flags that have been specified for an assembly, use the property to obtain an object, then use the property to obtain an value. - - To specify flags for a dynamic assembly, set the property of the object that you pass to the method. - - - -## Examples - The following code example shows how to apply the to an assembly, and how to read the flags at run time. The example also creates an instance of the attribute, and uses the property to display the flags. For an example of how to apply the to a dynamic assembly, see the property. - + enumeration describes the assembly characteristics that can be set using this attribute. + + To access the flags that have been specified for an assembly, use the property to obtain an object, then use the property to obtain an value. + + To specify flags for a dynamic assembly, set the property of the object that you pass to the method. + + + +## Examples + The following code example shows how to apply the to an assembly, and how to read the flags at run time. The example also creates an instance of the attribute, and uses the property to display the flags. For an example of how to apply the to a dynamic assembly, see the property. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/AssemblyFlagsAttribute/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/AssemblyFlagsAttribute/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/AssemblyFlagsAttribute/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/AssemblyFlagsAttribute/VB/source.vb" id="Snippet1"::: + ]]> @@ -142,17 +142,17 @@ - + A bitwise combination of flags, cast as an integer value, representing just-in-time (JIT) compiler options, longevity, whether an assembly is retargetable, and whether it has a full or tokenized public key. Initializes a new instance of the class with the specified combination of flags, cast as an integer value. - @@ -198,15 +198,15 @@ A bitwise combination of flags representing just-in-time (JIT) compiler options, longevity, whether an assembly is retargetable, and whether it has a full or tokenized public key. Initializes a new instance of the class with the specified combination of flags. - to an assembly, and how to read the flags at run time. The example also creates an instance of the attribute, and uses the property to display the flags. For an example of how to apply the to a dynamic assembly, see the property. - + to an assembly, and how to read the flags at run time. The example also creates an instance of the attribute, and uses the property to display the flags. For an example of how to apply the to a dynamic assembly, see the property. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/AssemblyFlagsAttribute/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/AssemblyFlagsAttribute/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/AssemblyFlagsAttribute/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/AssemblyFlagsAttribute/VB/source.vb" id="Snippet1"::: + ]]> @@ -262,17 +262,17 @@ - + A bitwise combination of flags, cast as an unsigned integer value, representing just-in-time (JIT) compiler options, longevity, whether an assembly is retargetable, and whether it has a full or tokenized public key. Initializes a new instance of the class with the specified combination of flags, cast as an unsigned integer value. - @@ -320,20 +320,20 @@ Gets an integer value representing the combination of flags specified when this attribute instance was created. An integer value representing a bitwise combination of flags. - type before using it. - - - -## Examples - The following code example shows how to apply the to an assembly, and how to read the flags at run time. The example also creates an instance of the attribute, and uses the property to display the flags. For an example of how to apply the to a dynamic assembly, see the property. - + type before using it. + + + +## Examples + The following code example shows how to apply the to an assembly, and how to read the flags at run time. The example also creates an instance of the attribute, and uses the property to display the flags. For an example of how to apply the to a dynamic assembly, see the property. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/AssemblyFlagsAttribute/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/AssemblyFlagsAttribute/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/AssemblyFlagsAttribute/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/AssemblyFlagsAttribute/VB/source.vb" id="Snippet1"::: + ]]> @@ -395,11 +395,11 @@ Gets an unsigned integer value representing the combination of flags specified when this attribute instance was created. An unsigned integer value representing a bitwise combination of flags. - type before using it. - + type before using it. + ]]> diff --git a/xml/System.Reflection/AssemblyName.xml b/xml/System.Reflection/AssemblyName.xml index 4ad71afde0f..219eb7ef8fb 100644 --- a/xml/System.Reflection/AssemblyName.xml +++ b/xml/System.Reflection/AssemblyName.xml @@ -107,92 +107,92 @@ Describes an assembly's unique identity in full. - object contains information about an assembly, which you can use to bind to that assembly. An assembly's identity consists of the following: - -- Simple name. - -- Version number. - -- Cryptographic key pair. - -- Supported culture. - - The simple name is typically the file name for the manifest file without its extension. The key pair includes a public and private key, used to create strong-name signatures for assemblies. - - All compilers that support the common language runtime will emit the simple name of a nested class, and reflection constructs a mangled name when queried, in accordance with the following conventions. - -|Delimiter|Meaning| -|---------------|-------------| -|Backslash (\\)|Escape character.| -|Comma (,)|Precedes the assembly name.| -|Plus sign (+)|Precedes a nested class.| - - For example, the fully qualified name for a class might look like this: - - ContainingClass+NestedClass,MyAssembly - - A "++" becomes "\\+\\+", and a "\\" becomes "\\\\". - - This qualified name can be persisted and later used to load the . To search for and load a , use either with the type name only or with the assembly qualified type name. with the type name only will look for the in the caller's assembly and then in the System assembly. with the assembly qualified type name will look for the in any assembly. - - A fully specified must have the name, culture, public key or public key token, major version, minor version, build number, and revision number parameters. The last four are packaged in the type. - - To create a simple name, create an object using the parameterless constructor and set the . The other properties are optional. - - To create a full strong name, create an object using the parameterless constructor and set the and . The other properties are optional. Use and to set the public key and the strong name. The strong name signing always uses the hash algorithm. - - To ensure that the names are constructed correctly, use the following properties: - -- - -- - -- - - You can also get the name by using the `/l` option with the [Gacutil.exe (Global Assembly Cache Tool)](/dotnet/framework/tools/gacutil-exe-gac-tool) - - For a partially specified strong name, create an object using the parameterless constructor and set the name and public key. An assembly created using such an can be signed later using the Assembly Linker (Al.exe). - - It is possible to specify a public key and a with inconsistent values. This can be useful in developer scenarios. In this case, the public key retrieved with specifies the correct public key, while the specifies the public and private keys used during development. When the runtime detects a mismatch between the and the public key, it looks up in the registry the correct key that matches the public key. - - The format of the display name of an is a comma-delimited Unicode string that begins with the name, as follows: - - `Name <,Culture = CultureInfo> <,Version = Major.Minor.Build.Revision> <, StrongName> <,PublicKeyToken> '\0'` - - `Name` is the textual name of the assembly. `CultureInfo` is the RFC1766-format-defined culture. `Major`, `Minor`, `Build`, and `Revision` are the major version, minor version, build number, and revision number of the assembly. `StrongName` is the hexadecimal-encoded low-order 64 bits of the hash value of the public key generated using the SHA-1 hashing algorithm and the public key specified by . `PublicKeyToken` is the hexadecimal-encoded public key specified by . - - Hexadecimal encoding is defined as the conversion of each byte of a binary object to two hexadecimal characters, progressing from least to most significant byte. Additional display values will be added as deemed necessary. - - If the full public key is known, then PublicKey may be substituted for StrongName. - - Also note that except for `Name`, which must come first, the lexical order of parameters is unimportant. However, any parameter (`Version`, `Culture`, `StrongName` or `PublicKey`) not specifically set is considered to be omitted, and the is then considered partial. When specifying partial information, Name parameters must be specified in the order described above. - - When supplying a display name, the convention `StrongName =null` or `PublicKey= null` indicates that binding and matching against a simply named assembly is required. Additionally, the convention `Culture= ""` (double quote representing an empty string) indicates matching against the default culture. - - The following example shows an for a simply named assembly with default culture. - -``` -ExampleAssembly, Culture="" -``` - - The following example shows a fully specified reference for a strongly named assembly with culture "en". - -``` -ExampleAssembly, Version=1.0.0.0, Culture=en, PublicKeyToken=a5d015c7d5a0b012 -``` - - - -## Examples - This example shows how to use various reflection classes to analyze the metadata contained in an assembly. - + object contains information about an assembly, which you can use to bind to that assembly. An assembly's identity consists of the following: + +- Simple name. + +- Version number. + +- Cryptographic key pair. + +- Supported culture. + + The simple name is typically the file name for the manifest file without its extension. The key pair includes a public and private key, used to create strong-name signatures for assemblies. + + All compilers that support the common language runtime will emit the simple name of a nested class, and reflection constructs a mangled name when queried, in accordance with the following conventions. + +|Delimiter|Meaning| +|---------------|-------------| +|Backslash (\\)|Escape character.| +|Comma (,)|Precedes the assembly name.| +|Plus sign (+)|Precedes a nested class.| + + For example, the fully qualified name for a class might look like this: + + ContainingClass+NestedClass,MyAssembly + + A "++" becomes "\\+\\+", and a "\\" becomes "\\\\". + + This qualified name can be persisted and later used to load the . To search for and load a , use either with the type name only or with the assembly qualified type name. with the type name only will look for the in the caller's assembly and then in the System assembly. with the assembly qualified type name will look for the in any assembly. + + A fully specified must have the name, culture, public key or public key token, major version, minor version, build number, and revision number parameters. The last four are packaged in the type. + + To create a simple name, create an object using the parameterless constructor and set the . The other properties are optional. + + To create a full strong name, create an object using the parameterless constructor and set the and . The other properties are optional. Use and to set the public key and the strong name. The strong name signing always uses the hash algorithm. + + To ensure that the names are constructed correctly, use the following properties: + +- + +- + +- + + You can also get the name by using the `/l` option with the [Gacutil.exe (Global Assembly Cache Tool)](/dotnet/framework/tools/gacutil-exe-gac-tool) + + For a partially specified strong name, create an object using the parameterless constructor and set the name and public key. An assembly created using such an can be signed later using the Assembly Linker (Al.exe). + + It is possible to specify a public key and a with inconsistent values. This can be useful in developer scenarios. In this case, the public key retrieved with specifies the correct public key, while the specifies the public and private keys used during development. When the runtime detects a mismatch between the and the public key, it looks up in the registry the correct key that matches the public key. + + The format of the display name of an is a comma-delimited Unicode string that begins with the name, as follows: + + `Name <,Culture = CultureInfo> <,Version = Major.Minor.Build.Revision> <, StrongName> <,PublicKeyToken> '\0'` + + `Name` is the textual name of the assembly. `CultureInfo` is the RFC1766-format-defined culture. `Major`, `Minor`, `Build`, and `Revision` are the major version, minor version, build number, and revision number of the assembly. `StrongName` is the hexadecimal-encoded low-order 64 bits of the hash value of the public key generated using the SHA-1 hashing algorithm and the public key specified by . `PublicKeyToken` is the hexadecimal-encoded public key specified by . + + Hexadecimal encoding is defined as the conversion of each byte of a binary object to two hexadecimal characters, progressing from least to most significant byte. Additional display values will be added as deemed necessary. + + If the full public key is known, then PublicKey may be substituted for StrongName. + + Also note that except for `Name`, which must come first, the lexical order of parameters is unimportant. However, any parameter (`Version`, `Culture`, `StrongName` or `PublicKey`) not specifically set is considered to be omitted, and the is then considered partial. When specifying partial information, Name parameters must be specified in the order described above. + + When supplying a display name, the convention `StrongName =null` or `PublicKey= null` indicates that binding and matching against a simply named assembly is required. Additionally, the convention `Culture= ""` (double quote representing an empty string) indicates matching against the default culture. + + The following example shows an for a simply named assembly with default culture. + +``` +ExampleAssembly, Culture="" +``` + + The following example shows a fully specified reference for a strongly named assembly with culture "en". + +``` +ExampleAssembly, Version=1.0.0.0, Culture=en, PublicKeyToken=a5d015c7d5a0b012 +``` + + + +## Examples + This example shows how to use various reflection classes to analyze the metadata contained in an assembly. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Reflection/CPP/reflection.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/Assembly/GetReferencedAssemblies/Reflection.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Reflection/VB/Reflection.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Reflection/VB/Reflection.vb" id="Snippet1"::: + ]]> @@ -257,15 +257,15 @@ ExampleAssembly, Version=1.0.0.0, Culture=en, PublicKeyToken=a5d015c7d5a0b012 Initializes a new instance of the class. - @@ -323,20 +323,20 @@ ExampleAssembly, Version=1.0.0.0, Culture=en, PublicKeyToken=a5d015c7d5a0b012 The display name of the assembly, as returned by the property. Initializes a new instance of the class with the specified display name. - are initialized with values from the display name. This is the recommended way of parsing display names. Writing your own code to parse display names is not recommended. - - - -## Examples - The following example creates an instance of from a display name. The individual elements of the display name are output to the console as properties of the object. - + are initialized with values from the display name. This is the recommended way of parsing display names. Writing your own code to parse display names is not recommended. + + + +## Examples + The following example creates an instance of from a display name. The individual elements of the display name are output to the console as properties of the object. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/AssemblyName_Constructor_2/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/AssemblyName/.ctor/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/AssemblyName_Constructor_2/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/AssemblyName_Constructor_2/VB/source.vb" id="Snippet1"::: + ]]> @@ -400,11 +400,11 @@ Note: In .NET for Win Makes a copy of this object. An object that is a copy of this object. - @@ -461,25 +461,25 @@ Note: In .NET for Win Gets or sets the location of the assembly as a URL. A string that is the URL location of the assembly. - property. - - If the assembly was loaded as a byte array, this property returns the location of the caller of the method overload, not the location of the loaded assembly. - + property. + + If the assembly was loaded as a byte array, this property returns the location of the caller of the method overload, not the location of the loaded assembly. + > [!NOTE] -> Do not use an with only the property set. The property does not supply any elements of the assembly identity (such as name or version), so loading does not occur according to load-by-identity rules, as you would expect from the method. Instead, the assembly is loaded using load-from rules. For information about the disadvantages of using the load-from context, see the method overload or [Best Practices for Assembly Loading](/dotnet/framework/deployment/best-practices-for-assembly-loading). - - - -## Examples - The following example emits a dynamic assembly and saves it to the current directory. When the assembly is created, the property is used to specify the directory where the assembly is saved. - +> Do not use an with only the property set. The property does not supply any elements of the assembly identity (such as name or version), so loading does not occur according to load-by-identity rules, as you would expect from the method. Instead, the assembly is loaded using load-from rules. For information about the disadvantages of using the load-from context, see the method overload or [Best Practices for Assembly Loading](/dotnet/framework/deployment/best-practices-for-assembly-loading). + + + +## Examples + The following example emits a dynamic assembly and saves it to the current directory. When the assembly is created, the property is used to specify the directory where the assembly is saved. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/AssemblyName_CodeBase/CPP/assemblyname_codebase.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/AssemblyName/CodeBase/assemblyname_codebase.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/AssemblyName_CodeBase/VB/assemblyname_codebase.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/AssemblyName_CodeBase/VB/assemblyname_codebase.vb" id="Snippet1"::: + ]]> @@ -576,15 +576,15 @@ Note: In .NET for Win Gets or sets the culture supported by the assembly. An object that represents the culture supported by the assembly. - property is used to specify the culture, which is part of the assembly's display name. - + property is used to specify the culture, which is part of the assembly's display name. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/AssemblyName_CodeBase/CPP/assemblyname_codebase.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/AssemblyName/CodeBase/assemblyname_codebase.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/AssemblyName_CodeBase/VB/assemblyname_codebase.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/AssemblyName_CodeBase/VB/assemblyname_codebase.vb" id="Snippet2"::: + ]]> @@ -740,15 +740,15 @@ Note: In .NET for Win Gets or sets the attributes of the assembly. A value that represents the attributes of the assembly. - property is used to specify that the assembly has a public key. - + property is used to specify that the assembly has a public key. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/AssemblyName_KeyPair/CPP/assemblyname_keypair.cpp" id="Snippet4"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/AssemblyName/Flags/assemblyname_keypair.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/AssemblyName_KeyPair/VB/assemblyname_keypair.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/AssemblyName_KeyPair/VB/assemblyname_keypair.vb" id="Snippet4"::: + ]]> @@ -811,28 +811,28 @@ Note: In .NET for Win Gets the full name of the assembly, also known as the display name. A string that is the full name of the assembly, also known as the display name. - constructor, which parses it and populates the appropriate fields of the new . - - When an assembly is loaded, this value can also be obtained using the property. - - - -## Examples - The following example emits a dynamic assembly and saves it to the current directory. When the assembly is created, the code example sets the , , , and properties, which together comprise an assembly's full name, or display name. The property is then used to retrieve the display name. - + constructor, which parses it and populates the appropriate fields of the new . + + When an assembly is loaded, this value can also be obtained using the property. + + + +## Examples + The following example emits a dynamic assembly and saves it to the current directory. When the assembly is created, the code example sets the , , , and properties, which together comprise an assembly's full name, or display name. The property is then used to retrieve the display name. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/AssemblyName_CodeBase/CPP/assemblyname_codebase.cpp" id="Snippet4"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/AssemblyName/CodeBase/assemblyname_codebase.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/AssemblyName_CodeBase/VB/assemblyname_codebase.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/AssemblyName_CodeBase/VB/assemblyname_codebase.vb" id="Snippet4"::: + ]]> Specifying Fully Qualified Type Names @@ -886,27 +886,27 @@ mylib, Version=1.2.1900.0, Culture=neutral, PublicKeyToken=a14f3033def15840 System.Reflection.AssemblyName - + The path for the assembly whose is to be returned. Gets the for a given file. An object that represents the given assembly file. - for an assembly on disk. It will not run unless you replace the string "MyAssembly.exe" with the file name of an assembly (including the path, if necessary) on your hard disk. Alternatively, you can compile this example as "MyAssembly.exe". - + for an assembly on disk. It will not run unless you replace the string "MyAssembly.exe" with the file name of an assembly (including the path, if necessary) on your hard disk. Alternatively, you can compile this example as "MyAssembly.exe". + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/AssemblyName_GetAssemblyName/CPP/assemblyname_getassemblyname.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/AssemblyName/GetAssemblyName/assemblyname_getassemblyname.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/AssemblyName_GetAssemblyName/VB/assemblyname_getassemblyname.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/AssemblyName_GetAssemblyName/VB/assemblyname_getassemblyname.vb" id="Snippet1"::: + ]]> @@ -980,8 +980,8 @@ mylib, Version=1.2.1900.0, Culture=neutral, PublicKeyToken=a14f3033def15840 System.Void - - + + The object to be populated with serialization information. @@ -1038,15 +1038,15 @@ mylib, Version=1.2.1900.0, Culture=neutral, PublicKeyToken=a14f3033def15840 Gets the public key of the assembly. A byte array that contains the public key of the assembly. - method is used to give the assembly a public key. The method is then used to retrieve the public key, which is displayed to the console. - + method is used to give the assembly a public key. The method is then used to retrieve the public key, which is displayed to the console. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/AssemblyName_KeyPair/CPP/assemblyname_keypair.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/AssemblyName/Flags/assemblyname_keypair.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/AssemblyName_KeyPair/VB/assemblyname_keypair.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/AssemblyName_KeyPair/VB/assemblyname_keypair.vb" id="Snippet2"::: + ]]> A public key was provided (for example, by using the method), but no public key token was provided. @@ -1104,15 +1104,15 @@ mylib, Version=1.2.1900.0, Culture=neutral, PublicKeyToken=a14f3033def15840 Gets the public key token, which is the last 8 bytes of the SHA-1 hash of the public key under which the application or assembly is signed. A byte array that contains the public key token. - method is used to set the assembly's public key token. The method is then used to retrieve the public key token, which is displayed to the console. - + method is used to set the assembly's public key token. The method is then used to retrieve the public key token, which is displayed to the console. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/AssemblyName_KeyPair/CPP/assemblyname_keypair.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/AssemblyName/Flags/assemblyname_keypair.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/AssemblyName_KeyPair/VB/assemblyname_keypair.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/AssemblyName_KeyPair/VB/assemblyname_keypair.vb" id="Snippet3"::: + ]]> @@ -1164,22 +1164,22 @@ mylib, Version=1.2.1900.0, Culture=neutral, PublicKeyToken=a14f3033def15840 Gets or sets the hash algorithm used by the assembly manifest. The hash algorithm used by the assembly manifest. - [!IMPORTANT] -> Starting with the .NET Framework 4, the property of an object that is returned by the method is if there is no hash algorithm for the referenced assembly, or if the hash algorithm of the referenced assembly is not identified by the enumeration. In previous versions of the .NET Framework, the property returned in this situation. - - - -## Examples - The following example emits a dynamic assembly and saves it to the current directory. When the assembly is created, the property is used to set the hash algorithm for the assembly manifest. - +> Starting with the .NET Framework 4, the property of an object that is returned by the method is if there is no hash algorithm for the referenced assembly, or if the hash algorithm of the referenced assembly is not identified by the enumeration. In previous versions of the .NET Framework, the property returned in this situation. + + + +## Examples + The following example emits a dynamic assembly and saves it to the current directory. When the assembly is created, the property is used to set the hash algorithm for the assembly manifest. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/AssemblyName_CodeBase/CPP/assemblyname_codebase.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/AssemblyName/CodeBase/assemblyname_codebase.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/AssemblyName_CodeBase/VB/assemblyname_codebase.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/AssemblyName_CodeBase/VB/assemblyname_codebase.vb" id="Snippet3"::: + ]]> @@ -1232,18 +1232,18 @@ mylib, Version=1.2.1900.0, Culture=neutral, PublicKeyToken=a14f3033def15840 Gets or sets the public and private cryptographic key pair that is used to create a strong name signature for the assembly. The public and private cryptographic key pair to be used to create a strong name for the assembly. - property. The getter for the property is only useful if the user set the property before using the object to create a dynamic assembly, and subsequently wants to retrieve the key pair. - -## Examples + +## Examples The following example emits a dynamic assembly and saves it to the current directory. When the assembly is created, the property is used to set the assembly's public and private cryptographic keys. - + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/AssemblyName_KeyPair/CPP/assemblyname_keypair.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/AssemblyName/Flags/assemblyname_keypair.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/AssemblyName_KeyPair/VB/assemblyname_keypair.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/AssemblyName_KeyPair/VB/assemblyname_keypair.vb" id="Snippet1"::: + ]]> .NET 6+ only: In all cases. @@ -1294,22 +1294,22 @@ mylib, Version=1.2.1900.0, Culture=neutral, PublicKeyToken=a14f3033def15840 Gets or sets the simple name of the assembly. This is usually, but not necessarily, the file name of the manifest file of the assembly, minus its extension. The simple name of the assembly. - property is used to set the simple name of the dynamic assembly. - + property is used to set the simple name of the dynamic assembly. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/AssemblyName_Constructor/CPP/assemblyname_constructor.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/AssemblyName/.ctor/assemblyname_constructor.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/AssemblyName_Constructor/VB/assemblyname_constructor.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/AssemblyName_Constructor/VB/assemblyname_constructor.vb" id="Snippet2"::: + ]]> Specifying Fully Qualified Type Names @@ -1357,7 +1357,7 @@ mylib, Version=1.2.1900.0, Culture=neutral, PublicKeyToken=a14f3033def15840 System.Void - + The source of the deserialization event. @@ -1415,11 +1415,11 @@ mylib, Version=1.2.1900.0, Culture=neutral, PublicKeyToken=a14f3033def15840 Gets or sets a value that identifies the processor and bits-per-word of the platform targeted by an executable. One of the enumeration values that identifies the processor and bits-per-word of the platform targeted by an executable. - for reference assemblies. - + for reference assemblies. + ]]> @@ -1469,8 +1469,8 @@ mylib, Version=1.2.1900.0, Culture=neutral, PublicKeyToken=a14f3033def15840 System.Boolean - - + + The reference assembly name. @@ -1479,11 +1479,11 @@ mylib, Version=1.2.1900.0, Culture=neutral, PublicKeyToken=a14f3033def15840 if the simple assembly names are the same; otherwise, . - @@ -1536,20 +1536,20 @@ mylib, Version=1.2.1900.0, Culture=neutral, PublicKeyToken=a14f3033def15840 A byte array containing the public key of the assembly. Sets the public key identifying the assembly. - method to provide a public key token. Otherwise, a is thrown when the method is called. - - - -## Examples - The following example emits a dynamic assembly and saves it to the current directory. When the assembly is created, the method is used to give the assembly a public key. The method is then used to retrieve the public key, which is displayed to the console. - + method to provide a public key token. Otherwise, a is thrown when the method is called. + + + +## Examples + The following example emits a dynamic assembly and saves it to the current directory. When the assembly is created, the method is used to give the assembly a public key. The method is then used to retrieve the public key, which is displayed to the console. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/AssemblyName_SetPublicKey/CPP/assemblyname_setpublickey.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/AssemblyName/SetPublicKey/assemblyname_setpublickey.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/AssemblyName_SetPublicKey/VB/assemblyname_setpublickey.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/AssemblyName_SetPublicKey/VB/assemblyname_setpublickey.vb" id="Snippet1"::: + ]]> @@ -1602,20 +1602,20 @@ mylib, Version=1.2.1900.0, Culture=neutral, PublicKeyToken=a14f3033def15840 A byte array containing the public key token of the assembly. Sets the public key token, which is the last 8 bytes of the SHA-1 hash of the public key under which the application or assembly is signed. - method, you must also use the method to provide a public key token. Otherwise, a is thrown when the method is called. - - - -## Examples - The following example emits a dynamic assembly and saves it to the current directory. When the assembly is created, the method is used to set the assembly's public key token. The method is then used to retrieve the public key token, which is displayed to the console. - + method, you must also use the method to provide a public key token. Otherwise, a is thrown when the method is called. + + + +## Examples + The following example emits a dynamic assembly and saves it to the current directory. When the assembly is created, the method is used to set the assembly's public key token. The method is then used to retrieve the public key token, which is displayed to the console. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/AssemblyName_SetPublicKey/CPP/assemblyname_setpublickey.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/AssemblyName/SetPublicKey/assemblyname_setpublickey.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/AssemblyName_SetPublicKey/VB/assemblyname_setpublickey.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/AssemblyName_SetPublicKey/VB/assemblyname_setpublickey.vb" id="Snippet2"::: + ]]> @@ -1650,11 +1650,11 @@ mylib, Version=1.2.1900.0, Culture=neutral, PublicKeyToken=a14f3033def15840 System.Void - - - - - + + + + + Reserved for future use. Must be IID_NULL. @@ -1664,11 +1664,11 @@ mylib, Version=1.2.1900.0, Culture=neutral, PublicKeyToken=a14f3033def15840 Caller-allocated array that receives the IDs corresponding to the names. Maps a set of names to a corresponding set of dispatch identifiers. - Late-bound access using the COM IDispatch interface is not supported. @@ -1704,9 +1704,9 @@ mylib, Version=1.2.1900.0, Culture=neutral, PublicKeyToken=a14f3033def15840 System.Void - - - + + + The type information to return. @@ -1714,11 +1714,11 @@ mylib, Version=1.2.1900.0, Culture=neutral, PublicKeyToken=a14f3033def15840 Receives a pointer to the requested type information object. Retrieves the type information for an object, which can then be used to get the type information for an interface. - Late-bound access using the COM IDispatch interface is not supported. @@ -1754,17 +1754,17 @@ mylib, Version=1.2.1900.0, Culture=neutral, PublicKeyToken=a14f3033def15840 System.Void - + Points to a location that receives the number of type information interfaces provided by the object. Retrieves the number of type information interfaces that an object provides (either 0 or 1). - Late-bound access using the COM IDispatch interface is not supported. @@ -1800,14 +1800,14 @@ mylib, Version=1.2.1900.0, Culture=neutral, PublicKeyToken=a14f3033def15840 System.Void - - - - - - - - + + + + + + + + Identifies the member. @@ -1820,11 +1820,11 @@ mylib, Version=1.2.1900.0, Culture=neutral, PublicKeyToken=a14f3033def15840 The index of the first argument that has an error. Provides access to properties and methods exposed by an object. - Late-bound access using the COM IDispatch interface is not supported. @@ -1881,20 +1881,20 @@ mylib, Version=1.2.1900.0, Culture=neutral, PublicKeyToken=a14f3033def15840 Returns the full name of the assembly, also known as the display name. The full name of the assembly, or the class name if the full name cannot be determined. - for the format of the returned string. - - - -## Examples - The following example gets an object for a hypothetical `MyAssembly.exe` assembly, and then uses the method to retrieve the full assembly name, or display name. - + for the format of the returned string. + + + +## Examples + The following example gets an object for a hypothetical `MyAssembly.exe` assembly, and then uses the method to retrieve the full assembly name, or display name. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/AssemblyName_GetAssemblyName/CPP/assemblyname_getassemblyname.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/AssemblyName/GetAssemblyName/assemblyname_getassemblyname.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/AssemblyName_GetAssemblyName/VB/assemblyname_getassemblyname.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/AssemblyName_GetAssemblyName/VB/assemblyname_getassemblyname.vb" id="Snippet2"::: + ]]> @@ -1944,32 +1944,32 @@ mylib, Version=1.2.1900.0, Culture=neutral, PublicKeyToken=a14f3033def15840 Gets or sets the major, minor, build, and revision numbers of the assembly. An object that represents the major, minor, build, and revision numbers of the assembly. - - 1. If a component exceeds this value, no error is thrown; however, in a dynamic assembly, that component is zero. - - - -## Examples - This section contains two examples. The first example shows how to retrieve the version of the currently executing assembly. The second example shows how to use the property to specify the assembly version when you emit a dynamic assembly. - - **Example 1** - - The following example retrieves and displays the version numbers of the currently executing assembly and the assembly that contains the class. - + - 1. If a component exceeds this value, no error is thrown; however, in a dynamic assembly, that component is zero. + + + +## Examples + This section contains two examples. The first example shows how to retrieve the version of the currently executing assembly. The second example shows how to use the property to specify the assembly version when you emit a dynamic assembly. + + **Example 1** + + The following example retrieves and displays the version numbers of the currently executing assembly and the assembly that contains the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/AssemblyName.Version/cpp/Example.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/AssemblyName/Version/Example.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/AssemblyName.Version/vb/Example.vb" id="Snippet1"::: - - **Example 2** - - The following example emits a dynamic assembly and saves it to the current directory. When the assembly is created, the property is used to specify version information for the assembly. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/AssemblyName.Version/vb/Example.vb" id="Snippet1"::: + + **Example 2** + + The following example emits a dynamic assembly and saves it to the current directory. When the assembly is created, the property is used to specify version information for the assembly. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/AssemblyName_Constructor/CPP/assemblyname_constructor.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/AssemblyName/.ctor/assemblyname_constructor.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/AssemblyName_Constructor/VB/assemblyname_constructor.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/AssemblyName_Constructor/VB/assemblyname_constructor.vb" id="Snippet3"::: + ]]> @@ -2021,13 +2021,13 @@ mylib, Version=1.2.1900.0, Culture=neutral, PublicKeyToken=a14f3033def15840 Gets or sets the information related to the assembly's compatibility with other assemblies. A value that represents information about the assembly's compatibility with other assemblies. - information indicates, for example, that the assembly cannot execute side-by-side with other versions due to conflicts over a device driver. - - Currently, always returns , and is not used by the loader. This property is reserved for a future feature. - + information indicates, for example, that the assembly cannot execute side-by-side with other versions due to conflicts over a device driver. + + Currently, always returns , and is not used by the loader. This property is reserved for a future feature. + ]]> diff --git a/xml/System.Reflection/ConstructorInfo.xml b/xml/System.Reflection/ConstructorInfo.xml index 5457a440912..8e2b1f8e51c 100644 --- a/xml/System.Reflection/ConstructorInfo.xml +++ b/xml/System.Reflection/ConstructorInfo.xml @@ -92,23 +92,23 @@ Discovers the attributes of a class constructor and provides access to constructor metadata. - on a `ConstructorInfo` returned by either the or method of a object. - + on a `ConstructorInfo` returned by either the or method of a object. + > [!NOTE] -> inherits from several members, such as , that can be used to examine generic methods. In the .NET Framework version 2.0 constructors cannot be generic, so these members return `false` or `null`. - - - -## Examples - The following example uses `ConstructorInfo` with and to find the constructors that match the specified search criteria. - +> inherits from several members, such as , that can be used to examine generic methods. In the .NET Framework version 2.0 constructors cannot be generic, so these members return `false` or `null`. + + + +## Examples + The following example uses `ConstructorInfo` with and to find the constructors that match the specified search criteria. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Type_GetConstructor3/CPP/type_getconstructor3.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System/Type/GetConstructor/type_getconstructor3.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Type_GetConstructor3/VB/type_getconstructor3.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Type_GetConstructor3/VB/type_getconstructor3.vb" id="Snippet1"::: + ]]> This type is thread safe. @@ -118,11 +118,11 @@ - - - - - + + + + + Constructor mscorlib @@ -427,27 +427,27 @@ Invokes the constructor reflected by the instance that has the specified parameters, providing default values for the parameters not commonly used. An instance of the class associated with the constructor. - [!NOTE] -> To create an instance of a value type that has no instance constructors, use the method. - - This method is a convenience method for the following overloaded version, using default values. This method cannot be overridden. - +> To create an instance of a value type that has no instance constructors, use the method. + + This method is a convenience method for the following overloaded version, using default values. This method cannot be overridden. + > [!NOTE] -> Starting with .NET Framework 2.0, this method can be used to access non-public members if the caller has been granted with the flag and if the grant set of the non-public members is restricted to the caller's grant set, or a subset thereof. (See [Security Considerations for Reflection](/dotnet/framework/reflection-and-codedom/security-considerations-for-reflection).) To use this functionality, your application should target .NET Framework 3.5 or later. - +> Starting with .NET Framework 2.0, this method can be used to access non-public members if the caller has been granted with the flag and if the grant set of the non-public members is restricted to the caller's grant set, or a subset thereof. (See [Security Considerations for Reflection](/dotnet/framework/reflection-and-codedom/security-considerations-for-reflection).) To use this functionality, your application should target .NET Framework 3.5 or later. + ]]> - The class is abstract. - - -or- - + The class is abstract. + + -or- + The constructor is a class initializer. The constructor is private or protected, and the caller lacks . @@ -499,10 +499,10 @@ Note: In .NET for Win System.Object - - - - + + + + One of the values that specifies the type of binding. @@ -512,21 +512,21 @@ Note: In .NET for Win When implemented in a derived class, invokes the constructor reflected by this with the specified arguments, under the constraints of the specified . An instance of the class associated with the constructor. - [!NOTE] -> To create an instance of a value type that has no instance constructors, use the method. - +> To create an instance of a value type that has no instance constructors, use the method. + > [!NOTE] -> Starting with .NET Framework 2.0, this method can be used to access non-public members if the caller has been granted with the flag and if the grant set of the non-public members is restricted to the caller's grant set, or a subset thereof. (See [Security Considerations for Reflection](/dotnet/framework/reflection-and-codedom/security-considerations-for-reflection).) To use this functionality, your application should target .NET Framework 3.5 or later. - +> Starting with .NET Framework 2.0, this method can be used to access non-public members if the caller has been granted with the flag and if the grant set of the non-public members is restricted to the caller's grant set, or a subset thereof. (See [Security Considerations for Reflection](/dotnet/framework/reflection-and-codedom/security-considerations-for-reflection).) To use this functionality, your application should target .NET Framework 3.5 or later. + ]]> The array does not contain values that match the types accepted by this constructor, under the constraints of the . @@ -534,10 +534,10 @@ Note: In .NET for Win An incorrect number of parameters was passed. Creation of , , and types is not supported. The caller does not have the necessary code access permissions. - The class is abstract. - - -or- - + The class is abstract. + + -or- + The constructor is a class initializer. The constructor is private or protected, and the caller lacks . @@ -595,20 +595,20 @@ Note: In .NET for Win Gets a value indicating that this member is a constructor. A value indicating that this member is a constructor. - . Therefore, when you examine a set of objects - for example, the array returned by - the property returns only when a given member is a constructor. - - - -## Examples - The following example uses the property to identify a object as a constructor. - + . Therefore, when you examine a set of objects - for example, the array returned by - the property returns only when a given member is a constructor. + + + +## Examples + The following example uses the property to identify a object as a constructor. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic MemberInfo.MemberType Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/ConstructorInfo/MemberType/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic MemberInfo.MemberType Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic MemberInfo.MemberType Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -651,8 +651,8 @@ Note: In .NET for Win System.Boolean - - + + The first to compare. @@ -700,8 +700,8 @@ Note: In .NET for Win System.Boolean - - + + The first to compare. @@ -742,11 +742,11 @@ Note: In .NET for Win System.Void - - - - - + + + + + Reserved for future use. Must be IID_NULL. @@ -756,11 +756,11 @@ Note: In .NET for Win Caller-allocated array which receives the IDs corresponding to the names. Maps a set of names to a corresponding set of dispatch identifiers. - Late-bound access using the COM IDispatch interface is not supported. @@ -831,9 +831,9 @@ Note: In .NET for Win System.Void - - - + + + The type information to return. @@ -841,11 +841,11 @@ Note: In .NET for Win Receives a pointer to the requested type information object. Retrieves the type information for an object, which can then be used to get the type information for an interface. - Late-bound access using the COM IDispatch interface is not supported. @@ -881,17 +881,17 @@ Note: In .NET for Win System.Void - + Points to a location that receives the number of type information interfaces provided by the object. Retrieves the number of type information interfaces that an object provides (either 0 or 1). - Late-bound access using the COM IDispatch interface is not supported. @@ -927,14 +927,14 @@ Note: In .NET for Win System.Void - - - - - - - - + + + + + + + + Identifies the member. @@ -947,11 +947,11 @@ Note: In .NET for Win The index of the first argument that has an error. Provides access to properties and methods exposed by an object. - Late-bound access using the COM IDispatch interface is not supported. @@ -987,11 +987,11 @@ Note: In .NET for Win System.Object - - - - - + + + + + The instance that created this method. @@ -1002,11 +1002,11 @@ Note: In .NET for Win Provides COM objects with version-independent access to the method. An instance of the type. - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -1041,8 +1041,8 @@ Note: In .NET for Win System.Object - - + + The instance that created this method. @@ -1050,11 +1050,11 @@ Note: In .NET for Win Provides COM objects with version-independent access to the method. An instance of the type. - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -1089,10 +1089,10 @@ Note: In .NET for Win System.Object - - - - + + + + One of the values that specifies the type of binding. @@ -1102,11 +1102,11 @@ Note: In .NET for Win Provides COM objects with version-independent access to the method. An instance of the type. - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -1141,18 +1141,18 @@ Note: In .NET for Win System.Object - + An array of objects used to match the number, order, and type of the parameters for this constructor, under the constraints of . If this constructor does not require parameters, pass an array with zero elements. Any object in this array that is not explicitly initialized with a value will contain the default value for that object type. For reference-type elements, this value is . For value-type elements, this value is 0, 0.0, or , depending on the specific element type. Provides COM objects with version-independent access to the method. An instance of the type. - instance is cast to an interface. - + instance is cast to an interface. + ]]> diff --git a/xml/System.Reflection/CustomAttributeData.xml b/xml/System.Reflection/CustomAttributeData.xml index 5ba1a32fe39..b55bbde6ce6 100644 --- a/xml/System.Reflection/CustomAttributeData.xml +++ b/xml/System.Reflection/CustomAttributeData.xml @@ -79,42 +79,42 @@ Provides access to custom attribute data for assemblies, modules, types, members and parameters that are loaded into the reflection-only context. - , , and so on. If the code for the attribute type itself is loaded into the reflection-only context, it cannot be executed. - - The class allows examination of custom attributes in the reflection-only context by providing an abstraction for attributes. The members of this class can be used to obtain the positional arguments and named arguments of the attribute. Use the property to get a list of structures that represent the positional arguments, and use the property to get a list of structures that represent the named arguments. - + , , and so on. If the code for the attribute type itself is loaded into the reflection-only context, it cannot be executed. + + The class allows examination of custom attributes in the reflection-only context by providing an abstraction for attributes. The members of this class can be used to obtain the positional arguments and named arguments of the attribute. Use the property to get a list of structures that represent the positional arguments, and use the property to get a list of structures that represent the named arguments. + > [!NOTE] -> The structure only provides information about the attribute property used to get and set the argument value. To obtain the type and value of the argument, use the property to obtain a structure. - - When you have a structure for an argument, whether named or positional, use the property to get the type and the property to get the value. - +> The structure only provides information about the attribute property used to get and set the argument value. To obtain the type and value of the argument, use the property to obtain a structure. + + When you have a structure for an argument, whether named or positional, use the property to get the type and the property to get the value. + > [!NOTE] -> For an array argument, the property returns a generic of objects. Each object in the collection represents the corresponding element of the array. - - can be used in the execution context as well as in the reflection-only context. For example, you might want to avoid loading the assembly that contains the code for a custom attribute. Using the class is different from using methods like : - -- The properties and methods of only provide you with the values that were specified for the attribute instance, not the semantics of the constructor. For example, a string argument of an attribute might be converted internally to some other representation, and returned in a canonical form; or a property might have side effects when the actual attribute code is executed. - -- The properties and methods of do not allow you to retrieve the custom attributes inherited from base classes. - - To create instances of the class, use the `static` (`Shared` in Visual Basic) factory methods. - - - -## Examples - The following example defines a custom attribute with four constructors and four properties. Two of the properties are read-only, and are set by using the positional parameters of the constructors. The other two properties are read/write, and can be set only by using named arguments. One positional property is an array of strings, and one named property is an array of integers. - - The attribute is applied to the assembly, to a type declared in the assembly, to a method of the type, and to a parameter of the method. Different constructors are used for these cases. When executed, the assembly loads itself into the reflection-only context and displays information about the custom attributes that were applied to it and to the type and members it contains. - - The attribute that is applied to the type demonstrates array properties, with both positional and named arguments. - +> For an array argument, the property returns a generic of objects. Each object in the collection represents the corresponding element of the array. + + can be used in the execution context as well as in the reflection-only context. For example, you might want to avoid loading the assembly that contains the code for a custom attribute. Using the class is different from using methods like : + +- The properties and methods of only provide you with the values that were specified for the attribute instance, not the semantics of the constructor. For example, a string argument of an attribute might be converted internally to some other representation, and returned in a canonical form; or a property might have side effects when the actual attribute code is executed. + +- The properties and methods of do not allow you to retrieve the custom attributes inherited from base classes. + + To create instances of the class, use the `static` (`Shared` in Visual Basic) factory methods. + + + +## Examples + The following example defines a custom attribute with four constructors and four properties. Two of the properties are read-only, and are set by using the positional parameters of the constructors. The other two properties are read/write, and can be set only by using named arguments. One positional property is an array of strings, and one named property is an array of integers. + + The attribute is applied to the assembly, to a type declared in the assembly, to a method of the type, and to a parameter of the method. Different constructors are used for these cases. When executed, the assembly loads itself into the reflection-only context and displays information about the custom attributes that were applied to it and to the type and members it contains. + + The attribute that is applied to the type demonstrates array properties, with both positional and named arguments. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/CustomAttributeData/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/CustomAttributeData/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/CustomAttributeData/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/CustomAttributeData/VB/source.vb" id="Snippet1"::: + ]]> @@ -122,11 +122,11 @@ - - - - - + + + + + Constructor mscorlib @@ -165,11 +165,11 @@ Initializes a new instance of the class. - objects. - + objects. + ]]> @@ -271,26 +271,26 @@ Gets a object that represents the constructor that would have initialized the custom attribute. An object that represents the constructor that would have initialized the custom attribute represented by the current instance of the class. - object. - - - -## Examples - The following example defines a custom attribute with four constructors and four properties. Two of the properties are read-only, and are set by using the positional parameters of the constructors. The other two properties are read/write, and can be set only by using named arguments. One positional property is an array of strings, and one named property is an array of integers. - - The attribute is applied to the assembly, to a type declared in the assembly, to a method of the type, and to a parameter of the method. Different constructors are used for these cases. When executed, the assembly loads itself into the reflection-only context and displays the custom attributes. - - The attribute that is applied to the type demonstrates array properties, with both positional and named arguments. - - The property is used in the `ShowAttributeData` method that displays custom attribute data. In this code example, the returned by this property is used to display a text string that describes the constructor, demonstrating that the property returns the constructor that would initialize the attribute. - + object. + + + +## Examples + The following example defines a custom attribute with four constructors and four properties. Two of the properties are read-only, and are set by using the positional parameters of the constructors. The other two properties are read/write, and can be set only by using named arguments. One positional property is an array of strings, and one named property is an array of integers. + + The attribute is applied to the assembly, to a type declared in the assembly, to a method of the type, and to a parameter of the method. Different constructors are used for these cases. When executed, the assembly loads itself into the reflection-only context and displays the custom attributes. + + The attribute that is applied to the type demonstrates array properties, with both positional and named arguments. + + The property is used in the `ShowAttributeData` method that displays custom attribute data. In this code example, the returned by this property is used to display a text string that describes the constructor, demonstrating that the property returns the constructor that would initialize the attribute. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/CustomAttributeData/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/CustomAttributeData/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/CustomAttributeData/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/CustomAttributeData/VB/source.vb" id="Snippet1"::: + ]]> @@ -349,28 +349,28 @@ Gets the list of positional arguments specified for the attribute instance represented by the object. A collection of structures that represent the positional arguments specified for the custom attribute instance. - method to get the named arguments specified for the attribute instance. - - - -## Examples - The following example defines a custom attribute with four constructors and four properties. Two of the properties are read-only, and are set by using the positional parameters of the constructors. The other two properties are read/write, and can be set only by using named arguments. One positional property is an array of strings, and one named property is an array of integers. - - The attribute is applied to the assembly, to a type declared in the assembly, to a method of the type, and to a parameter of the method. Different constructors are used for these cases. When executed, the assembly loads itself into the reflection-only context and displays the custom attributes. - - The attribute that is applied to the type demonstrates array properties, with both positional and named arguments. - - The property is used in the `ShowAttributeData` method that displays custom attribute data. In this code example, this property is used to display the list of arguments passed to the constructor that initialized the attribute. - + method to get the named arguments specified for the attribute instance. + + + +## Examples + The following example defines a custom attribute with four constructors and four properties. Two of the properties are read-only, and are set by using the positional parameters of the constructors. The other two properties are read/write, and can be set only by using named arguments. One positional property is an array of strings, and one named property is an array of integers. + + The attribute is applied to the assembly, to a type declared in the assembly, to a method of the type, and to a parameter of the method. Different constructors are used for these cases. When executed, the assembly loads itself into the reflection-only context and displays the custom attributes. + + The attribute that is applied to the type demonstrates array properties, with both positional and named arguments. + + The property is used in the `ShowAttributeData` method that displays custom attribute data. In this code example, this property is used to display the list of arguments passed to the constructor that initialized the attribute. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/CustomAttributeData/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/CustomAttributeData/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/CustomAttributeData/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/CustomAttributeData/VB/source.vb" id="Snippet1"::: + ]]> @@ -422,7 +422,7 @@ System.Boolean - + An object to compare with this instance, or . @@ -485,33 +485,33 @@ System.Collections.Generic.IList<System.Reflection.CustomAttributeData> - + The assembly whose custom attribute data is to be retrieved. Returns a list of objects representing data about the attributes that have been applied to the target assembly. A list of objects that represent data about the attributes that have been applied to the target assembly. - method that can always be used in the Reflection-only context. - - - -## Examples - The following example defines a custom attribute with four constructors and four properties. Two of the properties are read-only, and are set by using the positional parameters of the constructors. The other two properties are read/write, and can be set only by using named arguments. One positional property is an array of strings, and one named property is an array of integers. - - The attribute is applied to the assembly, to a type declared in the assembly, to a method of the type, and to a parameter of the method. Different constructors are used for these cases. When executed, the assembly loads itself into the reflection-only context and displays the custom attributes. - - The attribute that is applied to the type demonstrates array properties, with both positional and named arguments. - - The method is used in `Main()` to get the custom attributes applied to the assembly. The return value of the method is passed to the `ShowAttributeData` method. - + method that can always be used in the Reflection-only context. + + + +## Examples + The following example defines a custom attribute with four constructors and four properties. Two of the properties are read-only, and are set by using the positional parameters of the constructors. The other two properties are read/write, and can be set only by using named arguments. One positional property is an array of strings, and one named property is an array of integers. + + The attribute is applied to the assembly, to a type declared in the assembly, to a method of the type, and to a parameter of the method. Different constructors are used for these cases. When executed, the assembly loads itself into the reflection-only context and displays the custom attributes. + + The attribute that is applied to the type demonstrates array properties, with both positional and named arguments. + + The method is used in `Main()` to get the custom attributes applied to the assembly. The return value of the method is passed to the `ShowAttributeData` method. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/CustomAttributeData/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/CustomAttributeData/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/CustomAttributeData/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/CustomAttributeData/VB/source.vb" id="Snippet1"::: + ]]> @@ -564,33 +564,33 @@ System.Collections.Generic.IList<System.Reflection.CustomAttributeData> - + The member whose attribute data is to be retrieved. Returns a list of objects representing data about the attributes that have been applied to the target member. A list of objects that represent data about the attributes that have been applied to the target member. - class and the classes in the namespace that represent type members all derive from . - - - -## Examples - The following example defines a custom attribute with four constructors and four properties. Two of the properties are read-only, and are set by using the positional parameters of the constructors. The other two properties are read/write, and can be set only by using named arguments. One positional property is an array of strings, and one named property is an array of integers. - - The attribute is applied to the assembly, to a type declared in the assembly, to a method of the type, and to a parameter of the method. Different constructors are used for these cases. When executed, the assembly loads itself into the reflection-only context and displays the custom attributes. - - The attribute that is applied to the type demonstrates array properties, with both positional and named arguments. - - The method is used in `Main()` to get the custom attributes that were applied to a type and to a test method ( derives from ). The return value of is passed to the `ShowAttributeData` method. - + class and the classes in the namespace that represent type members all derive from . + + + +## Examples + The following example defines a custom attribute with four constructors and four properties. Two of the properties are read-only, and are set by using the positional parameters of the constructors. The other two properties are read/write, and can be set only by using named arguments. One positional property is an array of strings, and one named property is an array of integers. + + The attribute is applied to the assembly, to a type declared in the assembly, to a method of the type, and to a parameter of the method. Different constructors are used for these cases. When executed, the assembly loads itself into the reflection-only context and displays the custom attributes. + + The attribute that is applied to the type demonstrates array properties, with both positional and named arguments. + + The method is used in `Main()` to get the custom attributes that were applied to a type and to a test method ( derives from ). The return value of is passed to the `ShowAttributeData` method. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/CustomAttributeData/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/CustomAttributeData/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/CustomAttributeData/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/CustomAttributeData/VB/source.vb" id="Snippet1"::: + ]]> @@ -644,7 +644,7 @@ System.Collections.Generic.IList<System.Reflection.CustomAttributeData> - + The module whose custom attribute data is to be retrieved. @@ -699,33 +699,33 @@ System.Collections.Generic.IList<System.Reflection.CustomAttributeData> - + The parameter whose attribute data is to be retrieved. Returns a list of objects representing data about the attributes that have been applied to the target parameter. A list of objects that represent data about the attributes that have been applied to the target parameter. - method that can always be used in the Reflection-only context. - - - -## Examples - The following example defines a custom attribute with four constructors and four properties. Two of the properties are read-only, and are set by using the positional parameters of the constructors. The other two properties are read/write, and can be set only by using named arguments. One positional property is an array of strings, and one named property is an array of integers. - - The attribute is applied to the assembly, to a type declared in the assembly, to a method of the type, and to a parameter of the method. Different constructors are used for these cases. When executed, the assembly loads itself into the reflection-only context and displays the custom attributes. - - The attribute that is applied to the type demonstrates array properties, with both positional and named arguments. - - The method is used in `Main()` to retrieve the custom attributes applied to a parameter of a test method. The return value of is passed to the `ShowAttributeData` method. - + method that can always be used in the Reflection-only context. + + + +## Examples + The following example defines a custom attribute with four constructors and four properties. Two of the properties are read-only, and are set by using the positional parameters of the constructors. The other two properties are read/write, and can be set only by using named arguments. One positional property is an array of strings, and one named property is an array of integers. + + The attribute is applied to the assembly, to a type declared in the assembly, to a method of the type, and to a parameter of the method. Different constructors are used for these cases. When executed, the assembly loads itself into the reflection-only context and displays the custom attributes. + + The attribute that is applied to the type demonstrates array properties, with both positional and named arguments. + + The method is used in `Main()` to retrieve the custom attributes applied to a parameter of a test method. The return value of is passed to the `ShowAttributeData` method. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/CustomAttributeData/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/CustomAttributeData/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/CustomAttributeData/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/CustomAttributeData/VB/source.vb" id="Snippet1"::: + ]]> @@ -824,30 +824,30 @@ Gets the list of named arguments specified for the attribute instance represented by the object. A collection of structures that represent the named arguments specified for the custom attribute instance. - method to get the positional arguments that were specified for the attribute instance. - - - -## Examples - The following example defines a custom attribute with four constructors and four properties. Two of the properties are read-only, and are set by using the positional parameters of the constructors. The other two properties are read/write, and can be set only by using named arguments. One positional property is an array of strings, and one named property is an array of integers. - - The attribute is applied to the assembly, to a type declared in the assembly, to a method of the type, and to a parameter of the method. Different constructors are used for these cases. When executed, the assembly loads itself into the reflection-only context and displays the custom attributes. - - The attribute that is applied to the type demonstrates array properties, with both positional and named arguments. - - The property is used in the `ShowAttributeData` method that displays custom attribute data. In this code example, this property is used to display the list of named arguments specified for the attribute. - + method to get the positional arguments that were specified for the attribute instance. + + + +## Examples + The following example defines a custom attribute with four constructors and four properties. Two of the properties are read-only, and are set by using the positional parameters of the constructors. The other two properties are read/write, and can be set only by using named arguments. One positional property is an array of strings, and one named property is an array of integers. + + The attribute is applied to the assembly, to a type declared in the assembly, to a method of the type, and to a parameter of the method. Different constructors are used for these cases. When executed, the assembly loads itself into the reflection-only context and displays the custom attributes. + + The attribute that is applied to the type demonstrates array properties, with both positional and named arguments. + + The property is used in the `ShowAttributeData` method that displays custom attribute data. In this code example, this property is used to display the list of named arguments specified for the attribute. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/CustomAttributeData/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/CustomAttributeData/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/CustomAttributeData/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/CustomAttributeData/VB/source.vb" id="Snippet1"::: + ]]> @@ -896,26 +896,26 @@ Returns a string representation of the custom attribute. A string value that represents the custom attribute. - method is used in the `ShowAttributeData` method, to identify the attribute whose data is being displayed. - + method is used in the `ShowAttributeData` method, to identify the attribute whose data is being displayed. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/CustomAttributeData/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/CustomAttributeData/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/CustomAttributeData/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/CustomAttributeData/VB/source.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.Reflection/CustomAttributeNamedArgument.xml b/xml/System.Reflection/CustomAttributeNamedArgument.xml index e150116c6c3..218cbba9429 100644 --- a/xml/System.Reflection/CustomAttributeNamedArgument.xml +++ b/xml/System.Reflection/CustomAttributeNamedArgument.xml @@ -88,31 +88,31 @@ Represents a named argument of a custom attribute in the reflection-only context. - , , and so on. If the code for the attribute type itself is loaded into the reflection-only context, it cannot be executed. - - The structure is used by the class to provide access to a named argument specified for a custom attribute instance, without executing the code of the corresponding property of the custom attribute type. The property returns a structure that contains the type and value of the named argument. - + , , and so on. If the code for the attribute type itself is loaded into the reflection-only context, it cannot be executed. + + The structure is used by the class to provide access to a named argument specified for a custom attribute instance, without executing the code of the corresponding property of the custom attribute type. The property returns a structure that contains the type and value of the named argument. + > [!IMPORTANT] -> Whether an argument is named or positional, you must access its type and value by using the structure. - - To create instances of the class, use the `static` factory method. - - - -## Examples - The following example defines a custom attribute with four constructors and four properties. Two of the properties are read-only, and are set by using the positional parameters of the constructors. The other two properties are read/write, and can be set only by using named arguments. One positional property is an array of strings, and one named property is an array of integers. - - The attribute is applied to the assembly, to a type declared in the assembly, to a method of the type, and to a parameter of the method. Different constructors are used for these cases. When executed, the assembly loads itself into the reflection-only context and displays information about the custom attributes that were applied to it and to the type and members it contains. - - The attribute that is applied to the type demonstrates array properties, with both positional and named arguments. - +> Whether an argument is named or positional, you must access its type and value by using the structure. + + To create instances of the class, use the `static` factory method. + + + +## Examples + The following example defines a custom attribute with four constructors and four properties. Two of the properties are read-only, and are set by using the positional parameters of the constructors. The other two properties are read/write, and can be set only by using named arguments. One positional property is an array of strings, and one named property is an array of integers. + + The attribute is applied to the assembly, to a type declared in the assembly, to a method of the type, and to a parameter of the method. Different constructors are used for these cases. When executed, the assembly loads itself into the reflection-only context and displays information about the custom attributes that were applied to it and to the type and members it contains. + + The attribute that is applied to the type demonstrates array properties, with both positional and named arguments. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/CustomAttributeData/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/CustomAttributeData/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/CustomAttributeData/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/CustomAttributeData/VB/source.vb" id="Snippet1"::: + ]]> @@ -164,8 +164,8 @@ System.Reflection - - + + [System.Runtime.CompilerServices.Nullable(2)] @@ -179,11 +179,11 @@ The value of the field or property of the custom attribute. Initializes a new instance of the class, which represents the specified field or property of the custom attribute, and specifies the value of the field or property. - class. It is not intended for use in application code. - + class. It is not intended for use in application code. + ]]> @@ -225,19 +225,19 @@ System.Reflection - - + + A field or property of the custom attribute. The new object represents this member and its value. An object that describes the type and value of the field or property. Initializes a new instance of the class, which represents the specified field or property of the custom attribute, and specifies a object that describes the type and value of the field or property. - class. It is not intended for use in application code. - + class. It is not intended for use in application code. + ]]> @@ -289,7 +289,7 @@ System.Boolean - + [System.Diagnostics.CodeAnalysis.NotNullWhen(true)] @@ -475,11 +475,11 @@ Gets the attribute member that would be used to set the named argument. The attribute member that would be used to set the named argument. - @@ -566,8 +566,8 @@ System.Boolean - - + + The structure to the left of the equality operator. @@ -618,8 +618,8 @@ System.Boolean - - + + The structure to the left of the inequality operator. @@ -719,26 +719,26 @@ Gets a structure that can be used to obtain the type and value of the current named argument. A structure that can be used to obtain the type and value of the current named argument. - structure only contains information about how the argument value was set. Use this property to obtain a structure that contains the type and value. - - - -## Examples - The following code example defines a custom attribute with four constructors and four properties. Two of the properties are read-only, and are set by using the positional parameters of the constructors. The other two properties are read/write, and can be set only by using named arguments. One positional property is an array of strings, and one named property is an array of integers. - - The attribute is applied to the assembly, to a type declared in the assembly, to a method of the type, and to a parameter of the method. Different constructors are used for these cases. When executed, the assembly loads itself into the reflection-only context and displays the custom attributes. - - The attribute that is applied to the type demonstrates array properties, with both positional and named arguments. - - The property is used in the `ShowAttributeData` method that displays custom attribute data, to obtain the types and values of named attributes. - + structure only contains information about how the argument value was set. Use this property to obtain a structure that contains the type and value. + + + +## Examples + The following code example defines a custom attribute with four constructors and four properties. Two of the properties are read-only, and are set by using the positional parameters of the constructors. The other two properties are read/write, and can be set only by using named arguments. One positional property is an array of strings, and one named property is an array of integers. + + The attribute is applied to the assembly, to a type declared in the assembly, to a method of the type, and to a parameter of the method. Different constructors are used for these cases. When executed, the assembly loads itself into the reflection-only context and displays the custom attributes. + + The attribute that is applied to the type demonstrates array properties, with both positional and named arguments. + + The property is used in the `ShowAttributeData` method that displays custom attribute data, to obtain the types and values of named attributes. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/CustomAttributeData/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/CustomAttributeData/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/CustomAttributeData/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/CustomAttributeData/VB/source.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.Reflection/CustomAttributeTypedArgument.xml b/xml/System.Reflection/CustomAttributeTypedArgument.xml index 5fd7d251862..f4ee76e82b0 100644 --- a/xml/System.Reflection/CustomAttributeTypedArgument.xml +++ b/xml/System.Reflection/CustomAttributeTypedArgument.xml @@ -88,32 +88,32 @@ Represents an argument of a custom attribute in the reflection-only context, or an element of an array argument. - , , and so on. If the code for the attribute type itself is loaded into the reflection-only context, it cannot be executed. - - The structure is used by the class to provide access to the type and value of a positional argument specified for a custom attribute instance, without executing the attribute constructor. It also provides access to the type and value of a named argument without executing the code of the corresponding property of the custom attribute type. - - The types and values of all the positional and named arguments of an attribute instance are provided by structures. The positional attributes returned by the property are directly represented by structures, but the named arguments returned by the property are represented by structures; to get the structure for a named argument, use the property. - - If an argument is an array of values, the property of the that represents the argument returns a generic of objects. Each object in the collection represents the corresponding element of the array. - - To create instances of the class, use the `static` factory method. - - - -## Examples - The following example defines a custom attribute with four constructors and four properties. Two of the properties are read-only, and are set by using the positional parameters of the constructors. The other two properties are read/write, and can be set only by using named arguments. One positional property is an array of strings, and one named property is an array of integers. - - The attribute is applied to the assembly, to a type declared in the assembly, to a method of the type, and to a parameter of the method. Different constructors are used for these cases. When executed, the assembly loads itself into the reflection-only context and displays the custom attributes. - - The attribute that is applied to the type demonstrates array properties, with both positional and named arguments. - + , , and so on. If the code for the attribute type itself is loaded into the reflection-only context, it cannot be executed. + + The structure is used by the class to provide access to the type and value of a positional argument specified for a custom attribute instance, without executing the attribute constructor. It also provides access to the type and value of a named argument without executing the code of the corresponding property of the custom attribute type. + + The types and values of all the positional and named arguments of an attribute instance are provided by structures. The positional attributes returned by the property are directly represented by structures, but the named arguments returned by the property are represented by structures; to get the structure for a named argument, use the property. + + If an argument is an array of values, the property of the that represents the argument returns a generic of objects. Each object in the collection represents the corresponding element of the array. + + To create instances of the class, use the `static` factory method. + + + +## Examples + The following example defines a custom attribute with four constructors and four properties. Two of the properties are read-only, and are set by using the positional parameters of the constructors. The other two properties are read/write, and can be set only by using named arguments. One positional property is an array of strings, and one named property is an array of integers. + + The attribute is applied to the assembly, to a type declared in the assembly, to a method of the type, and to a parameter of the method. Different constructors are used for these cases. When executed, the assembly loads itself into the reflection-only context and displays the custom attributes. + + The attribute that is applied to the type demonstrates array properties, with both positional and named arguments. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/CustomAttributeData/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/CustomAttributeData/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/CustomAttributeData/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/CustomAttributeData/VB/source.vb" id="Snippet1"::: + ]]> @@ -164,19 +164,19 @@ System.Reflection - + The value of the custom attribute argument. Initializes a new instance of the class with the specified value. - constructor. - - This constructor is for use by inheritors of the class. It is not intended for use in application code. - + constructor. + + This constructor is for use by inheritors of the class. It is not intended for use in application code. + ]]> @@ -184,12 +184,12 @@ - - - - - - + + + + + + Constructor @@ -217,8 +217,8 @@ System.Reflection - - + + [System.Runtime.CompilerServices.Nullable(2)] @@ -232,11 +232,11 @@ The value of the custom attribute argument. Initializes a new instance of the class with the specified type and value. - class. It is not intended for use in application code. - + class. It is not intended for use in application code. + ]]> @@ -286,26 +286,26 @@ Gets the type of the argument or of the array argument element. A object representing the type of the argument or of the array element. - property. For array arguments, this property returns the array type, but the property returns a `ReadOnlyCollection` (`ReadOnlyCollection(Of CustomAttributeTypedArgument)` in Visual Basic) in which each element of the collection represents the corresponding element of the array argument. - - - -## Examples - The following example defines a custom attribute with four constructors and four properties. Two of the properties are read-only, and are set by using the positional parameters of the constructors. The other two properties are read/write, and can be set only by using named arguments. One positional property is an array of strings, and one named property is an array of integers. - - The attribute is applied to the assembly, to a type declared in the assembly, to a method of the type, and to a parameter of the method. Different constructors are used for these cases. When executed, the assembly loads itself into the reflection-only context and displays the custom attributes. - - The attribute that is applied to the type demonstrates array properties, with both positional and named arguments. - - The property is used in the `ShowValueOrArray` method that displays custom attribute data, to display the types of attributes. - + property. For array arguments, this property returns the array type, but the property returns a `ReadOnlyCollection` (`ReadOnlyCollection(Of CustomAttributeTypedArgument)` in Visual Basic) in which each element of the collection represents the corresponding element of the array argument. + + + +## Examples + The following example defines a custom attribute with four constructors and four properties. Two of the properties are read-only, and are set by using the positional parameters of the constructors. The other two properties are read/write, and can be set only by using named arguments. One positional property is an array of strings, and one named property is an array of integers. + + The attribute is applied to the assembly, to a type declared in the assembly, to a method of the type, and to a parameter of the method. Different constructors are used for these cases. When executed, the assembly loads itself into the reflection-only context and displays the custom attributes. + + The attribute that is applied to the type demonstrates array properties, with both positional and named arguments. + + The property is used in the `ShowValueOrArray` method that displays custom attribute data, to display the types of attributes. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/CustomAttributeData/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/CustomAttributeData/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/CustomAttributeData/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/CustomAttributeData/VB/source.vb" id="Snippet1"::: + ]]> @@ -357,7 +357,7 @@ System.Boolean - + [System.Diagnostics.CodeAnalysis.NotNullWhen(true)] @@ -504,8 +504,8 @@ System.Boolean - - + + The structure to the left of the equality operator. @@ -556,8 +556,8 @@ System.Boolean - - + + The structure to the left of the inequality operator. @@ -668,30 +668,30 @@ Gets the value of the argument for a simple argument or for an element of an array argument; gets a collection of values for an array argument. An object that represents the value of the argument or element, or a generic of objects that represent the values of an array-type argument. - represents an array argument, this property returns a `ReadOnlyCollection` (`ReadOnlyCollection(Of CustomAttributeTypedArgument)` in Visual Basic). Each element of the collection represents the corresponding element of the array argument. - - The type of the value can be obtained by using the property. gets the actual type of the value returned by the property for simple arguments or for elements of array arguments. It returns the array type for array arguments. - - - -## Examples - The following example defines a custom attribute with four constructors and four properties. Two of the properties are read-only, and are set by using the positional parameters of the constructors. The other two properties are read/write, and can be set only by using named arguments. One positional property is an array of strings, and one named property is an array of integers. - - The attribute is applied to the assembly, to a type declared in the assembly, to a method of the type, and to a parameter of the method. Different constructors are used for these cases. When executed, the assembly loads itself into the reflection-only context and displays the custom attributes. - - The attribute that is applied to the type demonstrates array properties, with both positional and named arguments. - - The property is used in the `ShowValueOrArray` method that displays custom attribute data, to display the values of attributes. - + represents an array argument, this property returns a `ReadOnlyCollection` (`ReadOnlyCollection(Of CustomAttributeTypedArgument)` in Visual Basic). Each element of the collection represents the corresponding element of the array argument. + + The type of the value can be obtained by using the property. gets the actual type of the value returned by the property for simple arguments or for elements of array arguments. It returns the array type for array arguments. + + + +## Examples + The following example defines a custom attribute with four constructors and four properties. Two of the properties are read-only, and are set by using the positional parameters of the constructors. The other two properties are read/write, and can be set only by using named arguments. One positional property is an array of strings, and one named property is an array of integers. + + The attribute is applied to the assembly, to a type declared in the assembly, to a method of the type, and to a parameter of the method. Different constructors are used for these cases. When executed, the assembly loads itself into the reflection-only context and displays the custom attributes. + + The attribute that is applied to the type demonstrates array properties, with both positional and named arguments. + + The property is used in the `ShowValueOrArray` method that displays custom attribute data, to display the values of attributes. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/CustomAttributeData/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/CustomAttributeData/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/CustomAttributeData/VB/source.vb" id="Snippet1"::: - - | - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/CustomAttributeData/VB/source.vb" id="Snippet1"::: + + | + ]]> diff --git a/xml/System.Reflection/EventInfo.xml b/xml/System.Reflection/EventInfo.xml index 8487b705c2f..f4683fd98fe 100644 --- a/xml/System.Reflection/EventInfo.xml +++ b/xml/System.Reflection/EventInfo.xml @@ -93,31 +93,31 @@ Discovers the attributes of an event and provides access to event metadata. - class to inspect events and to hook up event handlers, as shown in the example code for the method. - + class to inspect events and to hook up event handlers, as shown in the example code for the method. + > [!NOTE] -> is not intended to be used to raise events. An object raises events as dictated by its internal state. - - Events are used with delegates. An event listener instantiates an event-handler delegate that is invoked whenever the event is raised by an event source. In order to connect to the event source, the event listener adds this delegate to the invocation list on the source. When the event is raised, the invoke method of the event-handler delegate is called. Both multicast and single-cast event notifications are supported. The `Add` and `Remove` methods, as well as the event-handler delegate class associated with an event, must be marked in the metadata. - - Delegates are object-oriented function pointers. In C or C++, a function pointer is a reference to a method. In contrast to the C or C++ function pointer, a delegate contains two references: a reference to a method and a reference to an object that supports the method. Delegates can invoke a method without knowing the class type that declares or inherits the method. Delegates need only know the return type and parameter list of the method. - - The event model works equally well for single-cast and multicast delegates. When the delegate's invoke method is called, only a single object will have a method called on it. A multicast modifier can be applied to a delegate declaration, which allows multiple methods to be called when the invoke method of the delegate is called. - - Calling on `EventInfo` when the `inherit` parameter of `GetCustomAttributes` is `true` does not walk the type hierarchy. Use to inherit custom attributes. - - - -## Examples - The following code gets an object for the event of the class. - +> is not intended to be used to raise events. An object raises events as dictated by its internal state. + + Events are used with delegates. An event listener instantiates an event-handler delegate that is invoked whenever the event is raised by an event source. In order to connect to the event source, the event listener adds this delegate to the invocation list on the source. When the event is raised, the invoke method of the event-handler delegate is called. Both multicast and single-cast event notifications are supported. The `Add` and `Remove` methods, as well as the event-handler delegate class associated with an event, must be marked in the metadata. + + Delegates are object-oriented function pointers. In C or C++, a function pointer is a reference to a method. In contrast to the C or C++ function pointer, a delegate contains two references: a reference to a method and a reference to an object that supports the method. Delegates can invoke a method without knowing the class type that declares or inherits the method. Delegates need only know the return type and parameter list of the method. + + The event model works equally well for single-cast and multicast delegates. When the delegate's invoke method is called, only a single object will have a method called on it. A multicast modifier can be applied to a delegate declaration, which allows multiple methods to be called when the invoke method of the delegate is called. + + Calling on `EventInfo` when the `inherit` parameter of `GetCustomAttributes` is `true` does not walk the type hierarchy. Use to inherit custom attributes. + + + +## Examples + The following code gets an object for the event of the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/type_getevent1/CPP/type_getevent1.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System/Type/GetEvent/type_getevent1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/type_getevent1/VB/type_getevent1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/type_getevent1/VB/type_getevent1.vb" id="Snippet1"::: + ]]> This type is thread safe. @@ -127,11 +127,11 @@ - - - - - + + + + + Constructor mscorlib @@ -226,27 +226,27 @@ Encapsulates a method or methods to be invoked when the event is raised by the target. Adds an event handler to an event source. - class, creates an event handler using a dynamic assembly, and hooks up the dynamic event handler. All actions are performed using late binding. - - The instance is stored in a variable of type , and all code that accesses the does so late-bound. The example uses the method to get the event, and the property to get the delegate type for the event. - - The example gets a for the `Invoke` method of the delegate type and obtains the signature of the delegate from the instance. The example then creates a dynamic assembly with one module containing a single type named `Handler` and gives the type a `static` method (`Shared` method in Visual Basic) named `DynamicHandler` that handles the event. - - After the dynamic type is created, the example gets a for the finished method and uses it to create a delegate instance. This instance is passed to the method to hook up the event. The program then pauses to allow the event to be raised. - + class, creates an event handler using a dynamic assembly, and hooks up the dynamic event handler. All actions are performed using late binding. + + The instance is stored in a variable of type , and all code that accesses the does so late-bound. The example uses the method to get the event, and the property to get the delegate type for the event. + + The example gets a for the `Invoke` method of the delegate type and obtains the signature of the delegate from the instance. The example then creates a dynamic assembly with one module containing a single type named `Handler` and gives the type a `static` method (`Shared` method in Visual Basic) named `DynamicHandler` that handles the event. + + After the dynamic type is created, the example gets a for the finished method and uses it to create a delegate instance. This instance is passed to the method to hook up the event. The program then pauses to allow the event to be raised. + :::code language="csharp" source="~/snippets/csharp/System.Reflection/EventInfo/AddEventHandler/source.cs"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/AddEventHandler/vb/source.vb"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/AddEventHandler/vb/source.vb"::: + ]]> The event does not have a public accessor. @@ -255,10 +255,10 @@ You might use the `AddEventHandler` method when you load a type after the progra Note: In .NET for Windows Store apps or the Portable Class Library, catch the base class exception, , instead. - The parameter is and the event is not static. - - -or- - + The parameter is and the event is not static. + + -or- + The is not declared on the target. Note: In .NET for Windows Store apps or the Portable Class Library, catch instead. @@ -311,11 +311,11 @@ Note: In object for the method of the event, including non-public methods. The object for the method. - with a value of `true`. - + with a value of `true`. + ]]> @@ -367,11 +367,11 @@ Note: In @@ -480,17 +480,17 @@ Note: In object of the underlying event-handler delegate associated with this event. A read-only object representing the delegate event handler. - property to discover the delegate type of an event and to display its parameter types. - - The example defines a delegate named `MyDelegate` and an event named `ev` of type `MyDelegate`. The code in the `Main` method discovers the event signature by getting the delegate type of the event, getting the `Invoke` method of the delegate type, and then retrieving and displaying the parameters. - + property to discover the delegate type of an event and to display its parameter types. + + The example defines a delegate named `MyDelegate` and an event named `ev` of type `MyDelegate`. The code in the `Main` method discovers the event signature by getting the delegate type of the event, getting the `Invoke` method of the delegate type, and then retrieving and displaying the parameters. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/EventArg/CPP/eventarg.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/EventInfo/EventHandlerType/eventarg.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/EventArg/VB/eventarg.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/EventArg/VB/eventarg.vb" id="Snippet1"::: + ]]> The caller does not have the required permission. @@ -558,20 +558,20 @@ Note: In object representing the method used to add an event handler delegate to the event source. - ( handler) -``` - + ( handler) +``` + ]]> @@ -620,7 +620,7 @@ add_( handler) System.Reflection.MethodInfo - + @@ -628,20 +628,20 @@ add_( handler) When overridden in a derived class, retrieves the object for the method of the event, specifying whether to return non-public methods. A object representing the method used to add an event handler delegate to the event source. - ( handler) -``` - + ( handler) +``` + ]]> @@ -754,21 +754,21 @@ add_( handler) Returns the public methods that have been associated with an event in metadata using the directive. An array representing the public methods that have been associated with the event in metadata by using the directive. If there are no such public methods, an empty array is returned. - method to retrieve an for that method. - -- The `.removeon` directive specifies the method used to detach event handlers. Use the method to retrieve an for that method. - -- The `.fire` directive specifies the method used to raise the event. Use the method to retrieve an for that method. - -- The `.other` directive specifies any other methods associated with the event. Use the method to retrieve an array of objects for those methods. - - The methods associated with an event using the `.other` directive have no special significance to the runtime. The C# and Visual Basic compilers do not use the `.other` directive. - + method to retrieve an for that method. + +- The `.removeon` directive specifies the method used to detach event handlers. Use the method to retrieve an for that method. + +- The `.fire` directive specifies the method used to raise the event. Use the method to retrieve an for that method. + +- The `.other` directive specifies any other methods associated with the event. Use the method to retrieve an array of objects for those methods. + + The methods associated with an event using the `.other` directive have no special significance to the runtime. The C# and Visual Basic compilers do not use the `.other` directive. + ]]> @@ -816,7 +816,7 @@ add_( handler) System.Reflection.MethodInfo[] - + @@ -824,21 +824,21 @@ add_( handler) Returns the methods that have been associated with the event in metadata using the directive, specifying whether to include non-public methods. An array representing methods that have been associated with an event in metadata by using the directive. If there are no methods matching the specification, an empty array is returned. - method to retrieve an for that method. - -- The `.removeon` directive specifies the method used to detach event handlers. Use the method to retrieve an for this method. - -- The `.fire` directive specifies the method used to raise the event. Use the method to retrieve an for this method. - -- The `.other` directive specifies any other methods associated with the event. Use the method to retrieve an array of objects for those methods. - - The methods associated with an event using the `.other` directive have no special significance to the runtime. The C# and Visual Basic compilers do not use the `.other` directive. - + method to retrieve an for that method. + +- The `.removeon` directive specifies the method used to detach event handlers. Use the method to retrieve an for this method. + +- The `.fire` directive specifies the method used to raise the event. Use the method to retrieve an for this method. + +- The `.other` directive specifies any other methods associated with the event. Use the method to retrieve an array of objects for those methods. + + The methods associated with an event using the `.other` directive have no special significance to the runtime. The C# and Visual Basic compilers do not use the `.other` directive. + ]]> This method is not implemented. @@ -903,11 +903,11 @@ add_( handler) Returns the method that is called when the event is raised. The method that is called when the event is raised. - @@ -956,7 +956,7 @@ add_( handler) System.Reflection.MethodInfo - + @@ -964,11 +964,11 @@ add_( handler) When overridden in a derived class, returns the method that is called when the event is raised, specifying whether to return non-public methods. A object that was called when the event was raised. - @@ -1035,15 +1035,15 @@ add_( handler) Returns the method used to remove an event handler delegate from the event source. A object representing the method used to remove an event handler delegate from the event source. - ( handler) -``` - + ( handler) +``` + ]]> @@ -1092,7 +1092,7 @@ remove_( handler) System.Reflection.MethodInfo - + @@ -1100,15 +1100,15 @@ remove_( handler) When overridden in a derived class, retrieves the object for removing a method of the event, specifying whether to return non-public methods. A object representing the method used to remove an event handler delegate from the event source. - ( handler) -``` - + ( handler) +``` + ]]> @@ -1253,11 +1253,11 @@ remove_( handler) if this event has a special name; otherwise, . - @@ -1308,11 +1308,11 @@ remove_( handler) Gets a value indicating that this member is an event. A value indicating that this member is an event. - . Therefore, when you examine a set of objects - for example, the array returned by - the property returns only when a given member is an event. - + . Therefore, when you examine a set of objects - for example, the array returned by - the property returns only when a given member is an event. + ]]> @@ -1355,8 +1355,8 @@ remove_( handler) System.Boolean - - + + The first object to compare. @@ -1404,8 +1404,8 @@ remove_( handler) System.Boolean - - + + The first object to compare. @@ -1459,11 +1459,11 @@ remove_( handler) Gets the method that is called when the event is raised, including non-public methods. The method that is called when the event is raised. - with a value of `true`. - + with a value of `true`. + ]]> @@ -1529,21 +1529,21 @@ remove_( handler) The delegate to be disassociated from the events raised by target. Removes an event handler from an event source. - The event does not have a public accessor. The handler that was passed in cannot be used. - The parameter is and the event is not static. - - -or- - + The parameter is and the event is not static. + + -or- + The is not declared on the target. Note: In .NET for Windows Store apps or the Portable Class Library, catch instead. @@ -1600,11 +1600,11 @@ Note: In object for removing a method of the event, including non-public methods. The object for removing a method of the event. - with a value of `true`. - + with a value of `true`. + ]]> @@ -1639,11 +1639,11 @@ Note: In - - - - + + + + + Reserved for future use. Must be IID_NULL. @@ -1653,11 +1653,11 @@ Note: In Caller-allocated array which receives the IDs corresponding to the names. Maps a set of names to a corresponding set of dispatch identifiers. - Late-bound access using the COM IDispatch interface is not supported. @@ -1728,9 +1728,9 @@ Note: In - - + + + The type information to return. @@ -1738,11 +1738,11 @@ Note: In Receives a pointer to the requested type information object. Retrieves the type information for an object, which can then be used to get the type information for an interface. - Late-bound access using the COM IDispatch interface is not supported. @@ -1778,17 +1778,17 @@ Note: In + Points to a location that receives the number of type information interfaces provided by the object. Retrieves the number of type information interfaces that an object provides (either 0 or 1). - Late-bound access using the COM IDispatch interface is not supported. @@ -1824,14 +1824,14 @@ Note: In - - - - - - - + + + + + + + + Identifies the member. @@ -1844,11 +1844,11 @@ Note: In The index of the first argument that has an error. Provides access to properties and methods exposed by an object. - Late-bound access using the COM IDispatch interface is not supported. diff --git a/xml/System.Reflection/FieldInfo.xml b/xml/System.Reflection/FieldInfo.xml index de734ce78f6..8dbbf5c4cce 100644 --- a/xml/System.Reflection/FieldInfo.xml +++ b/xml/System.Reflection/FieldInfo.xml @@ -92,22 +92,22 @@ Discovers the attributes of a field and provides access to field metadata. - class does not have a public constructor. objects are obtained by calling either the or method of a `Type` object. - - Fields are variables defined in the class. provides access to the metadata for a field within a class and provides dynamic set and get functionality for the field. The class is not loaded into memory until invoke or get is called on the object. - - - -## Examples - The following example uses the method to get the field-related information from the class, and then displays field attributes. - + class does not have a public constructor. objects are obtained by calling either the or method of a `Type` object. + + Fields are variables defined in the class. provides access to the metadata for a field within a class and provides dynamic set and get functionality for the field. The class is not loaded into memory until invoke or get is called on the object. + + + +## Examples + The following example uses the method to get the field-related information from the class, and then displays field attributes. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/FieldInfo/CPP/fieldinfo.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/FieldInfo/Overview/fieldinfo.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/FieldInfo/VB/fieldinfo.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/FieldInfo/VB/fieldinfo.vb" id="Snippet1"::: + ]]> This type is thread safe. @@ -118,11 +118,11 @@ - - - - - + + + + + Constructor mscorlib @@ -203,22 +203,22 @@ Gets the attributes associated with this field. The for this field. - @@ -328,20 +328,20 @@ Gets a , which is a handle to the internal metadata representation of a field. A handle to the internal metadata representation of a field. - @@ -393,22 +393,22 @@ Gets the type of this field object. The type of this field object. - , and displays its . - + , and displays its . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic FieldInfo.FieldType Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/FieldInfo/FieldType/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic FieldInfo.FieldType Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic FieldInfo.FieldType Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -480,20 +480,20 @@ Gets a for the field represented by the specified handle. A object representing the field specified by . - method to get objects for the fields of a type, gets a structure for each field, and then retrieves the objects from the handles using this overload of the method. - + method to get objects for the fields of a type, gets a structure for each field, and then retrieves the objects from the handles using this overload of the method. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/FieldInfo_GetFieldFromHandle/CPP/fieldinfo_getfieldfromhandle.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/FieldInfo/GetFieldFromHandle/fieldinfo_getfieldfromhandle.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/FieldInfo_GetFieldFromHandle/VB/fieldinfo_getfieldfromhandle.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/FieldInfo_GetFieldFromHandle/VB/fieldinfo_getfieldfromhandle.vb" id="Snippet1"::: + ]]> @@ -559,40 +559,40 @@ Gets a for the field represented by the specified handle, for the specified generic type. A object representing the field specified by , in the generic type specified by . - ` (`MyType(Of Integer)` in Visual Basic), `declaringType` is the runtime type handle for `MyType`. Do not use the runtime type handle of the generic type definition, unless the runtime field handle represents a field on the generic type definition. - - Implementations are compatible in some cases. For example, a single implementation is shared by all types that are constructed from a particular generic type definition by using reference types for the generic type arguments. For example, `MyType`, `MyType`, and `MyType` all share the same implementation. In this situation, the object that is returned represents a field on the type that `declaringType` specifies, regardless of the original source of `handle`. This practice is not recommended, because it works only if the generic type arguments of the constructed type are reference types. - - If a generic argument is a value type, the runtime type handle of the constructed type is not compatible with runtime field handles from constructions that have a reference type in the same generic parameter position, or that have a different value type in that position. In that case, the only way to use the overload is to ensure that `declaringType` is the runtime type handle for the constructed type that `handle` belongs to. - - - -## Examples - The following example shows how to retrieve objects for fields on constructed generic classes. The example defines the generic type `Test` (`Test(Of T)` in Visual Basic) with a single field named `TestField`, of type `T`. The example gets the and for the case where `T` is , and demonstrates the following: - -- An exception is thrown if the method overload is used. This is true even if the field is not of type `T`. - -- A is retrieved successfully if the runtime type handle is from the same construction as the runtime field handle, in this case `Test`. - -- If the runtime type handle is from a compatible construction, in this case `Test`, a for the field on the compatible construction is retrieved. - -- If the runtime type handle is not from a compatible construction, an exception is thrown. In this case, a value type is specified for `T`. - + ` (`MyType(Of Integer)` in Visual Basic), `declaringType` is the runtime type handle for `MyType`. Do not use the runtime type handle of the generic type definition, unless the runtime field handle represents a field on the generic type definition. + + Implementations are compatible in some cases. For example, a single implementation is shared by all types that are constructed from a particular generic type definition by using reference types for the generic type arguments. For example, `MyType`, `MyType`, and `MyType` all share the same implementation. In this situation, the object that is returned represents a field on the type that `declaringType` specifies, regardless of the original source of `handle`. This practice is not recommended, because it works only if the generic type arguments of the constructed type are reference types. + + If a generic argument is a value type, the runtime type handle of the constructed type is not compatible with runtime field handles from constructions that have a reference type in the same generic parameter position, or that have a different value type in that position. In that case, the only way to use the overload is to ensure that `declaringType` is the runtime type handle for the constructed type that `handle` belongs to. + + + +## Examples + The following example shows how to retrieve objects for fields on constructed generic classes. The example defines the generic type `Test` (`Test(Of T)` in Visual Basic) with a single field named `TestField`, of type `T`. The example gets the and for the case where `T` is , and demonstrates the following: + +- An exception is thrown if the method overload is used. This is true even if the field is not of type `T`. + +- A is retrieved successfully if the runtime type handle is from the same construction as the runtime field handle, in this case `Test`. + +- If the runtime type handle is from a compatible construction, in this case `Test`, a for the field on the compatible construction is retrieved. + +- If the runtime type handle is not from a compatible construction, an exception is thrown. In this case, a value type is specified for `T`. + :::code language="csharp" source="~/snippets/csharp/System.Reflection/FieldInfo/GetFieldFromHandle/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/FieldInfo_GetFieldFromHandle2/vb/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/FieldInfo_GetFieldFromHandle2/vb/source.vb" id="Snippet1"::: + ]]> - is invalid. - - -or- - + is invalid. + + -or- + is not compatible with . For example, is the runtime type handle of the generic type definition, and comes from a constructed type. @@ -674,15 +674,15 @@ Gets the modified type of this field object. A modified type. - , and which are used to obtain custom modifiers from a function pointer. To obtain the normal, unmodified type from a modified type, use . - This method is provided for designers of managed compilers. For more information on custom modifiers, see classes in the namespace. Also see the metadata specification in Partition II of the [Common Language Infrastructure (CLI) documentation](https://www.ecma-international.org/publications-and-standards/standards/ecma-335/). - + This method is provided for designers of managed compilers. For more information on custom modifiers, see classes in the namespace. Also see the metadata specification in Partition II of the [Common Language Infrastructure (CLI) documentation](https://www.ecma-international.org/publications-and-standards/standards/ecma-335/). + ]]> @@ -733,11 +733,11 @@ Gets an array of types that identify the optional custom modifiers of the field. An array of objects that identify the optional custom modifiers of the current field, such as . - and methods are provided for designers of managed compilers. For more information on custom modifiers, see and related classes in the namespace. Also see the metadata specification in Partition II of the [Common Language Infrastructure (CLI) documentation](https://www.ecma-international.org/publications-and-standards/standards/ecma-335/). - + and methods are provided for designers of managed compilers. For more information on custom modifiers, see and related classes in the namespace. Also see the metadata specification in Partition II of the [Common Language Infrastructure (CLI) documentation](https://www.ecma-international.org/publications-and-standards/standards/ecma-335/). + ]]> @@ -791,18 +791,18 @@ Returns a literal value associated with the field by a compiler. An that contains the literal value associated with the field. If the literal value is a class type with an element value of zero, the return value is . - [!NOTE] -> For more information on constant values and the Constant table, see Partition II of the [Common Language Infrastructure (CLI) documentation](https://www.ecma-international.org/publications-and-standards/standards/ecma-335/). - +> For more information on constant values and the Constant table, see Partition II of the [Common Language Infrastructure (CLI) documentation](https://www.ecma-international.org/publications-and-standards/standards/ecma-335/). + ]]> The Constant table in unmanaged metadata does not contain a constant value for the current field. @@ -852,11 +852,11 @@ Gets an array of types that identify the required custom modifiers of the property. An array of objects that identify the required custom modifiers of the current property, such as or . - and methods are provided for designers of managed compilers. For more information on custom modifiers, see and related classes in the namespace. Also see the metadata specification in Partition II of the [Common Language Infrastructure (CLI) documentation](https://www.ecma-international.org/publications-and-standards/standards/ecma-335/). - + and methods are provided for designers of managed compilers. For more information on custom modifiers, see and related classes in the namespace. Also see the metadata specification in Partition II of the [Common Language Infrastructure (CLI) documentation](https://www.ecma-international.org/publications-and-standards/standards/ecma-335/). + ]]> @@ -953,34 +953,34 @@ When overridden in a derived class, returns the value of a field supported by a given object. An object containing the value of the field reflected by this instance. - [!NOTE] -> Access restrictions are ignored for fully trusted code. That is, private constructors, methods, fields, and properties can be accessed and invoked through reflection whenever the code is fully trusted. - +> Access restrictions are ignored for fully trusted code. That is, private constructors, methods, fields, and properties can be accessed and invoked through reflection whenever the code is fully trusted. + > [!NOTE] -> Starting with the .NET Framework 2.0 Service Pack 1, this method can be used to access non-public members if the caller has been granted with the flag and if the grant set of the non-public members is restricted to the caller's grant set, or a subset thereof. (See [Security Considerations for Reflection](/dotnet/framework/reflection-and-codedom/security-considerations-for-reflection).) -> -> To use this functionality, your application should target the .NET Framework 3.5 or later. - - - -## Examples - The following example uses the method to retrieve the value of a static field. Note that the value of the `obj` argument is `null`. - +> Starting with the .NET Framework 2.0 Service Pack 1, this method can be used to access non-public members if the caller has been granted with the flag and if the grant set of the non-public members is restricted to the caller's grant set, or a subset thereof. (See [Security Considerations for Reflection](/dotnet/framework/reflection-and-codedom/security-considerations-for-reflection).) +> +> To use this functionality, your application should target the .NET Framework 3.5 or later. + + + +## Examples + The following example uses the method to retrieve the value of a static field. Note that the value of the `obj` argument is `null`. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/GetFldVal/CPP/getfldval.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/FieldInfo/GetValue/getfldval.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/GetFldVal/VB/getfldval.vb" id="Snippet1"::: - - The following example retrieves an array of objects that represents the fields of the `FieldsClass` type, and then calls the to display the value of each field for the `fieldsInst` object. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/GetFldVal/VB/getfldval.vb" id="Snippet1"::: + + The following example retrieves an array of objects that represents the fields of the `FieldsClass` type, and then calls the to display the value of each field for the `fieldsInst` object. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/FieldInfo_GetValue/CPP/fieldinfo_getvalue.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/FieldInfo/GetValue/fieldinfo_getvalue.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/FieldInfo_GetValue/VB/fieldinfo_getvalue.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/FieldInfo_GetValue/VB/fieldinfo_getvalue.vb" id="Snippet1"::: + ]]> The field is non-static and is . @@ -1046,7 +1046,7 @@ Note: In .NET for Win System.Object - + A structure that encapsulates a managed pointer to a location and a runtime representation of the type that might be stored at that location. @@ -1105,22 +1105,22 @@ Note: In .NET for Win if the visibility of this field is exactly described by ; otherwise, . - property might be `true` for a field, but if it is a field of a private nested type then the field is not visible outside the containing type. - - The visibility of a field is exactly described by if the only visibility modifier is `internal` (`Friend` in Visual Basic). This property is `false` for fields that are `protected internal` in C# (`Protected Friend` in Visual Basic, `protected public` in C++); use the property to identify such fields. - - - -## Examples - The following code example defines fields with varying levels of visibility, and displays the values of their , , , and properties. + property might be `true` for a field, but if it is a field of a private nested type then the field is not visible outside the containing type. + + The visibility of a field is exactly described by if the only visibility modifier is `internal` (`Friend` in Visual Basic). This property is `false` for fields that are `protected internal` in C# (`Protected Friend` in Visual Basic, `protected public` in C++); use the property to identify such fields. + + + +## Examples + The following code example defines fields with varying levels of visibility, and displays the values of their , , , and properties. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic FieldInfo.IsAssembly Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/FieldInfo/IsAssembly/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic FieldInfo.IsAssembly Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic FieldInfo.IsAssembly Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -1177,21 +1177,21 @@ Note: In .NET for Win if access to this field is exactly described by ; otherwise, . - if the only visibility modifier is `protected`. This property is `false` for fields that are `protected internal` in C# (`Protected Friend` in Visual Basic, `protected public` in C++); use the property to identify such fields. - - - -## Examples - The following code example defines fields with varying levels of visibility, and displays the values of their , , , and properties. - + if the only visibility modifier is `protected`. This property is `false` for fields that are `protected internal` in C# (`Protected Friend` in Visual Basic, `protected public` in C++); use the property to identify such fields. + + + +## Examples + The following code example defines fields with varying levels of visibility, and displays the values of their , , , and properties. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic FieldInfo.IsAssembly Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/FieldInfo/IsAssembly/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic FieldInfo.IsAssembly Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic FieldInfo.IsAssembly Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -1249,23 +1249,23 @@ Note: In .NET for Win if access to this field is exactly described by ; otherwise, . - level visibility, it can be called from any member in a derived class that is also in the same assembly, but not from any other type. - - The visibility of a field is exactly described by if the visibility modifier is `private protected` in C#, `Private Protected` in Visual Basic, or `protected private` in C++. - - - -## Examples - The following code example defines fields with varying levels of visibility, and displays the values of their , , , and properties. - + level visibility, it can be called from any member in a derived class that is also in the same assembly, but not from any other type. + + The visibility of a field is exactly described by if the visibility modifier is `private protected` in C#, `Private Protected` in Visual Basic, or `protected private` in C++. + + + +## Examples + The following code example defines fields with varying levels of visibility, and displays the values of their , , , and properties. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic FieldInfo.IsAssembly Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/FieldInfo/IsAssembly/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic FieldInfo.IsAssembly Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic FieldInfo.IsAssembly Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -1322,25 +1322,25 @@ Note: In .NET for Win if access to this field is exactly described by ; otherwise, . - level visibility, it can be called from any member in a derived class or any member in the same assembly, but not from any other type. - - The actual visibility of a field is limited by the visibility of its type. The property might be `true` for a field, but if it is a field of a private nested type then the field is not visible outside the containing type. - - The visibility of a field is exactly described by if the visibility modifier is `protected internal` in C# (`Protected Friend` in Visual Basic, `protected public` in C++). - - - -## Examples - The following code example defines fields with varying levels of visibility, and displays the values of their , , , and properties. - + level visibility, it can be called from any member in a derived class or any member in the same assembly, but not from any other type. + + The actual visibility of a field is limited by the visibility of its type. The property might be `true` for a field, but if it is a field of a private nested type then the field is not visible outside the containing type. + + The visibility of a field is exactly described by if the visibility modifier is `protected internal` in C# (`Protected Friend` in Visual Basic, `protected public` in C++). + + + +## Examples + The following code example defines fields with varying levels of visibility, and displays the values of their , , , and properties. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic FieldInfo.IsAssembly Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/FieldInfo/IsAssembly/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic FieldInfo.IsAssembly Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic FieldInfo.IsAssembly Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -1396,34 +1396,34 @@ Note: In .NET for Win if the field has the attribute set; otherwise, . - with either or both of and in the `GetField` method. - - The `IsInitOnly` property is set when the attribute is set. - - - -## Examples - In the following example, two fields are created. The second field is read-only, having no set accessor, and `IsInitOnly` is set to `true`. - + with either or both of and in the `GetField` method. + + The `IsInitOnly` property is set when the attribute is set. + + + +## Examples + In the following example, two fields are created. The second field is read-only, having no set accessor, and `IsInitOnly` is set to `true`. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic FieldInfo.IsInitOnly Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/FieldInfo/IsInitOnly/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic FieldInfo.IsInitOnly Example/VB/source.vb" id="Snippet1"::: - - This code produces the following output: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic FieldInfo.IsInitOnly Example/VB/source.vb" id="Snippet1"::: + + This code produces the following output: + ```console -Reflection.FieldInfo +Reflection.FieldInfo -Myfielda - A- modified, IsInitOnly = False +Myfielda - A- modified, IsInitOnly = False Myfieldb - B readonly field, IsInitOnly = True -``` - +``` + ]]> @@ -1479,11 +1479,11 @@ Myfieldb - B readonly field, IsInitOnly = True if the field has the attribute set; otherwise, . - @@ -1540,20 +1540,20 @@ Myfieldb - B readonly field, IsInitOnly = True if the field has the attribute set; otherwise, . - @@ -1604,15 +1604,15 @@ Myfieldb - B readonly field, IsInitOnly = True if the attribute is set in ; otherwise, . - property value of the field. - + property value of the field. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/FieldInfo_IsPInvokeImpl/CPP/fieldinfo_ispinvokeimpl.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/FieldInfo/IsPinvokeImpl/fieldinfo_ispinvokeimpl.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/FieldInfo_IsPInvokeImpl/VB/fieldinfo_ispinvokeimpl.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/FieldInfo_IsPInvokeImpl/VB/fieldinfo_ispinvokeimpl.vb" id="Snippet1"::: + ]]> @@ -1666,24 +1666,24 @@ Myfieldb - B readonly field, IsInitOnly = True if the field is private; otherwise; . - @@ -1738,24 +1738,24 @@ Myfieldb - B readonly field, IsInitOnly = True if this field is public; otherwise, . - @@ -1802,24 +1802,24 @@ Myfieldb - B readonly field, IsInitOnly = True if the current field is security-critical or security-safe-critical at the current trust level; if it is transparent. - , , and properties report the transparency level of the field at its current trust level, as determined by the common language runtime (CLR). The combinations of these properties are shown in the following table: - -|Security level|IsSecurityCritical|IsSecuritySafeCritical|IsSecurityTransparent| -|--------------------|------------------------|----------------------------|---------------------------| -|Critical|`true`|`false`|`false`| -|Safe critical|`true`|`true`|`false`| -|Transparent|`false`|`false`|`true`| - - Using these properties is much simpler than examining the security annotations of an assembly and its types and members, checking the current trust level, and attempting to duplicate the runtime's rules. - + , , and properties report the transparency level of the field at its current trust level, as determined by the common language runtime (CLR). The combinations of these properties are shown in the following table: + +|Security level|IsSecurityCritical|IsSecuritySafeCritical|IsSecurityTransparent| +|--------------------|------------------------|----------------------------|---------------------------| +|Critical|`true`|`false`|`false`| +|Safe critical|`true`|`true`|`false`| +|Transparent|`false`|`false`|`true`| + + Using these properties is much simpler than examining the security annotations of an assembly and its types and members, checking the current trust level, and attempting to duplicate the runtime's rules. + > [!IMPORTANT] -> For partial-trust assemblies, the value of this property depends on the current trust level of the assembly. If the assembly is loaded into a partially trusted application domain (for example, into a sandboxed application domain), then the runtime ignores the security annotations of the assembly. The assembly and all its types are treated as transparent. The runtime pays attention to the security annotations of a partial-trust assembly only when that assembly is loaded into a fully trusted application domain (for example, into the default application domain of a desktop application). By contrast, a trusted assembly (that is, a strong-named assembly that is installed in the global assembly cache) is always loaded with full trust regardless of the trust level of the application domain, so its current trust level is always fully trusted. You can determine the current trust levels of assemblies and application domains by using the and properties. - - For more information about reflection and transparency, see [Security Considerations for Reflection](/dotnet/framework/reflection-and-codedom/security-considerations-for-reflection). For information about transparency, see [Security Changes](/dotnet/framework/security/security-changes). - +> For partial-trust assemblies, the value of this property depends on the current trust level of the assembly. If the assembly is loaded into a partially trusted application domain (for example, into a sandboxed application domain), then the runtime ignores the security annotations of the assembly. The assembly and all its types are treated as transparent. The runtime pays attention to the security annotations of a partial-trust assembly only when that assembly is loaded into a fully trusted application domain (for example, into the default application domain of a desktop application). By contrast, a trusted assembly (that is, a strong-named assembly that is installed in the global assembly cache) is always loaded with full trust regardless of the trust level of the application domain, so its current trust level is always fully trusted. You can determine the current trust levels of assemblies and application domains by using the and properties. + + For more information about reflection and transparency, see [Security Considerations for Reflection](/dotnet/framework/reflection-and-codedom/security-considerations-for-reflection). For information about transparency, see [Security Changes](/dotnet/framework/security/security-changes). + ]]> @@ -1866,24 +1866,24 @@ Myfieldb - B readonly field, IsInitOnly = True if the current field is security-safe-critical at the current trust level; if it is security-critical or transparent. - , , and properties report the transparency level of the field at its current trust level, as determined by the common language runtime (CLR). The combinations of these properties are shown in the following table: - -|Security level|IsSecurityCritical|IsSecuritySafeCritical|IsSecurityTransparent| -|--------------------|------------------------|----------------------------|---------------------------| -|Critical|`true`|`false`|`false`| -|Safe critical|`true`|`true`|`false`| -|Transparent|`false`|`false`|`true`| - - Using these properties is much simpler than examining the security annotations of an assembly and its types and members, checking the current trust level, and attempting to duplicate the runtime's rules. - + , , and properties report the transparency level of the field at its current trust level, as determined by the common language runtime (CLR). The combinations of these properties are shown in the following table: + +|Security level|IsSecurityCritical|IsSecuritySafeCritical|IsSecurityTransparent| +|--------------------|------------------------|----------------------------|---------------------------| +|Critical|`true`|`false`|`false`| +|Safe critical|`true`|`true`|`false`| +|Transparent|`false`|`false`|`true`| + + Using these properties is much simpler than examining the security annotations of an assembly and its types and members, checking the current trust level, and attempting to duplicate the runtime's rules. + > [!IMPORTANT] -> For partial-trust assemblies, the value of this property depends on the current trust level of the assembly. If the assembly is loaded into a partially trusted application domain (for example, into a sandboxed application domain), then the runtime ignores the security annotations of the assembly. The assembly and all its types are treated as transparent. The runtime pays attention to the security annotations of a partial-trust assembly only when that assembly is loaded into a fully trusted application domain (for example, into the default application domain of a desktop application). By contrast, a trusted assembly (that is, a strong-named assembly that is installed in the global assembly cache) is always loaded with full trust regardless of the trust level of the application domain, so its current trust level is always fully trusted. You can determine the current trust levels of assemblies and application domains by using the and properties. - - For more information about reflection and transparency, see [Security Considerations for Reflection](/dotnet/framework/reflection-and-codedom/security-considerations-for-reflection). For information about transparency, see [Security Changes](/dotnet/framework/security/security-changes). - +> For partial-trust assemblies, the value of this property depends on the current trust level of the assembly. If the assembly is loaded into a partially trusted application domain (for example, into a sandboxed application domain), then the runtime ignores the security annotations of the assembly. The assembly and all its types are treated as transparent. The runtime pays attention to the security annotations of a partial-trust assembly only when that assembly is loaded into a fully trusted application domain (for example, into the default application domain of a desktop application). By contrast, a trusted assembly (that is, a strong-named assembly that is installed in the global assembly cache) is always loaded with full trust regardless of the trust level of the application domain, so its current trust level is always fully trusted. You can determine the current trust levels of assemblies and application domains by using the and properties. + + For more information about reflection and transparency, see [Security Considerations for Reflection](/dotnet/framework/reflection-and-codedom/security-considerations-for-reflection). For information about transparency, see [Security Changes](/dotnet/framework/security/security-changes). + ]]> @@ -1930,24 +1930,24 @@ Myfieldb - B readonly field, IsInitOnly = True if the field is security-transparent at the current trust level; otherwise, . - , , and properties report the transparency level of the field at its current trust level, as determined by the common language runtime (CLR). The combinations of these properties are shown in the following table: - -|Security level|IsSecurityCritical|IsSecuritySafeCritical|IsSecurityTransparent| -|--------------------|------------------------|----------------------------|---------------------------| -|Critical|`true`|`false`|`false`| -|Safe critical|`true`|`true`|`false`| -|Transparent|`false`|`false`|`true`| - - Using these properties is much simpler than examining the security annotations of an assembly and its types and members, checking the current trust level, and attempting to duplicate the runtime's rules. - + , , and properties report the transparency level of the field at its current trust level, as determined by the common language runtime (CLR). The combinations of these properties are shown in the following table: + +|Security level|IsSecurityCritical|IsSecuritySafeCritical|IsSecurityTransparent| +|--------------------|------------------------|----------------------------|---------------------------| +|Critical|`true`|`false`|`false`| +|Safe critical|`true`|`true`|`false`| +|Transparent|`false`|`false`|`true`| + + Using these properties is much simpler than examining the security annotations of an assembly and its types and members, checking the current trust level, and attempting to duplicate the runtime's rules. + > [!IMPORTANT] -> For partial-trust assemblies, the value of this property depends on the current trust level of the assembly. If the assembly is loaded into a partially trusted application domain (for example, into a sandboxed application domain), then the runtime ignores the security annotations of the assembly. The assembly and all its types are treated as transparent. The runtime pays attention to the security annotations of a partial-trust assembly only when that assembly is loaded into a fully trusted application domain (for example, into the default application domain of a desktop application). By contrast, a trusted assembly (that is, a strong-named assembly that is installed in the global assembly cache) is always loaded with full trust regardless of the trust level of the application domain, so its current trust level is always fully trusted. You can determine the current trust levels of assemblies and application domains by using the and properties. - - For more information about reflection and transparency, see [Security Considerations for Reflection](/dotnet/framework/reflection-and-codedom/security-considerations-for-reflection). For information about transparency, see [Security Changes](/dotnet/framework/security/security-changes). - +> For partial-trust assemblies, the value of this property depends on the current trust level of the assembly. If the assembly is loaded into a partially trusted application domain (for example, into a sandboxed application domain), then the runtime ignores the security annotations of the assembly. The assembly and all its types are treated as transparent. The runtime pays attention to the security annotations of a partial-trust assembly only when that assembly is loaded into a fully trusted application domain (for example, into the default application domain of a desktop application). By contrast, a trusted assembly (that is, a strong-named assembly that is installed in the global assembly cache) is always loaded with full trust regardless of the trust level of the application domain, so its current trust level is always fully trusted. You can determine the current trust levels of assemblies and application domains by using the and properties. + + For more information about reflection and transparency, see [Security Considerations for Reflection](/dotnet/framework/reflection-and-codedom/security-considerations-for-reflection). For information about transparency, see [Security Changes](/dotnet/framework/security/security-changes). + ]]> @@ -2002,20 +2002,20 @@ Myfieldb - B readonly field, IsInitOnly = True if the attribute is set in ; otherwise, . - @@ -2069,34 +2069,34 @@ Myfieldb - B readonly field, IsInitOnly = True if this field is static; otherwise, . - @@ -2149,28 +2149,28 @@ Myfieldb - B static field; IsStatic - True Gets a value indicating that this member is a field. A value indicating that this member is a field. - . Therefore, when you examine a set of objects - for example, the array returned by - the property returns only when a given member is a field. - - - -## Examples - The following example determines whether the specified member is a field and displays the result. - + . Therefore, when you examine a set of objects - for example, the array returned by - the property returns only when a given member is a field. + + + +## Examples + The following example determines whether the specified member is a field and displays the result. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic FieldInfo.MemberType Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/FieldInfo/MemberType/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic FieldInfo.MemberType Example/VB/source.vb" id="Snippet1"::: - - This code produces the following output: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic FieldInfo.MemberType Example/VB/source.vb" id="Snippet1"::: + + This code produces the following output: ```console -Reflection.FieldInfo +Reflection.FieldInfo -Myfield.field - a private field; MemberType is a Field +Myfield.field - a private field; MemberType is a Field ``` - + ]]> @@ -2220,8 +2220,8 @@ Myfield.field - a private field; MemberType is a Field System.Boolean - - + + The first object to compare. @@ -2279,8 +2279,8 @@ Myfield.field - a private field; MemberType is a Field System.Boolean - - + + The first object to compare. @@ -2370,30 +2370,30 @@ Myfield.field - a private field; MemberType is a Field The value to assign to the field. Sets the value of the field supported by the given object. - [!NOTE] -> Fully trusted code has the permissions that are needed to access and invoke private constructors, methods, fields, and properties using reflection. - +> Fully trusted code has the permissions that are needed to access and invoke private constructors, methods, fields, and properties using reflection. + > [!NOTE] -> Starting with the .NET Framework 2.0 Service Pack 1, this method can be used to access non-public members if the caller has been granted with the flag and if the grant set of the non-public members is restricted to the caller's grant set, or a subset thereof. (See [Security Considerations for Reflection](/dotnet/framework/reflection-and-codedom/security-considerations-for-reflection).) -> -> To use this functionality, your application should target the .NET Framework 3.5 or later. - - - -## Examples - The following example sets the value of a field, gets and displays the value, modifies the field, and displays the result. - +> Starting with the .NET Framework 2.0 Service Pack 1, this method can be used to access non-public members if the caller has been granted with the flag and if the grant set of the non-public members is restricted to the caller's grant set, or a subset thereof. (See [Security Considerations for Reflection](/dotnet/framework/reflection-and-codedom/security-considerations-for-reflection).) +> +> To use this functionality, your application should target the .NET Framework 3.5 or later. + + + +## Examples + The following example sets the value of a field, gets and displays the value, modifies the field, and displays the result. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/FieldInfo_SetValue/CPP/fieldinfo_setvalue.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/FieldInfo/SetValue/fieldinfo_setvalue.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/FieldInfo_SetValue/VB/fieldinfo_setvalue.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/FieldInfo_SetValue/VB/fieldinfo_setvalue.vb" id="Snippet1"::: + ]]> The caller does not have permission to access this field. @@ -2404,10 +2404,10 @@ Note: In .NET for Win Note: In .NET for Windows Store apps or the Portable Class Library, catch instead. - The field does not exist on the object. - - -or- - + The field does not exist on the object. + + -or- + The parameter cannot be converted and stored in the field. @@ -2459,11 +2459,11 @@ Note: In .NET for Win System.Void - - - - - + + + + + The object whose field value will be set. @@ -2473,29 +2473,29 @@ Note: In .NET for Win The software preferences of a particular culture. When overridden in a derived class, sets the value of the field supported by the given object. - [!NOTE] -> Fully trusted code has the permissions that are needed to access and invoke private constructors, methods, fields, and properties using reflection. - +> Fully trusted code has the permissions that are needed to access and invoke private constructors, methods, fields, and properties using reflection. + > [!NOTE] -> Starting with the .NET Framework 2.0 Service Pack 1, this method can be used to access non-public members if the caller has been granted with the flag and if the grant set of the non-public members is restricted to the caller's grant set, or a subset thereof. (See [Security Considerations for Reflection](/dotnet/framework/reflection-and-codedom/security-considerations-for-reflection).) -> -> To use this functionality, your application should target the .NET Framework 3.5 or later. - +> Starting with the .NET Framework 2.0 Service Pack 1, this method can be used to access non-public members if the caller has been granted with the flag and if the grant set of the non-public members is restricted to the caller's grant set, or a subset thereof. (See [Security Considerations for Reflection](/dotnet/framework/reflection-and-codedom/security-considerations-for-reflection).) +> +> To use this functionality, your application should target the .NET Framework 3.5 or later. + ]]> The caller does not have permission to access this field. The parameter is and the field is an instance field. - The field does not exist on the object. - - -or- - + The field does not exist on the object. + + -or- + The parameter cannot be converted and stored in the field. @@ -2546,23 +2546,23 @@ This method cannot be used to set values of static, init-only (`readonly` in C#) System.Void - - + + A structure that encapsulates a managed pointer to a location and a runtime representation of the type that can be stored at that location. The value to assign to the field. Sets the value of the field supported by the given object. - [!NOTE] -> Starting with the .NET Framework 2.0 Service Pack 1, this method can be used to access non-public members if the caller has been granted with the flag and if the grant set of the non-public members is restricted to the caller's grant set, or a subset thereof. (See [Security Considerations for Reflection](/dotnet/framework/reflection-and-codedom/security-considerations-for-reflection).) -> -> To use this functionality, your application should target the .NET Framework 3.5 or later. - +> Starting with the .NET Framework 2.0 Service Pack 1, this method can be used to access non-public members if the caller has been granted with the flag and if the grant set of the non-public members is restricted to the caller's grant set, or a subset thereof. (See [Security Considerations for Reflection](/dotnet/framework/reflection-and-codedom/security-considerations-for-reflection).) +> +> To use this functionality, your application should target the .NET Framework 3.5 or later. + ]]> @@ -2599,11 +2599,11 @@ This method cannot be used to set values of static, init-only (`readonly` in C#) System.Void - - - - - + + + + + Reserved for future use. Must be IID_NULL. @@ -2613,11 +2613,11 @@ This method cannot be used to set values of static, init-only (`readonly` in C#) Caller-allocated array which receives the IDs corresponding to the names. Maps a set of names to a corresponding set of dispatch identifiers. - Late-bound access using the COM IDispatch interface is not supported. @@ -2688,9 +2688,9 @@ This method cannot be used to set values of static, init-only (`readonly` in C#) System.Void - - - + + + The type information to return. @@ -2698,11 +2698,11 @@ This method cannot be used to set values of static, init-only (`readonly` in C#) Receives a pointer to the requested type information object. Retrieves the type information for an object, which can then be used to get the type information for an interface. - Late-bound access using the COM IDispatch interface is not supported. @@ -2738,17 +2738,17 @@ This method cannot be used to set values of static, init-only (`readonly` in C#) System.Void - + Points to a location that receives the number of type information interfaces provided by the object. Retrieves the number of type information interfaces that an object provides (either 0 or 1). - Late-bound access using the COM IDispatch interface is not supported. @@ -2784,14 +2784,14 @@ This method cannot be used to set values of static, init-only (`readonly` in C#) System.Void - - - - - - - - + + + + + + + + Identifies the member. @@ -2804,11 +2804,11 @@ This method cannot be used to set values of static, init-only (`readonly` in C#) The index of the first argument that has an error. Provides access to properties and methods exposed by an object. - Late-bound access using the COM IDispatch interface is not supported. diff --git a/xml/System.Reflection/MemberInfo.xml b/xml/System.Reflection/MemberInfo.xml index 83ba2c3c67d..df394f4f224 100644 --- a/xml/System.Reflection/MemberInfo.xml +++ b/xml/System.Reflection/MemberInfo.xml @@ -101,22 +101,22 @@ Obtains information about the attributes of a member and provides access to member metadata. - class is the abstract base class for classes used to obtain information about all members of a class (constructors, events, fields, methods, and properties). - - This class introduces the basic functionality that all members provide. - - - -## Examples - This example shows how to use various reflection classes to analyze the metadata contained in an assembly. - + class is the abstract base class for classes used to obtain information about all members of a class (constructors, events, fields, methods, and properties). + + This class introduces the basic functionality that all members provide. + + + +## Examples + This example shows how to use various reflection classes to analyze the metadata contained in an assembly. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Reflection/CPP/reflection.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/Assembly/GetReferencedAssemblies/Reflection.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Reflection/VB/Reflection.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Reflection/VB/Reflection.vb" id="Snippet1"::: + ]]> This type is thread safe. @@ -126,11 +126,11 @@ - - - - - + + + + + Constructor mscorlib @@ -162,11 +162,11 @@ Initializes a new instance of the class. - @@ -273,28 +273,28 @@ Gets the class that declares this member. The object for the class that declares this member. - property retrieves a reference to the object for the type that declares this member. A member of a type is either declared by the type or inherited from a base type, so the `Type` object returned by the property might not be the same as the `Type` object used to obtain the current object. - -- If the `Type` object from which this `MemberInfo` object was obtained did not declare this member, the property will represent one of its base types. - -- If the `MemberInfo` object is a global member (that is, if it was obtained from the method, which returns global methods on a module), the returned will be `null`. - - - -## Examples - The following example defines an interface, `IValue`, with a single member, `GetValue`. It also defines four classes: `A`, a base class that implements the `IValue` interface; `B`, which inherits from `A` and hides its implementation of `GetValue` from the base class implementation; `C`, which simply inherits from `A`; and `D`, which inherits from `A` and overrides its `GetValue` method. The example then retrieves a object for each member of the type (including members inherited from ) and displays the value of its property. - + property retrieves a reference to the object for the type that declares this member. A member of a type is either declared by the type or inherited from a base type, so the `Type` object returned by the property might not be the same as the `Type` object used to obtain the current object. + +- If the `Type` object from which this `MemberInfo` object was obtained did not declare this member, the property will represent one of its base types. + +- If the `MemberInfo` object is a global member (that is, if it was obtained from the method, which returns global methods on a module), the returned will be `null`. + + + +## Examples + The following example defines an interface, `IValue`, with a single member, `GetValue`. It also defines four classes: `A`, a base class that implements the `IValue` interface; `B`, which inherits from `A` and hides its implementation of `GetValue` from the base class implementation; `C`, which simply inherits from `A`; and `D`, which inherits from `A` and overrides its `GetValue` method. The example then retrieves a object for each member of the type (including members inherited from ) and displays the value of its property. + :::code language="csharp" source="~/snippets/csharp/System.Reflection/MemberInfo/DeclaringType/Example2.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic MemberInfo.DeclaringType Example/VB/Example2.vb" id="Snippet2"::: - - Note that the declaring type of `A.GetValue` is `A`, that `B` includes two `GetValue` methods, one declared by `A` and one by `B`, and that the declaring type of `D.GetValue` is `D`. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic MemberInfo.DeclaringType Example/VB/Example2.vb" id="Snippet2"::: + + Note that the declaring type of `A.GetValue` is `A`, that `B` includes two `GetValue` methods, one declared by `A` and one by `B`, and that the declaring type of `D.GetValue` is `D`. + > [!NOTE] -> `DeclaringType` returns only the member names and the names of their declaring types. To return the member names with their prototypes, call `MemberInfo.ToString`. - +> `DeclaringType` returns only the member names and the names of their declaring types. To return the member names with their prototypes, call `MemberInfo.ToString`. + ]]> @@ -410,7 +410,7 @@ System.Object[] - + @@ -418,23 +418,23 @@ When overridden in a derived class, returns an array of all custom attributes applied to this member. An array that contains all the custom attributes applied to this member, or an array with zero elements if no attributes are defined. - method. - + method. + > [!NOTE] -> In the .NET Framework version 2.0, this method returns security attributes on methods, constructors, and types if they are stored in the new metadata format. Assemblies compiled with version 2.0 use this format. Dynamic assemblies and assemblies compiled with earlier versions of the .NET Framework use the old XML format. See [Emitting Declarative Security Attributes](https://msdn.microsoft.com/library/9eeddee8-ca89-4440-b84b-fd613f590cd5). - - - -## Examples - The following example defines a custom attribute and associates the attribute with `MyClass.MyMethod`, retrieves the attribute at run time, and displays the result. - +> In the .NET Framework version 2.0, this method returns security attributes on methods, constructors, and types if they are stored in the new metadata format. Assemblies compiled with version 2.0 use this format. Dynamic assemblies and assemblies compiled with earlier versions of the .NET Framework use the old XML format. See [Emitting Declarative Security Attributes](https://msdn.microsoft.com/library/9eeddee8-ca89-4440-b84b-fd613f590cd5). + + + +## Examples + The following example defines a custom attribute and associates the attribute with `MyClass.MyMethod`, retrieves the attribute at run time, and displays the result. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/MemberInfo_GetCustomAttributes1/CPP/memberinfo_getcustomattributes1.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/MemberInfo/GetCustomAttributes/memberinfo_getcustomattributes1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/MemberInfo_GetCustomAttributes1/VB/memberinfo_getcustomattributes1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/MemberInfo_GetCustomAttributes1/VB/memberinfo_getcustomattributes1.vb" id="Snippet1"::: + ]]> This member belongs to a type that is loaded into the reflection-only context. See [How to: Load Assemblies into the Reflection-Only Context](/dotnet/framework/reflection-and-codedom/how-to-load-assemblies-into-the-reflection-only-context). @@ -485,8 +485,8 @@ System.Object[] - - + + The type of attribute to search for. Only attributes that are assignable to this type are returned. @@ -495,22 +495,22 @@ When overridden in a derived class, returns an array of custom attributes applied to this member and identified by . An array of custom attributes applied to this member, or an array with zero elements if no attributes assignable to have been applied. - method. - + method. + > [!NOTE] -> In the .NET Framework version 2.0, this method returns security attributes on methods, constructors, and types if the attributes are stored in the new metadata format. Assemblies compiled with version 2.0 use this format. Dynamic assemblies and assemblies compiled with earlier versions of the .NET Framework use the old XML format. See [Emitting Declarative Security Attributes](https://msdn.microsoft.com/library/9eeddee8-ca89-4440-b84b-fd613f590cd5). - - - -## Examples - The following example defines a class named `BaseClass` that has two non-inherited members: a thread static field named `total` and a non-CLS-compliant method named `MethodA`. A class named `DerivedClass` inherits from `BaseClass` and overrides its `MethodA` method. Note that no attributes are applied to the members of `DerivedClass`. The example iterates the members of `DerivedClass` to determine whether the or attribute as been applied to them. Because `inherit` is `true`, the method searches the inheritance hierarchy of `DerivedClass` for the specified attribute. As the output from the example shows, the `total` field is decorated with the attribute, and the `MethodA` method is decorated with the attribute. - +> In the .NET Framework version 2.0, this method returns security attributes on methods, constructors, and types if the attributes are stored in the new metadata format. Assemblies compiled with version 2.0 use this format. Dynamic assemblies and assemblies compiled with earlier versions of the .NET Framework use the old XML format. See [Emitting Declarative Security Attributes](https://msdn.microsoft.com/library/9eeddee8-ca89-4440-b84b-fd613f590cd5). + + + +## Examples + The following example defines a class named `BaseClass` that has two non-inherited members: a thread static field named `total` and a non-CLS-compliant method named `MethodA`. A class named `DerivedClass` inherits from `BaseClass` and overrides its `MethodA` method. Note that no attributes are applied to the members of `DerivedClass`. The example iterates the members of `DerivedClass` to determine whether the or attribute as been applied to them. Because `inherit` is `true`, the method searches the inheritance hierarchy of `DerivedClass` for the specified attribute. As the output from the example shows, the `total` field is decorated with the attribute, and the `MethodA` method is decorated with the attribute. + :::code language="csharp" source="~/snippets/csharp/System.Reflection/MemberInfo/GetCustomAttributes/GetCustomAttributes1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/System.Reflection.MemberInfo.GetCustomAttributes/vb/GetCustomAttributes1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/System.Reflection.MemberInfo.GetCustomAttributes/vb/GetCustomAttributes1.vb" id="Snippet1"::: + ]]> A custom attribute type cannot be loaded. @@ -558,13 +558,13 @@ Returns a list of objects representing data about the attributes that have been applied to the target member. A generic list of objects representing data about the attributes that have been applied to the target member. - and cannot be used in such cases, because they create instances of the attributes. Code in the reflection-only context cannot be executed. For more information and for example code, see the class. - - This method gets custom attribute data for types, nested types, and type members, because the class and the classes in the namespace that represent type members all derive from . - + and cannot be used in such cases, because they create instances of the attributes. Code in the reflection-only context cannot be executed. For more information and for example code, see the class. + + This method gets custom attribute data for types, nested types, and type members, because the class and the classes in the namespace that represent type members all derive from . + ]]> @@ -778,8 +778,8 @@ For more information, see [How to use and debug assembly unloadability in .NET C System.Boolean - - + + The type of custom attribute to search for. The search includes derived types. @@ -789,23 +789,23 @@ For more information, see [How to use and debug assembly unloadability in .NET C if one or more instances of or any of its derived types is applied to this member; otherwise, . - method. - + method. + > [!NOTE] -> In the .NET Framework version 2.0, this method returns `true` if a type, method, or constructor has security attributes stored in the new metadata format. Assemblies compiled with version 2.0 use this format. Dynamic assemblies and assemblies compiled with earlier versions of the .NET Framework use the old XML format. See [Emitting Declarative Security Attributes](https://msdn.microsoft.com/library/9eeddee8-ca89-4440-b84b-fd613f590cd5). - - - -## Examples - The following example determines whether the specified attribute is applied to the specified member. - +> In the .NET Framework version 2.0, this method returns `true` if a type, method, or constructor has security attributes stored in the new metadata format. Assemblies compiled with version 2.0 use this format. Dynamic assemblies and assemblies compiled with earlier versions of the .NET Framework use the old XML format. See [Emitting Declarative Security Attributes](https://msdn.microsoft.com/library/9eeddee8-ca89-4440-b84b-fd613f590cd5). + + + +## Examples + The following example determines whether the specified attribute is applied to the specified member. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/MemberInfo_GetCustomAttribute_IsDefined/CPP/memberinfo_getcustomattribute_isdefined.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/MemberInfo/IsDefined/memberinfo_getcustomattribute_isdefined.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/MemberInfo_GetCustomAttribute_IsDefined/VB/memberinfo_getcustomattribute_isdefined.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/MemberInfo_GetCustomAttribute_IsDefined/VB/memberinfo_getcustomattribute_isdefined.vb" id="Snippet1"::: + ]]> @@ -855,22 +855,22 @@ For more information, see [How to use and debug assembly unloadability in .NET C When overridden in a derived class, gets a value indicating the type of the member - method, constructor, event, and so on. A value indicating the type of member. - objects - for example, the array returned by - the property can be used to determine the member type of any given member. - - To get the `MemberType` property, get the class . From the `Type`, get the array. From the `MethodInfo` array, get the `MemberTypes`. - - - -## Examples - The following example displays the member name and type of a specified class. - + objects - for example, the array returned by - the property can be used to determine the member type of any given member. + + To get the `MemberType` property, get the class . From the `Type`, get the array. From the `MethodInfo` array, get the `MemberTypes`. + + + +## Examples + The following example displays the member name and type of a specified class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic MemberInfo.MemberType Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/ConstructorInfo/MemberType/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic MemberInfo.MemberType Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic MemberInfo.MemberType Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -917,14 +917,14 @@ For more information, see [How to use and debug assembly unloadability in .NET C Gets a value that identifies a metadata element. A value which, in combination with , uniquely identifies a metadata element. - [!NOTE] > Using the unmanaged reflection API requires familiarity with the Common Language Infrastructure (CLI) documentation, especially "Partition II: Metadata Definition and Semantics" and "Partition III: CIL Instruction Set". For more information, see [ECMA 335 Common Language Infrastructure (CLI)](https://www.ecma-international.org/publications-and-standards/standards/ecma-335/). - + ]]> The current represents an array method, such as , on an array type whose element type is a dynamic type that has not been completed. To get a metadata token in this case, pass the object to the method; or use the method to get the token directly, instead of using the method to get a first. @@ -973,20 +973,20 @@ For more information, see [How to use and debug assembly unloadability in .NET C Gets the module in which the type that declares the member represented by the current is defined. The in which the type that declares the member represented by the current is defined. - property to get the type in which the method is declared, and then calling the property of the resulting object. - - - -## Examples - The following code example declares a class that inherits and overrides . The example obtains objects for the class's `ToString` method and for the inherited method, and displays the names of the modules in which the two methods are declared. - + property to get the type in which the method is declared, and then calling the property of the resulting object. + + + +## Examples + The following code example declares a class that inherits and overrides . The example obtains objects for the class's `ToString` method and for the inherited method, and displays the names of the modules in which the two methods are declared. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Reflection.MemberInfo.Module/cpp/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/MemberInfo/Module/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Reflection.MemberInfo.Module/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Reflection.MemberInfo.Module/VB/source.vb" id="Snippet1"::: + ]]> This method is not implemented. @@ -1040,22 +1040,22 @@ For more information, see [How to use and debug assembly unloadability in .NET C Gets the name of the current member. A containing the name of this member. - property, get the class . From the `Type`, get the array. From a `MemberInfo` element of the array, obtain the `Name` property. - - - -## Examples - This example lists the `Name` and `DeclaringType` property of each member of the specified class. - + property, get the class . From the `Type`, get the array. From a `MemberInfo` element of the array, obtain the `Name` property. + + + +## Examples + This example lists the `Name` and `DeclaringType` property of each member of the specified class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic MemberInfo.Name Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/MemberInfo/Name/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic MemberInfo.Name Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic MemberInfo.Name Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -1103,8 +1103,8 @@ For more information, see [How to use and debug assembly unloadability in .NET C System.Boolean - - + + The to compare to . @@ -1162,8 +1162,8 @@ For more information, see [How to use and debug assembly unloadability in .NET C System.Boolean - - + + The to compare to . @@ -1229,22 +1229,22 @@ For more information, see [How to use and debug assembly unloadability in .NET C Gets the class object that was used to obtain this instance of . The object through which this object was obtained. - object that was used to obtain this instance of `MemberInfo`. This may differ from the value of the property if this object represents a member that is inherited from a base class. - - If the `MemberInfo` object is a global member (that is, if it was obtained from the method, which returns global methods on a module), the returned will be `null`. - - - -## Examples - The following code example shows how the changes when the member is viewed from a obtained from type and from a obtained from the class itself, which inherits but does not override . - + object that was used to obtain this instance of `MemberInfo`. This may differ from the value of the property if this object represents a member that is inherited from a base class. + + If the `MemberInfo` object is a global member (that is, if it was obtained from the method, which returns global methods on a module), the returned will be `null`. + + + +## Examples + The following code example shows how the changes when the member is viewed from a obtained from type and from a obtained from the class itself, which inherits but does not override . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic MemberInfo.ReflectedType Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/MemberInfo/ReflectedType/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic MemberInfo.ReflectedType Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic MemberInfo.ReflectedType Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -1395,11 +1395,11 @@ For more information, see [How to use and debug assembly unloadability in .NET C System.Void - - - - - + + + + + Reserved for future use. Must be IID_NULL. @@ -1409,11 +1409,11 @@ For more information, see [How to use and debug assembly unloadability in .NET C Caller-allocated array which receives the IDs corresponding to the names. Maps a set of names to a corresponding set of dispatch identifiers. - The method is called late-bound using the COM IDispatch interface. @@ -1484,9 +1484,9 @@ For more information, see [How to use and debug assembly unloadability in .NET C System.Void - - - + + + The type information to return. @@ -1494,11 +1494,11 @@ For more information, see [How to use and debug assembly unloadability in .NET C Receives a pointer to the requested type information object. Retrieves the type information for an object, which can then be used to get the type information for an interface. - The method is called late-bound using the COM IDispatch interface. @@ -1534,17 +1534,17 @@ For more information, see [How to use and debug assembly unloadability in .NET C System.Void - + Points to a location that receives the number of type information interfaces provided by the object. Retrieves the number of type information interfaces that an object provides (either 0 or 1). - The method is called late-bound using the COM IDispatch interface. @@ -1580,14 +1580,14 @@ For more information, see [How to use and debug assembly unloadability in .NET C System.Void - - - - - - - - + + + + + + + + Identifies the member. @@ -1600,11 +1600,11 @@ For more information, see [How to use and debug assembly unloadability in .NET C The index of the first argument that has an error. Provides access to properties and methods exposed by an object. - The method is called late-bound using the COM IDispatch interface. diff --git a/xml/System.Reflection/MethodBase.xml b/xml/System.Reflection/MethodBase.xml index 108101a4bde..b87d8579463 100644 --- a/xml/System.Reflection/MethodBase.xml +++ b/xml/System.Reflection/MethodBase.xml @@ -92,11 +92,11 @@ Provides information about methods and constructors. - and . - + and . + ]]> This type is thread safe. @@ -106,11 +106,11 @@ - - - - - + + + + + Constructor mscorlib @@ -191,40 +191,40 @@ Gets the attributes associated with this method. One of the values. - , first get the type. From the type, get the method. From the method, get the . - - - -## Examples - The following code example displays the attributes of the user-defined method Mymethod. - + , first get the type. From the type, get the method. From the method, get the . + + + +## Examples + The following code example displays the attributes of the user-defined method Mymethod. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic MethodBase.Attributes Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System/Type/GetFields/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic MethodBase.Attributes Example/VB/source.vb" id="Snippet1"::: - - This code produces the following output: - - Reflection.MethodBase.Attributes Sample - - Mymethodbase = Void Mymethod(Int32, System.String ByRef, System.String ByRef) - - PrivateScope - - FamANDAssem - - Family - - Public - - HideBySig - - ReuseSlot - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic MethodBase.Attributes Example/VB/source.vb" id="Snippet1"::: + + This code produces the following output: + + Reflection.MethodBase.Attributes Sample + + Mymethodbase = Void Mymethod(Int32, System.String ByRef, System.String ByRef) + + PrivateScope + + FamANDAssem + + Family + + Public + + HideBySig + + ReuseSlot + ]]> @@ -327,17 +327,17 @@ if the current object represents a generic method that contains unassigned generic type parameters; otherwise, . - property provides a standard way to distinguish between closed constructed methods, which can be invoked, and open constructed methods, which cannot. If the property returns `true`, the method cannot be invoked. - - The property searches recursively for type parameters. For example, it returns `true` for any method in an open type `A` (`A(Of T)` in Visual Basic), even though the method itself is not generic. Contrast this with the behavior of the property, which returns `false` for such a method. - - Similarly, the property parameter returns `true` for any constructor in an open type, even though constructors cannot have type parameters of their own. - - For a list of the invariant conditions for terms specific to generic methods, see the property. For a list of the invariant conditions for other terms used in generic reflection, see the property. - + property provides a standard way to distinguish between closed constructed methods, which can be invoked, and open constructed methods, which cannot. If the property returns `true`, the method cannot be invoked. + + The property searches recursively for type parameters. For example, it returns `true` for any method in an open type `A` (`A(Of T)` in Visual Basic), even though the method itself is not generic. Contrast this with the behavior of the property, which returns `false` for such a method. + + Similarly, the property parameter returns `true` for any constructor in an open type, even though constructors cannot have type parameters of their own. + + For a list of the invariant conditions for terms specific to generic methods, see the property. For a list of the invariant conditions for other terms used in generic reflection, see the property. + ]]> @@ -450,25 +450,25 @@ Returns a object representing the currently executing method. - is a static method that is called from within an executing method and that returns information about that method. - + is a static method that is called from within an executing method and that returns information about that method. + A object representing the currently executing method. - that is returned by is obtained from the generic type definition (that is, returns `true`). Therefore, it does not reflect the type arguments that were used when the method was called. For example, if a method `M()` is defined on a generic type `C` (`C(Of T)` in Visual Basic), and is called from `C.M()`, then returns `C.M()` (`C(Of T).M()` in Visual Basic). - - If the currently executing method is a generic method, returns the generic method definition. If the generic method is defined on a generic type, the is obtained from the generic type definition. - - - -## Examples - The following example defines two types. The first is a non-generic class, `TestClass`, includes a constructor, a method named `GetValue`, and a read-write property named `GetValue`. The second is a generic class named `TestClass` that includes a constructor, a `GetValue` method, and a generic method, `ConvertValue`. Each constructor, method, and property accessor includes a call to the method. - + that is returned by is obtained from the generic type definition (that is, returns `true`). Therefore, it does not reflect the type arguments that were used when the method was called. For example, if a method `M()` is defined on a generic type `C` (`C(Of T)` in Visual Basic), and is called from `C.M()`, then returns `C.M()` (`C(Of T).M()` in Visual Basic). + + If the currently executing method is a generic method, returns the generic method definition. If the generic method is defined on a generic type, the is obtained from the generic type definition. + + + +## Examples + The following example defines two types. The first is a non-generic class, `TestClass`, includes a constructor, a method named `GetValue`, and a read-write property named `GetValue`. The second is a generic class named `TestClass` that includes a constructor, a `GetValue` method, and a generic method, `ConvertValue`. Each constructor, method, and property accessor includes a call to the method. + :::code language="csharp" source="~/snippets/csharp/System.Reflection/MethodBase/GetCurrentMethod/GetCurentMethod1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/System.Reflection.MethodBase.GetCurrentMethod/vb/GetCurentMethod1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/System.Reflection.MethodBase.GetCurrentMethod/vb/GetCurentMethod1.vb" id="Snippet1"::: + ]]> This member was invoked with a late-binding mechanism. @@ -528,21 +528,21 @@ Returns an array of objects that represent the type arguments of a generic method or the type parameters of a generic method definition. An array of objects that represent the type arguments of a generic method or the type parameters of a generic method definition. Returns an empty array if the current method is not a generic method. - property returns `false`), the array returned by the method contains the types that have been assigned to the generic type parameters of the generic method definition. - -- If the current method is a generic method definition, the array contains the type parameters. - -- If the current method is an open constructed method (that is, the property returns `true`) in which specific types have been assigned to some type parameters and type parameters of enclosing generic types have been assigned to other type parameters, the array contains both types and type parameters. Use the property to tell them apart. For a demonstration of this scenario, see the code example provided for the property. - - Generic constructors are not supported in the .NET Framework version 2.0. This property throws if not overridden in a derived class, so an exception is thrown if the current instance is of type . - - For a list of the invariant conditions for terms specific to generic methods, see the property. For a list of the invariant conditions for other terms used in generic reflection, see the property. - + property returns `false`), the array returned by the method contains the types that have been assigned to the generic type parameters of the generic method definition. + +- If the current method is a generic method definition, the array contains the type parameters. + +- If the current method is an open constructed method (that is, the property returns `true`) in which specific types have been assigned to some type parameters and type parameters of enclosing generic types have been assigned to other type parameters, the array contains both types and type parameters. Use the property to tell them apart. For a demonstration of this scenario, see the code example provided for the property. + + Generic constructors are not supported in the .NET Framework version 2.0. This property throws if not overridden in a derived class, so an exception is thrown if the current instance is of type . + + For a list of the invariant conditions for terms specific to generic methods, see the property. For a list of the invariant conditions for other terms used in generic reflection, see the property. + ]]> The current object is a . Generic constructors are not supported in the .NET Framework version 2.0. This exception is the default behavior if this method is not overridden in a derived class. @@ -652,25 +652,25 @@ When overridden in a derived class, gets a object that provides access to the MSIL stream, local variables, and exceptions for the current method. A object that provides access to the MSIL stream, local variables, and exceptions for the current method. - in order to use it. You can call the method on and objects, because the method is overridden in the runtime versions of these classes. For example, the runtime version of the class derives from the class, which in turn derives from the class. - - - -## Examples - The following code example defines a test method named `MethodBodyExample` and displays its local variable information and exception-handling clauses. The method is used to obtain a object for the test method. - - The property is used to obtain a list of objects and display their types and index order. The property is used to obtain a list of exception-handling clauses. - + in order to use it. You can call the method on and objects, because the method is overridden in the runtime versions of these classes. For example, the runtime version of the class derives from the class, which in turn derives from the class. + + + +## Examples + The following code example defines a test method named `MethodBodyExample` and displays its local variable information and exception-handling clauses. The method is used to obtain a object for the test method. + + The property is used to obtain a list of objects and display their types and index order. The property is used to obtain a list of exception-handling clauses. + > [!NOTE] -> Not all computer languages can generate clauses. The Visual Basic example shows a filter clause, using a Visual Basic `When` expression, which is omitted from the examples for other languages. - +> Not all computer languages can generate clauses. The Visual Basic example shows a filter clause, using a Visual Basic `When` expression, which is omitted from the examples for other languages. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/MethodBody/cpp/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/ExceptionHandlingClause/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/MethodBody/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/MethodBody/VB/source.vb" id="Snippet1"::: + ]]> This method is invalid unless overridden in a derived class. @@ -742,11 +742,11 @@ Gets method information by using the method's internal metadata representation (handle). A containing information about the method. - @@ -813,13 +813,13 @@ Gets a object for the constructor or method represented by the specified handle, for the specified generic type. A object representing the method or constructor specified by , in the generic type specified by . - structure for a constructor or method of a generic type can represent different objects, depending on the types specified for the type parameters of the generic type. For example, if `class G` (`class G(Of T)` in Visual Basic, `generic ref class G` in C++) has a method that returns type `T`, the object for that method in a constructed class such as `G` is different from the object for that method in the generic type definition. - + structure for a constructor or method of a generic type can represent different objects, depending on the types specified for the type parameters of the generic type. For example, if `class G` (`class G(Of T)` in Visual Basic, `generic ref class G` in C++) has a method that returns type `T`, the object for that method in a constructed class such as `G` is different from the object for that method in the generic type definition. + ]]> @@ -872,15 +872,15 @@ When overridden in a derived class, returns the flags. The flags. - method to display the method implementation flags that are set by default. - + method to display the method implementation flags that are set by default. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/ConstructorBuilder_GetModule_4/CPP/constructorbuilder_getmodule_4.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/MethodBase/GetMethodImplementationFlags/constructorbuilder_getmodule_4.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ConstructorBuilder_GetModule_4/VB/constructorbuilder_getmodule_4.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ConstructorBuilder_GetModule_4/VB/constructorbuilder_getmodule_4.vb" id="Snippet3"::: + ]]> @@ -940,17 +940,17 @@ When overridden in a derived class, gets the parameters of the specified method or constructor. An array of type containing information that matches the signature of the method (or constructor) reflected by this instance. - method to retrieve the parameters of the `Invoke` method of a delegate. - - The example defines a delegate named `MyDelegate` and an event named `ev` of type `MyDelegate`. The code in the `Main` method discovers the event signature by getting the delegate type of the event, getting the `Invoke` method of the delegate type, and then retrieving and displaying the parameters. - + method to retrieve the parameters of the `Invoke` method of a delegate. + + The example defines a delegate named `MyDelegate` and an event named `ev` of type `MyDelegate`. The code in the `Main` method discovers the event signature by getting the delegate type of the event, getting the `Invoke` method of the delegate type, and then retrieving and displaying the parameters. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/EventArg/CPP/eventarg.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/EventInfo/EventHandlerType/eventarg.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/EventArg/VB/eventarg.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/EventArg/VB/eventarg.vb" id="Snippet1"::: + ]]> @@ -1062,56 +1062,56 @@ The object on which to invoke the method or constructor. If a method is static, this argument is ignored. If a constructor is static, this argument must be or an instance of the class that defines the constructor. - An argument list for the invoked method or constructor. This is an array of objects with the same number, order, and type as the parameters of the method or constructor to be invoked. If there are no parameters, should be . - + An argument list for the invoked method or constructor. This is an array of objects with the same number, order, and type as the parameters of the method or constructor to be invoked. If there are no parameters, should be . + If the method or constructor represented by this instance takes a parameter ( in Visual Basic), no special attribute is required for that parameter in order to invoke the method or constructor using this function. Any object in this array that is not explicitly initialized with a value will contain the default value for that object type. For reference-type elements, this value is . For value-type elements, the default value is 0, 0.0, or , depending on the specific element type. Invokes the method or constructor represented by the current instance, using the specified parameters. An object containing the return value of the invoked method, or in the case of a constructor. - method overload, passing for `invokeAttr` and `null` for `binder` and `culture`. - + method overload, passing for `invokeAttr` and `null` for `binder` and `culture`. + If the invoked method throws an exception, the method returns the originating exception. - - To invoke a static method using its object, pass `null` for `obj`. - + + To invoke a static method using its object, pass `null` for `obj`. + > [!NOTE] -> If this method overload is used to invoke an instance constructor, the object supplied for `obj` is reinitialized; that is, all instance initializers are executed. The return value is `null`. If a class constructor is invoked, the class is reinitialized; that is, all class initializers are executed. The return value is `null`. - +> If this method overload is used to invoke an instance constructor, the object supplied for `obj` is reinitialized; that is, all instance initializers are executed. The return value is `null`. If a class constructor is invoked, the class is reinitialized; that is, all class initializers are executed. The return value is `null`. + > [!NOTE] -> Starting with .NET Framework 2.0, this method can be used to access non-public members if the caller has been granted with the flag and if the grant set of the non-public members is restricted to the caller's grant set, or a subset thereof. (See [Security Considerations for Reflection](/dotnet/framework/reflection-and-codedom/security-considerations-for-reflection).) To use this functionality, your application should target .NET Framework 3.5 or later. - - If a parameter of the reflected method is a value type, and the corresponding argument in `parameters` is `null`, the runtime passes a zero-initialized instance of the value type. - - - -## Examples - The following code example demonstrates dynamic method lookup using reflection. Note that you cannot use the object from the base class to invoke the overridden method in the derived class, because late binding cannot resolve overrides. - +> Starting with .NET Framework 2.0, this method can be used to access non-public members if the caller has been granted with the flag and if the grant set of the non-public members is restricted to the caller's grant set, or a subset thereof. (See [Security Considerations for Reflection](/dotnet/framework/reflection-and-codedom/security-considerations-for-reflection).) To use this functionality, your application should target .NET Framework 3.5 or later. + + If a parameter of the reflected method is a value type, and the corresponding argument in `parameters` is `null`, the runtime passes a zero-initialized instance of the value type. + + + +## Examples + The following code example demonstrates dynamic method lookup using reflection. Note that you cannot use the object from the base class to invoke the overridden method in the derived class, because late binding cannot resolve overrides. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic MethodBase.Invoke1 Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/MethodBase/Invoke/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic MethodBase.Invoke1 Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic MethodBase.Invoke1 Example/VB/source.vb" id="Snippet1"::: + ]]> - The parameter is and the method is not static. - - -or- - - The method is not declared or inherited by the class of . - - -or- - + The parameter is and the method is not static. + + -or- + + The method is not declared or inherited by the class of . + + -or- + A static constructor is invoked, and is neither nor an instance of the class that declared the constructor. Note: In .NET for Windows Store apps or the Portable Class Library, catch instead. The elements of the array do not match the signature of the method or constructor reflected by this instance. - The invoked method or constructor throws an exception. - - -or- - + The invoked method or constructor throws an exception. + + -or- + The current instance is a that contains unverifiable code. See the "Verification" section in Remarks for . The array does not have the correct number of arguments. The caller does not have permission to execute the method or constructor that is represented by the current instance. @@ -1166,70 +1166,70 @@ Note: In .NET for Win System.Object - - - - - + + + + + The object on which to invoke the method or constructor. If a method is static, this argument is ignored. If a constructor is static, this argument must be or an instance of the class that defines the constructor. A bitmask that is a combination of 0 or more bit flags from . If is , this parameter is assigned the value ; thus, whatever you pass in is ignored. An object that enables the binding, coercion of argument types, invocation of members, and retrieval of objects via reflection. If is , the default binder is used. - An argument list for the invoked method or constructor. This is an array of objects with the same number, order, and type as the parameters of the method or constructor to be invoked. If there are no parameters, this should be . - + An argument list for the invoked method or constructor. This is an array of objects with the same number, order, and type as the parameters of the method or constructor to be invoked. If there are no parameters, this should be . + If the method or constructor represented by this instance takes a ByRef parameter, there is no special attribute required for that parameter in order to invoke the method or constructor using this function. Any object in this array that is not explicitly initialized with a value will contain the default value for that object type. For reference-type elements, this value is . For value-type elements, this value is 0, 0.0, or , depending on the specific element type. An instance of used to govern the coercion of types. If this is , the for the current thread is used. (This is necessary to convert a string that represents 1000 to a value, for example, since 1000 is represented differently by different cultures.) When overridden in a derived class, invokes the reflected method or constructor with the given parameters. An containing the return value of the invoked method, or in the case of a constructor, or if the method's return type is . Before calling the method or constructor, checks to see if the user has access permission and verifies that the parameters are valid. - [!NOTE] -> If this method overload is used to invoke an instance constructor, the object supplied for `obj` is reinitialized; that is, all instance initializers are executed. The return value is `null`. If a class constructor is invoked, the class is reinitialized; that is, all class initializers are executed. The return value is `null`. - - For pass-by-value primitive parameters, normal widening is performed (Int16 -> Int32, for example). For pass-by-value reference parameters, normal reference widening is allowed (derived class to base class, and base class to interface type). However, for pass-by-reference primitive parameters, the types must match exactly. For pass-by-reference reference parameters, the normal widening still applies. - - For example, if the method reflected by this instance is declared as `public boolean Compare(String a, String b)`, then `parameters` should be an array of `Objects` with length 2 such that `parameters[0] = new Object("SomeString1") and parameters[1] = new Object("SomeString2")`. - - If a parameter of the current method is a value type, and the corresponding argument in `parameters` is `null`, the runtime passes a zero-initialized instance of the value type. - - Reflection uses dynamic method lookup when invoking virtual methods. For example, suppose that class B inherits from class A and both implement a virtual method named M. Now suppose that you have a `MethodInfo` object that represents M on class A. If you use the `Invoke` method to invoke M on an object of type B, then reflection will use the implementation given by class B. Even if the object of type B is cast to A, the implementation given by class B is used (see code sample below). - - On the other hand, if the method is non-virtual, then reflection will use the implementation given by the type from which the `MethodInfo` was obtained, regardless of the type of the object passed as the target. - +> If this method overload is used to invoke an instance constructor, the object supplied for `obj` is reinitialized; that is, all instance initializers are executed. The return value is `null`. If a class constructor is invoked, the class is reinitialized; that is, all class initializers are executed. The return value is `null`. + + For pass-by-value primitive parameters, normal widening is performed (Int16 -> Int32, for example). For pass-by-value reference parameters, normal reference widening is allowed (derived class to base class, and base class to interface type). However, for pass-by-reference primitive parameters, the types must match exactly. For pass-by-reference reference parameters, the normal widening still applies. + + For example, if the method reflected by this instance is declared as `public boolean Compare(String a, String b)`, then `parameters` should be an array of `Objects` with length 2 such that `parameters[0] = new Object("SomeString1") and parameters[1] = new Object("SomeString2")`. + + If a parameter of the current method is a value type, and the corresponding argument in `parameters` is `null`, the runtime passes a zero-initialized instance of the value type. + + Reflection uses dynamic method lookup when invoking virtual methods. For example, suppose that class B inherits from class A and both implement a virtual method named M. Now suppose that you have a `MethodInfo` object that represents M on class A. If you use the `Invoke` method to invoke M on an object of type B, then reflection will use the implementation given by class B. Even if the object of type B is cast to A, the implementation given by class B is used (see code sample below). + + On the other hand, if the method is non-virtual, then reflection will use the implementation given by the type from which the `MethodInfo` was obtained, regardless of the type of the object passed as the target. + Access restrictions are ignored for fully trusted code. That is, private constructors, methods, fields, and properties can be accessed and invoked via reflection whenever the code is fully trusted. If the invoked method throws an exception, the method returns the originating exception. - + > [!NOTE] -> Starting with .NET Framework 2.0, this method can be used to access non-public members if the caller has been granted with the flag and if the grant set of the non-public members is restricted to the caller's grant set, or a subset thereof. (See [Security Considerations for Reflection](/dotnet/framework/reflection-and-codedom/security-considerations-for-reflection).) To use this functionality, your application should target .NET Framework 3.5 or later. - - - -## Examples - The following example demonstrates all members of the class using an overload of . The private method `CanConvertFrom` finds compatible types for a given type. For another example of invoking members in a custom binding scenario, see [Dynamically Loading and Using Types](/dotnet/framework/reflection-and-codedom/dynamically-loading-and-using-types). - +> Starting with .NET Framework 2.0, this method can be used to access non-public members if the caller has been granted with the flag and if the grant set of the non-public members is restricted to the caller's grant set, or a subset thereof. (See [Security Considerations for Reflection](/dotnet/framework/reflection-and-codedom/security-considerations-for-reflection).) To use this functionality, your application should target .NET Framework 3.5 or later. + + + +## Examples + The following example demonstrates all members of the class using an overload of . The private method `CanConvertFrom` finds compatible types for a given type. For another example of invoking members in a custom binding scenario, see [Dynamically Loading and Using Types](/dotnet/framework/reflection-and-codedom/dynamically-loading-and-using-types). + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Binder_1/CPP/binder.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/Binder/Overview/binder.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Binder_1/VB/binder.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Binder_1/VB/binder.vb" id="Snippet1"::: + ]]> - The parameter is and the method is not static. - - -or- - - The method is not declared or inherited by the class of . - - -or- - + The parameter is and the method is not static. + + -or- + + The method is not declared or inherited by the class of . + + -or- + A static constructor is invoked, and is neither nor an instance of the class that declared the constructor. The type of the parameter does not match the signature of the method or constructor reflected by this instance. The array does not have the correct number of arguments. @@ -1288,22 +1288,22 @@ This method dynamically invokes the method reflected by this instance on `obj`, if the method is abstract; otherwise, . - , first get the type. From the type, get the method. From the method, get the `MethodBase`. If the `MethodBase` or constructor is other than public, it is protected and cannot be readily accessed. To access a non-public method, set the mask to `NonPublic` in `GetMethod`. - - - -## Examples - The following example determines whether specified the method is abstract and displays the result. - + , first get the type. From the type, get the method. From the method, get the `MethodBase`. If the `MethodBase` or constructor is other than public, it is protected and cannot be readily accessed. To access a non-public method, set the mask to `NonPublic` in `GetMethod`. + + + +## Examples + The following example determines whether specified the method is abstract and displays the result. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic MethodBase.IsAbstract Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/MethodBase/IsAbstract/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic MethodBase.IsAbstract Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic MethodBase.IsAbstract Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -1358,22 +1358,22 @@ This method dynamically invokes the method reflected by this instance on `obj`, if the visibility of this method or constructor is exactly described by ; otherwise, . - property might be `true` for a method, but if it is a method of a private nested type then the method is not visible outside the containing type. - - The visibility of a method or constructor is exactly described by if the only visibility modifier is `internal` (`Friend` in Visual Basic). This property is `false` for methods that are `protected internal` in C# (`Protected Friend` in Visual Basic, `protected public` in C++); use the property to identify such methods. - - - -## Examples - The following code example defines methods with varying levels of visibility, and displays the values of their , , , and properties. + property might be `true` for a method, but if it is a method of a private nested type then the method is not visible outside the containing type. + + The visibility of a method or constructor is exactly described by if the only visibility modifier is `internal` (`Friend` in Visual Basic). This property is `false` for methods that are `protected internal` in C# (`Protected Friend` in Visual Basic, `protected public` in C++); use the property to identify such methods. + + + +## Examples + The following code example defines methods with varying levels of visibility, and displays the values of their , , , and properties. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic MethodBase.IsAssembly Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/MethodBase/IsAssembly/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic MethodBase.IsAssembly Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic MethodBase.IsAssembly Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -1473,13 +1473,13 @@ This method dynamically invokes the method reflected by this instance on `obj`, if this method is a constructor represented by a object (see note in Remarks about objects); otherwise, . - [!NOTE] -> The property returns `false` for a object in a dynamic type, unless the flag was included in the `attributes` parameter when the constructor was defined. Omitting the flag does not affect the correctness of the emitted constructor. - +> The property returns `false` for a object in a dynamic type, unless the flag was included in the `attributes` parameter when the constructor was defined. Omitting the flag does not affect the correctness of the emitted constructor. + ]]> @@ -1533,20 +1533,20 @@ This method dynamically invokes the method reflected by this instance on `obj`, if access to this method or constructor is exactly described by ; otherwise, . - if the only visibility modifier is `protected`. This property is `false` for methods that are `protected internal` in C# (`Protected Friend` in Visual Basic, `protected public` in C++); use the property to identify such methods. - - - -## Examples - The following code example defines methods with varying levels of visibility, and displays the values of their , , , and properties. + if the only visibility modifier is `protected`. This property is `false` for methods that are `protected internal` in C# (`Protected Friend` in Visual Basic, `protected public` in C++); use the property to identify such methods. + + + +## Examples + The following code example defines methods with varying levels of visibility, and displays the values of their , , , and properties. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic MethodBase.IsAssembly Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/MethodBase/IsAssembly/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic MethodBase.IsAssembly Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic MethodBase.IsAssembly Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -1603,20 +1603,20 @@ This method dynamically invokes the method reflected by this instance on `obj`, if access to this method or constructor is exactly described by ; otherwise, . - if the visibility modifier is `private protected` in C#, `Private Protected` in Visual Basic, or `protected private` in C++. - - - -## Examples - The following code example defines methods with varying levels of visibility, and displays the values of their , , , and properties. + + + +## Examples + The following code example defines methods with varying levels of visibility, and displays the values of their , , , and properties. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic MethodBase.IsAssembly Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/MethodBase/IsAssembly/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic MethodBase.IsAssembly Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic MethodBase.IsAssembly Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -1673,24 +1673,24 @@ This method dynamically invokes the method reflected by this instance on `obj`, if access to this method or constructor is exactly described by ; otherwise, . - visibility, it can be called from any member in a derived class or any member in the same assembly, but not from any other type. - - The actual visibility of a method is limited by the visibility of its type. The property might be `true` for a method, but if it is a method of a private nested type then the method is not visible outside the containing type. - - The visibility of a method or constructor is exactly described by if the visibility modifier is `protected internal` in C# (`Protected Friend` in Visual Basic, `protected public` in C++). - - - -## Examples - The following code example defines methods with varying levels of visibility, and displays the values of their , , , and properties. + visibility, it can be called from any member in a derived class or any member in the same assembly, but not from any other type. + + The actual visibility of a method is limited by the visibility of its type. The property might be `true` for a method, but if it is a method of a private nested type then the method is not visible outside the containing type. + + The visibility of a method or constructor is exactly described by if the visibility modifier is `protected internal` in C# (`Protected Friend` in Visual Basic, `protected public` in C++). + + + +## Examples + The following code example defines methods with varying levels of visibility, and displays the values of their , , , and properties. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic MethodBase.IsAssembly Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/MethodBase/IsAssembly/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic MethodBase.IsAssembly Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic MethodBase.IsAssembly Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -1747,8 +1747,8 @@ This method dynamically invokes the method reflected by this instance on `obj`, if this method is ; otherwise, . - @@ -1823,22 +1823,22 @@ If `IsVirtual` is `false` or `IsFinal` is `true`, then the method cannot be over if the current represents a generic method; otherwise, . - property to determine whether the current object represents a generic method. Use the property to determine whether the current object represents an open constructed method or a closed constructed method. - + property to determine whether the current object represents a generic method. Use the property to determine whether the current object represents an open constructed method or a closed constructed method. + > [!NOTE] -> Generics are not supported by default; this property returns `false` if not overridden in a derived class. Generic constructors are not supported in the .NET Framework version 2.0, so this property returns `false` if the current instance is of type . - -The following table summarizes the invariant conditions for terms specific to generic methods. For other terms used in generic reflection, such as *generic type parameter* and *generic type*, see the property. +> Generics are not supported by default; this property returns `false` if not overridden in a derived class. Generic constructors are not supported in the .NET Framework version 2.0, so this property returns `false` if the current instance is of type . -|Term|Invariant condition| -|---|---| -|generic method definition| The property is `true`.
Defines a generic method. A constructed method is created by calling the method on a object that represents a generic method definition, and specifying an array of type arguments.
The method can be called only on generic method definitions.
Any generic method definition is a generic method, but the converse is not true.| -|generic method|The `IsGenericMethod` property is `true`.
Can be a generic method definition, an open constructed method, or a closed constructed method.| -|open constructed method|The property is `true`.
It is not possible to invoke an open constructed method.| -|closed constructed method|The property is `false`.
When examined recursively, the method has no unassigned generic parameters. The containing type has no generic type parameters, and none of the type arguments have generic type parameters.
The method can be invoked.| +The following table summarizes the invariant conditions for terms specific to generic methods. For other terms used in generic reflection, such as *generic type parameter* and *generic type*, see the property. + +|Term|Invariant condition| +|---|---| +|generic method definition| The property is `true`.
Defines a generic method. A constructed method is created by calling the method on a object that represents a generic method definition, and specifying an array of type arguments.
The method can be called only on generic method definitions.
Any generic method definition is a generic method, but the converse is not true.| +|generic method|The `IsGenericMethod` property is `true`.
Can be a generic method definition, an open constructed method, or a closed constructed method.| +|open constructed method|The property is `true`.
It is not possible to invoke an open constructed method.| +|closed constructed method|The property is `false`.
When examined recursively, the method has no unassigned generic parameters. The containing type has no generic type parameters, and none of the type arguments have generic type parameters.
The method can be invoked.| ]]>
@@ -1892,26 +1892,26 @@ The following table summarizes the invariant conditions for terms specific to ge if the current object represents the definition of a generic method; otherwise, . - represents a generic method definition, then: - -- The property is `true`. - -- For each object in the array returned by the method: - - - The property is `true`. - - - The property returns the current instance. - - - The property is the same as the position of the object in the array. - + represents a generic method definition, then: + +- The property is `true`. + +- For each object in the array returned by the method: + + - The property is `true`. + + - The property returns the current instance. + + - The property is the same as the position of the object in the array. + > [!NOTE] -> Generics are not supported by default; this property returns `false` if not overridden in a derived class. Generic constructors are not supported in the .NET Framework version 2.0, so this property returns `false` if the current instance is of type . - - For a list of the invariant conditions for terms specific to generic methods, see the property. For a list of the invariant conditions for other terms used in generic reflection, see the property. - +> Generics are not supported by default; this property returns `false` if not overridden in a derived class. Generic constructors are not supported in the .NET Framework version 2.0, so this property returns `false` if the current instance is of type . + + For a list of the invariant conditions for terms specific to generic methods, see the property. For a list of the invariant conditions for other terms used in generic reflection, see the property. + ]]> @@ -1965,23 +1965,23 @@ The following table summarizes the invariant conditions for terms specific to ge if the member is hidden by signature; otherwise, . - returns `false` on a member declared with the Visual Basic `Shadows` modifier, and `true` on a member declared with the C# `new` modifier. - + returns `false` on a member declared with the Visual Basic `Shadows` modifier, and `true` on a member declared with the C# `new` modifier. + > [!WARNING] -> This property does not determine whether a method has the attribute. A method that is declared with either the `new` or the `Shadows` modifier will have the attribute, but only methods declared with `new` (that is, only C# methods) will have the property set to `true`. To determine whether a method has the attribute, use code similar to the following: `if ((myMethodInfo.Attributes & MethodAttributes.VtableLayoutMask) == MethodAttributes.NewSlot)` in C# or `If (myMethodInfo.Attributes And MethodAttributes.VtableLayoutMask) = MethodAttributes.NewSlot` in Visual Basic. Note, however, that although all methods declared with `new` or `Shadows` have the attribute, not all methods that have the attribute are declared with `new` or `Shadows`. - - - -## Examples - The following code example contains a base class with an overloaded method, and a derived class that hides one of the overloads. In the Visual Basic version of the code example, the property returns `false` for the member in the derived class. In the C# version of the code sample, the property returns `true` for the member in the derived class. - +> This property does not determine whether a method has the attribute. A method that is declared with either the `new` or the `Shadows` modifier will have the attribute, but only methods declared with `new` (that is, only C# methods) will have the property set to `true`. To determine whether a method has the attribute, use code similar to the following: `if ((myMethodInfo.Attributes & MethodAttributes.VtableLayoutMask) == MethodAttributes.NewSlot)` in C# or `If (myMethodInfo.Attributes And MethodAttributes.VtableLayoutMask) = MethodAttributes.NewSlot` in Visual Basic. Note, however, that although all methods declared with `new` or `Shadows` have the attribute, not all methods that have the attribute are declared with `new` or `Shadows`. + + + +## Examples + The following code example contains a base class with an overloaded method, and a derived class that hides one of the overloads. In the Visual Basic version of the code example, the property returns `false` for the member in the derived class. In the C# version of the code sample, the property returns `true` for the member in the derived class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Reflection.MethodBase.IsHideBySig/cpp/hide.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/MethodBase/IsHideBySig/hide.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Reflection.MethodBase.IsHideBySig/VB/hide.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Reflection.MethodBase.IsHideBySig/VB/hide.vb" id="Snippet1"::: + ]]>
@@ -2034,11 +2034,11 @@ The following table summarizes the invariant conditions for terms specific to ge if access to this method is restricted to other members of the class itself; otherwise, . - @@ -2092,20 +2092,20 @@ The following table summarizes the invariant conditions for terms specific to ge if this method is public; otherwise, . - , first get the type. From the type, get the method. From the method, get the `MethodBase`. If the `MethodBase` or constructor is other than public, it is protected and cannot be readily accessed. To access a non-public method, set the mask to `NonPublic` in `GetMethod`. - - - -## Examples - The following example uses the property to display a message that indicates whether the specified method is public. - + , first get the type. From the type, get the method. From the method, get the `MethodBase`. If the `MethodBase` or constructor is other than public, it is protected and cannot be readily accessed. To access a non-public method, set the mask to `NonPublic` in `GetMethod`. + + + +## Examples + The following example uses the property to display a message that indicates whether the specified method is public. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic MethodBase.IsPublic Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/MethodBase/IsPublic/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic MethodBase.IsPublic Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic MethodBase.IsPublic Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -2152,24 +2152,24 @@ The following table summarizes the invariant conditions for terms specific to ge if the current method or constructor is security-critical or security-safe-critical at the current trust level; if it is transparent. - , , and properties report the transparency level of the method or constructor at its current trust level, as determined by the common language runtime (CLR). The combinations of these properties are shown in the following table: - -|Security level|IsSecurityCritical|IsSecuritySafeCritical|IsSecurityTransparent| -|--------------------|------------------------|----------------------------|---------------------------| -|Critical|`true`|`false`|`false`| -|Safe critical|`true`|`true`|`false`| -|Transparent|`false`|`false`|`true`| - - Using these properties is much simpler than examining the security annotations of an assembly and its types and members, checking the current trust level, and attempting to duplicate the runtime's rules. - + , , and properties report the transparency level of the method or constructor at its current trust level, as determined by the common language runtime (CLR). The combinations of these properties are shown in the following table: + +|Security level|IsSecurityCritical|IsSecuritySafeCritical|IsSecurityTransparent| +|--------------------|------------------------|----------------------------|---------------------------| +|Critical|`true`|`false`|`false`| +|Safe critical|`true`|`true`|`false`| +|Transparent|`false`|`false`|`true`| + + Using these properties is much simpler than examining the security annotations of an assembly and its types and members, checking the current trust level, and attempting to duplicate the runtime's rules. + > [!IMPORTANT] -> For partial-trust assemblies, the value of this property depends on the current trust level of the assembly. If the assembly is loaded into a partially trusted application domain (for example, into a sandboxed application domain), the runtime ignores the security annotations of the assembly. The assembly and all its types are treated as transparent. The runtime pays attention to the security annotations of a partial-trust assembly only when that assembly is loaded into a fully trusted application domain (for example, into the default application domain of a desktop application). By contrast, a trusted assembly (that is, a strong-named assembly that is installed in the global assembly cache) is always loaded with full trust regardless of the trust level of the application domain, so its current trust level is always fully trusted. You can determine the current trust levels of assemblies and application domains by using the and properties. - - For more information about reflection and transparency, see [Security Considerations for Reflection](/dotnet/framework/reflection-and-codedom/security-considerations-for-reflection). For information about transparency, see [Security Changes](/dotnet/framework/security/security-changes). - +> For partial-trust assemblies, the value of this property depends on the current trust level of the assembly. If the assembly is loaded into a partially trusted application domain (for example, into a sandboxed application domain), the runtime ignores the security annotations of the assembly. The assembly and all its types are treated as transparent. The runtime pays attention to the security annotations of a partial-trust assembly only when that assembly is loaded into a fully trusted application domain (for example, into the default application domain of a desktop application). By contrast, a trusted assembly (that is, a strong-named assembly that is installed in the global assembly cache) is always loaded with full trust regardless of the trust level of the application domain, so its current trust level is always fully trusted. You can determine the current trust levels of assemblies and application domains by using the and properties. + + For more information about reflection and transparency, see [Security Considerations for Reflection](/dotnet/framework/reflection-and-codedom/security-considerations-for-reflection). For information about transparency, see [Security Changes](/dotnet/framework/security/security-changes). + ]]> @@ -2218,24 +2218,24 @@ The following table summarizes the invariant conditions for terms specific to ge if the method or constructor is security-safe-critical at the current trust level; if it is security-critical or transparent. - , , and properties report the transparency level of the method or constructor at its current trust level, as determined by the common language runtime (CLR). The combinations of these properties are shown in the following table: - -|Security level|IsSecurityCritical|IsSecuritySafeCritical|IsSecurityTransparent| -|--------------------|------------------------|----------------------------|---------------------------| -|Critical|`true`|`false`|`false`| -|Safe critical|`true`|`true`|`false`| -|Transparent|`false`|`false`|`true`| - - Using these properties is much simpler than examining the security annotations of an assembly and its types and members, checking the current trust level, and attempting to duplicate the runtime's rules. - + , , and properties report the transparency level of the method or constructor at its current trust level, as determined by the common language runtime (CLR). The combinations of these properties are shown in the following table: + +|Security level|IsSecurityCritical|IsSecuritySafeCritical|IsSecurityTransparent| +|--------------------|------------------------|----------------------------|---------------------------| +|Critical|`true`|`false`|`false`| +|Safe critical|`true`|`true`|`false`| +|Transparent|`false`|`false`|`true`| + + Using these properties is much simpler than examining the security annotations of an assembly and its types and members, checking the current trust level, and attempting to duplicate the runtime's rules. + > [!IMPORTANT] -> For partial-trust assemblies, the value of this property depends on the current trust level of the assembly. If the assembly is loaded into a partially trusted application domain (for example, into a sandboxed application domain), the runtime ignores the security annotations of the assembly. The assembly and all its types are treated as transparent. The runtime pays attention to the security annotations of a partial-trust assembly only when that assembly is loaded into a fully trusted application domain (for example, into the default application domain of a desktop application). By contrast, a trusted assembly (that is, a strong-named assembly that is installed in the global assembly cache) is always loaded with full trust regardless of the trust level of the application domain, so its current trust level is always fully trusted. You can determine the current trust levels of assemblies and application domains by using the and properties. - - For more information about reflection and transparency, see [Security Considerations for Reflection](/dotnet/framework/reflection-and-codedom/security-considerations-for-reflection). For information about transparency, see [Security Changes](/dotnet/framework/security/security-changes). - +> For partial-trust assemblies, the value of this property depends on the current trust level of the assembly. If the assembly is loaded into a partially trusted application domain (for example, into a sandboxed application domain), the runtime ignores the security annotations of the assembly. The assembly and all its types are treated as transparent. The runtime pays attention to the security annotations of a partial-trust assembly only when that assembly is loaded into a fully trusted application domain (for example, into the default application domain of a desktop application). By contrast, a trusted assembly (that is, a strong-named assembly that is installed in the global assembly cache) is always loaded with full trust regardless of the trust level of the application domain, so its current trust level is always fully trusted. You can determine the current trust levels of assemblies and application domains by using the and properties. + + For more information about reflection and transparency, see [Security Considerations for Reflection](/dotnet/framework/reflection-and-codedom/security-considerations-for-reflection). For information about transparency, see [Security Changes](/dotnet/framework/security/security-changes). + ]]> @@ -2284,18 +2284,18 @@ The following table summarizes the invariant conditions for terms specific to ge if the method or constructor is security-transparent at the current trust level; otherwise, . - and properties return `false`. - - The , , and properties report the transparency level of the method or constructor at its current trust level, as determined by the common language runtime (CLR). Using these properties is much simpler than examining the security annotations of an assembly and its types and members, checking the current trust level, and attempting to duplicate the runtime's rules. - + and properties return `false`. + + The , , and properties report the transparency level of the method or constructor at its current trust level, as determined by the common language runtime (CLR). Using these properties is much simpler than examining the security annotations of an assembly and its types and members, checking the current trust level, and attempting to duplicate the runtime's rules. + > [!IMPORTANT] -> For partial-trust assemblies, the value of this property depends on the current trust level of the assembly. If the assembly is loaded into a partially trusted application domain (for example, into a sandboxed application domain), the runtime ignores the security annotations of the assembly. The assembly and all its types are treated as transparent. The runtime pays attention to the security annotations of a partial-trust assembly only when that assembly is loaded into a fully trusted application domain (for example, into the default application domain of a desktop application). By contrast, a trusted assembly (that is, a strong-named assembly that is installed in the global assembly cache) is always loaded with full trust regardless of the trust level of the application domain, so its current trust level is always fully trusted. You can determine the current trust levels of assemblies and application domains by using the and properties. - - For more information about reflection and transparency, see [Security Considerations for Reflection](/dotnet/framework/reflection-and-codedom/security-considerations-for-reflection). For information about transparency, see [Security Changes](/dotnet/framework/security/security-changes). - +> For partial-trust assemblies, the value of this property depends on the current trust level of the assembly. If the assembly is loaded into a partially trusted application domain (for example, into a sandboxed application domain), the runtime ignores the security annotations of the assembly. The assembly and all its types are treated as transparent. The runtime pays attention to the security annotations of a partial-trust assembly only when that assembly is loaded into a fully trusted application domain (for example, into the default application domain of a desktop application). By contrast, a trusted assembly (that is, a strong-named assembly that is installed in the global assembly cache) is always loaded with full trust regardless of the trust level of the application domain, so its current trust level is always fully trusted. You can determine the current trust levels of assemblies and application domains by using the and properties. + + For more information about reflection and transparency, see [Security Considerations for Reflection](/dotnet/framework/reflection-and-codedom/security-considerations-for-reflection). For information about transparency, see [Security Changes](/dotnet/framework/security/security-changes). + ]]> @@ -2352,20 +2352,20 @@ The following table summarizes the invariant conditions for terms specific to ge if this method has a special name; otherwise, . - bit is set to flag members that are treated in a special way by some compilers (such as property accessors and operator overloading methods). - - - -## Examples - This example shows a use of to filter internal or private members out of a list. - + bit is set to flag members that are treated in a special way by some compilers (such as property accessors and operator overloading methods). + + + +## Examples + This example shows a use of to filter internal or private members out of a list. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Type.IsSpecialName Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/MethodBase/IsSpecialName/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Type.IsSpecialName Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Type.IsSpecialName Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -2420,11 +2420,11 @@ The following table summarizes the invariant conditions for terms specific to ge if this method is ; otherwise, . - @@ -2479,39 +2479,39 @@ The following table summarizes the invariant conditions for terms specific to ge if this method is ; otherwise, . - must be `false`. For example, a method might be non-virtual, but it implements an interface method. The common language runtime requires that all methods that implement interface members must be marked as `virtual`; therefore, the compiler marks the method `virtual final`. So there are cases where a method is marked as `virtual` but is still not overridable. - - To establish with certainty whether a method is overridable, use code such as this: - -```csharp -if (MethodInfo.IsVirtual && !MethodInfo.IsFinal) -``` - -```vb -If MethodInfo.IsVirtual AndAlso Not MethodInfo.IsFinal Then -``` - - If `IsVirtual` is `false` or `IsFinal` is `true`, then the method cannot be overridden. - - You can determine whether the current method overrides a method in a base class by calling the method. The following example implements an `IsOverride` method that does this. - + must be `false`. For example, a method might be non-virtual, but it implements an interface method. The common language runtime requires that all methods that implement interface members must be marked as `virtual`; therefore, the compiler marks the method `virtual final`. So there are cases where a method is marked as `virtual` but is still not overridable. + + To establish with certainty whether a method is overridable, use code such as this: + +```csharp +if (MethodInfo.IsVirtual && !MethodInfo.IsFinal) +``` + +```vb +If MethodInfo.IsVirtual AndAlso Not MethodInfo.IsFinal Then +``` + + If `IsVirtual` is `false` or `IsFinal` is `true`, then the method cannot be overridden. + + You can determine whether the current method overrides a method in a base class by calling the method. The following example implements an `IsOverride` method that does this. + :::code language="csharp" source="~/snippets/csharp/System.Reflection/MethodBase/IsVirtual/IsOverride1.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.reflection.methodinfo.getbasedefinition/vb/IsOverride1.vb" id="Snippet2"::: - - - -## Examples - The following example displays `false` for `IsFinal`, which might lead you to think that `MyMethod` is overridable. The code prints `false` even though `MyMethod` is not marked `virtual` and thus cannot be overridden. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.reflection.methodinfo.getbasedefinition/vb/IsOverride1.vb" id="Snippet2"::: + + + +## Examples + The following example displays `false` for `IsFinal`, which might lead you to think that `MyMethod` is overridable. The code prints `false` even though `MyMethod` is not marked `virtual` and thus cannot be overridden. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic MethodBase.IsVirtual Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/MethodBase/IsFinal/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic MethodBase.IsVirtual Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic MethodBase.IsVirtual Example/VB/source.vb" id="Snippet1"::: + ]]>
@@ -2560,11 +2560,11 @@ If MethodInfo.IsVirtual AndAlso Not MethodInfo.IsFinal Then Gets a handle to the internal metadata representation of a method. A object. -
@@ -2614,11 +2614,11 @@ If MethodInfo.IsVirtual AndAlso Not MethodInfo.IsFinal Then Gets the flags that specify the attributes of a method implementation. The method implementation flags. - method for more information. - + method for more information. + ]]>
@@ -2660,8 +2660,8 @@ If MethodInfo.IsVirtual AndAlso Not MethodInfo.IsFinal Then System.Boolean - - + + The first object to compare. @@ -2709,8 +2709,8 @@ If MethodInfo.IsVirtual AndAlso Not MethodInfo.IsFinal Then System.Boolean - - + + The first object to compare. @@ -2751,11 +2751,11 @@ If MethodInfo.IsVirtual AndAlso Not MethodInfo.IsFinal Then System.Void - - - - - + + + + + Reserved for future use. Must be IID_NULL. @@ -2765,11 +2765,11 @@ If MethodInfo.IsVirtual AndAlso Not MethodInfo.IsFinal Then Caller-allocated array which receives the IDs corresponding to the names. Maps a set of names to a corresponding set of dispatch identifiers. - Late-bound access using the COM IDispatch interface is not supported. @@ -2808,11 +2808,11 @@ If MethodInfo.IsVirtual AndAlso Not MethodInfo.IsFinal Then 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. + ]]> @@ -2847,9 +2847,9 @@ If MethodInfo.IsVirtual AndAlso Not MethodInfo.IsFinal Then System.Void - - - + + + The type information to return. @@ -2857,11 +2857,11 @@ If MethodInfo.IsVirtual AndAlso Not MethodInfo.IsFinal Then Receives a pointer to the requested type information object. Retrieves the type information for an object, which can then be used to get the type information for an interface. - Late-bound access using the COM IDispatch interface is not supported. @@ -2897,17 +2897,17 @@ If MethodInfo.IsVirtual AndAlso Not MethodInfo.IsFinal Then System.Void - + Points to a location that receives the number of type information interfaces provided by the object. Retrieves the number of type information interfaces that an object provides (either 0 or 1). - Late-bound access using the COM IDispatch interface is not supported. @@ -2943,14 +2943,14 @@ If MethodInfo.IsVirtual AndAlso Not MethodInfo.IsFinal Then System.Void - - - - - - - - + + + + + + + + Identifies the member. @@ -2963,11 +2963,11 @@ If MethodInfo.IsVirtual AndAlso Not MethodInfo.IsFinal Then The index of the first argument that has an error. Provides access to properties and methods exposed by an object. - Late-bound access using the COM IDispatch interface is not supported. @@ -3005,11 +3005,11 @@ If MethodInfo.IsVirtual AndAlso Not MethodInfo.IsFinal Then 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. + ]]> @@ -3046,11 +3046,11 @@ If MethodInfo.IsVirtual AndAlso Not MethodInfo.IsFinal Then 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. + ]]> @@ -3087,11 +3087,11 @@ If MethodInfo.IsVirtual AndAlso Not MethodInfo.IsFinal Then 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. + ]]> @@ -3128,11 +3128,11 @@ If MethodInfo.IsVirtual AndAlso Not MethodInfo.IsFinal Then 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. + ]]> @@ -3169,11 +3169,11 @@ If MethodInfo.IsVirtual AndAlso Not MethodInfo.IsFinal Then 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. + ]]> @@ -3210,11 +3210,11 @@ If MethodInfo.IsVirtual AndAlso Not MethodInfo.IsFinal Then 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. + ]]>
@@ -3251,11 +3251,11 @@ If MethodInfo.IsVirtual AndAlso Not MethodInfo.IsFinal Then 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. + ]]>
@@ -3292,11 +3292,11 @@ If MethodInfo.IsVirtual AndAlso Not MethodInfo.IsFinal Then 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. + ]]>
@@ -3333,11 +3333,11 @@ If MethodInfo.IsVirtual AndAlso Not MethodInfo.IsFinal Then 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. + ]]>
@@ -3374,11 +3374,11 @@ If MethodInfo.IsVirtual AndAlso Not MethodInfo.IsFinal Then 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. + ]]>
@@ -3415,11 +3415,11 @@ If MethodInfo.IsVirtual AndAlso Not MethodInfo.IsFinal Then 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. + ]]>
@@ -3456,11 +3456,11 @@ If MethodInfo.IsVirtual AndAlso Not MethodInfo.IsFinal Then 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. + ]]>
@@ -3497,11 +3497,11 @@ If MethodInfo.IsVirtual AndAlso Not MethodInfo.IsFinal Then 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. + ]]>
diff --git a/xml/System.Reflection/MethodInfo.xml b/xml/System.Reflection/MethodInfo.xml index 02721dae94b..8eefa2edd5d 100644 --- a/xml/System.Reflection/MethodInfo.xml +++ b/xml/System.Reflection/MethodInfo.xml @@ -92,27 +92,27 @@ Discovers the attributes of a method and provides access to method metadata. - class represents a method of a type. You can use a object to obtain information about the method that the object represents and to invoke the method. For example: - -- You can determine the method's visibility by retrieving the values of the , , , and properties. - -- You can discover what attributes are applied to the method by retrieving the value of the property or calling the method. - -- You can determine whether the method is a generic method, an open constructed generic method, or a closed constructed generic method, by retrieving the values of the and properties. - -- You can get information about the method's parameters and return type from the method and the , , and properties. - -- You can execute a method on a class instance by calling the method. - -- You can instantiate a object that represents a constructed generic method from one that represents a generic method definition by calling the method. - - You can instantiate a instances by calling the or method, or by calling the method of a object that represents a generic method definition. - - For a list of the invariant conditions for terms specific to generic methods, see the property. For a list of the invariant conditions for other terms used in generic reflection, see the property. - + class represents a method of a type. You can use a object to obtain information about the method that the object represents and to invoke the method. For example: + +- You can determine the method's visibility by retrieving the values of the , , , and properties. + +- You can discover what attributes are applied to the method by retrieving the value of the property or calling the method. + +- You can determine whether the method is a generic method, an open constructed generic method, or a closed constructed generic method, by retrieving the values of the and properties. + +- You can get information about the method's parameters and return type from the method and the , , and properties. + +- You can execute a method on a class instance by calling the method. + +- You can instantiate a object that represents a constructed generic method from one that represents a generic method definition by calling the method. + + You can instantiate a instances by calling the or method, or by calling the method of a object that represents a generic method definition. + + For a list of the invariant conditions for terms specific to generic methods, see the property. For a list of the invariant conditions for other terms used in generic reflection, see the property. + ]]> This type is thread safe. @@ -125,11 +125,11 @@ - - - - - + + + + + Constructor mscorlib @@ -196,11 +196,11 @@ ## Remarks -To invoke a generic method, there must be no generic type definitions or open constructed types in the type arguments of the method itself, or in any enclosing types. -Making this recursive determination can be difficult. For convenience, and to reduce the chance of error, the `ContainsGenericParameters` property provides a standard way to distinguish between closed constructed methods, which can be invoked, and open constructed methods, which cannot. +To invoke a generic method, there must be no generic type definitions or open constructed types in the type arguments of the method itself, or in any enclosing types. +Making this recursive determination can be difficult. For convenience, and to reduce the chance of error, the `ContainsGenericParameters` property provides a standard way to distinguish between closed constructed methods, which can be invoked, and open constructed methods, which cannot. If the `ContainsGenericParameters` property returns `true`, the method cannot be invoked. -The `ContainsGenericParameters` property searches recursively for type parameters. +The `ContainsGenericParameters` property searches recursively for type parameters. For example, it returns `true` for any method in an open type `A`, even though the method itself is not generic. Contrast this with the behavior of the property, which returns `false` for such a method. @@ -541,44 +541,44 @@ For a list of the invariant conditions for other terms used in generic reflectio When overridden in a derived class, returns the object for the method on the direct or indirect base class in which the method represented by this instance was first declared. A object for the first implementation of this method. - method returns the first definition of the specified method in the class hierarchy. You can determine the type on which the first definition of the method is found by retrieving the value of the property on the returned object. - - The method behaves as follows: - -- If the current object represents an interface implementation, the method returns the current object. - -- If the current object represents a method that overrides a virtual definition in a base class, the method returns a object that represents the virtual definition. - -- If the current object represents a method that is specified with the `new` keyword in C# or the `Shadows` keyword in Visual Basic (as in `newslot`, as described in [Common Type System](/dotnet/standard/base-types/common-type-system)), the method returns the current object. - -- If the current object represents an inherited method (that is, the current method does not provide its own implementation), the method returns a object that represents the lowest method in the class hierarchy. For example, if `Base.ToString` overrides `Object.ToString`, and `Derived.ToString` overrides `Base.ToString`, calling the method on a object that represents `Derived.ToString` returns a object that represents `Object.ToString`. - -- If the current object represents a method that is not present in any base class, the method returns the current object. - - You can determine whether the current method overrides a method in a base class by calling the method. The following example implements an `IsOverride` method that does this. - + method returns the first definition of the specified method in the class hierarchy. You can determine the type on which the first definition of the method is found by retrieving the value of the property on the returned object. + + The method behaves as follows: + +- If the current object represents an interface implementation, the method returns the current object. + +- If the current object represents a method that overrides a virtual definition in a base class, the method returns a object that represents the virtual definition. + +- If the current object represents a method that is specified with the `new` keyword in C# or the `Shadows` keyword in Visual Basic (as in `newslot`, as described in [Common Type System](/dotnet/standard/base-types/common-type-system)), the method returns the current object. + +- If the current object represents an inherited method (that is, the current method does not provide its own implementation), the method returns a object that represents the lowest method in the class hierarchy. For example, if `Base.ToString` overrides `Object.ToString`, and `Derived.ToString` overrides `Base.ToString`, calling the method on a object that represents `Derived.ToString` returns a object that represents `Object.ToString`. + +- If the current object represents a method that is not present in any base class, the method returns the current object. + + You can determine whether the current method overrides a method in a base class by calling the method. The following example implements an `IsOverride` method that does this. + :::code language="csharp" source="~/snippets/csharp/System.Reflection/MethodBase/IsVirtual/IsOverride1.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.reflection.methodinfo.getbasedefinition/vb/IsOverride1.vb" id="Snippet2"::: - - To call the `GetBaseDefinition` method: - -1. Get a object that represents the type (the class or structure) that contains the property. If you are working with an object (an instance of a type), you can call its method. Otherwise, you can use the C# operator or the Visual Basic [GetType](/dotnet/visual-basic/language-reference/operators/gettype-operator) operator, as the example illustrates. - -2. Get a object that represents the method in which you're interested. You can do this by getting an array of all methods from the method and then iterating the elements in the array, or you can retrieve the object that represents the method directly by calling the method and specifying the method name. - -3. Call the method to get the value of the object that represents the base method definition. - - - -## Examples - The following example demonstrates the behavior of the method. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.reflection.methodinfo.getbasedefinition/vb/IsOverride1.vb" id="Snippet2"::: + + To call the `GetBaseDefinition` method: + +1. Get a object that represents the type (the class or structure) that contains the property. If you are working with an object (an instance of a type), you can call its method. Otherwise, you can use the C# operator or the Visual Basic [GetType](/dotnet/visual-basic/language-reference/operators/gettype-operator) operator, as the example illustrates. + +2. Get a object that represents the method in which you're interested. You can do this by getting an array of all methods from the method and then iterating the elements in the array, or you can retrieve the object that represents the method directly by calling the method and specifying the method name. + +3. Call the method to get the value of the object that represents the base method definition. + + + +## Examples + The following example demonstrates the behavior of the method. + :::code language="csharp" source="~/snippets/csharp/System.Reflection/MethodBase/IsVirtual/getbasedefinition1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.reflection.methodinfo.getbasedefinition/vb/getbasedefinition1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.reflection.methodinfo.getbasedefinition/vb/getbasedefinition1.vb" id="Snippet1"::: + ]]> Common Type System @@ -634,28 +634,28 @@ For a list of the invariant conditions for other terms used in generic reflectio Returns an array of objects that represent the type arguments of a generic method or the type parameters of a generic method definition. An array of objects that represent the type arguments of a generic method or the type parameters of a generic method definition. Returns an empty array if the current method is not a generic method. - property returns `false`), the array returned by the method contains the types that have been assigned to the generic type parameters of the generic method definition. - -- If the current method is a generic method definition, the array contains the type parameters. - -- If the current method is an open constructed method (that is, the property returns `true`) in which specific types have been assigned to some type parameters and type parameters of enclosing generic types have been assigned to other type parameters, the array contains both types and type parameters. Use the property to tell them apart. For a demonstration of this scenario, see the code example for the property. - - For a list of the invariant conditions for terms specific to generic methods, see the property. For a list of the invariant conditions for other terms used in generic reflection, see the property. - -## Examples - The following code example shows how to get the type arguments of a generic method and display them. - - This example is part of a larger example provided for the method. - + property returns `false`), the array returned by the method contains the types that have been assigned to the generic type parameters of the generic method definition. + +- If the current method is a generic method definition, the array contains the type parameters. + +- If the current method is an open constructed method (that is, the property returns `true`) in which specific types have been assigned to some type parameters and type parameters of enclosing generic types have been assigned to other type parameters, the array contains both types and type parameters. Use the property to tell them apart. For a demonstration of this scenario, see the code example for the property. + + For a list of the invariant conditions for terms specific to generic methods, see the property. For a list of the invariant conditions for other terms used in generic reflection, see the property. + +## Examples + The following code example shows how to get the type arguments of a generic method and display them. + + This example is part of a larger example provided for the method. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/MethodInfo.Generics/cpp/source.cpp" id="Snippet8"::: :::code language="csharp" source="~/snippets/csharp/System/Type/DeclaringMethod/source.cs" id="Snippet8"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/MethodInfo.Generics/VB/source.vb" id="Snippet8"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/MethodInfo.Generics/VB/source.vb" id="Snippet8"::: + ]]> This method is not supported. @@ -717,58 +717,58 @@ For a list of the invariant conditions for other terms used in generic reflectio Returns a object that represents a generic method definition from which the current method can be constructed. A object representing a generic method definition from which the current method can be constructed. - (T t)` (expressed in C# syntax; `Function M(Of T)(ByVal tVal As T) As T` in Visual Basic) you can construct and invoke the method `int M(int t)` (`Function M(Of Integer)(ByVal tVal As Integer) As Integer` in Visual Basic). Given a object representing this constructed method, the method returns the generic method definition. - - If two constructed methods are created from the same generic method definition, the method returns the same object for both methods. - - If you call on a that already represents a generic method definition, it returns the current . - - If a generic method definition includes generic parameters of the declaring type, there will be a generic method definition specific to each constructed type. For example, consider the following C#, Visual Basic, and C++ code: - -``` -class B {} -class C { public B M() {...}} - -Class B(Of U, V) -End Class -Class C(Of T) - Public Function M(Of S)() As B(Of T, S) - ... - End Function -End Class - -generic ref class B {}; -generic ref class C -{ -public: - generic B^ M() {...}; -}; -``` - - In the constructed type `C` (`C(Of Integer)` in Visual Basic), the generic method `M` returns `B`. In the open type `C`, `M` returns `B`. In both cases, the property returns `true` for the that represents `M`, so can be called on both objects. In the case of the constructed type, the result of calling is a that can be invoked. In the case of the open type, the returned by cannot be invoked. - - For a list of the invariant conditions for terms specific to generic methods, see the property. For a list of the invariant conditions for other terms used in generic reflection, see the property. - - - -## Examples - The following code example shows a class with a generic method and the code required to obtain a for the method, bind the method to type arguments, and get the original generic type definition back from the bound method. - - This example is part of a larger example provided for the method. - + (T t)` (expressed in C# syntax; `Function M(Of T)(ByVal tVal As T) As T` in Visual Basic) you can construct and invoke the method `int M(int t)` (`Function M(Of Integer)(ByVal tVal As Integer) As Integer` in Visual Basic). Given a object representing this constructed method, the method returns the generic method definition. + + If two constructed methods are created from the same generic method definition, the method returns the same object for both methods. + + If you call on a that already represents a generic method definition, it returns the current . + + If a generic method definition includes generic parameters of the declaring type, there will be a generic method definition specific to each constructed type. For example, consider the following C#, Visual Basic, and C++ code: + +``` +class B {} +class C { public B M() {...}} + +Class B(Of U, V) +End Class +Class C(Of T) + Public Function M(Of S)() As B(Of T, S) + ... + End Function +End Class + +generic ref class B {}; +generic ref class C +{ +public: + generic B^ M() {...}; +}; +``` + + In the constructed type `C` (`C(Of Integer)` in Visual Basic), the generic method `M` returns `B`. In the open type `C`, `M` returns `B`. In both cases, the property returns `true` for the that represents `M`, so can be called on both objects. In the case of the constructed type, the result of calling is a that can be invoked. In the case of the open type, the returned by cannot be invoked. + + For a list of the invariant conditions for terms specific to generic methods, see the property. For a list of the invariant conditions for other terms used in generic reflection, see the property. + + + +## Examples + The following code example shows a class with a generic method and the code required to obtain a for the method, bind the method to type arguments, and get the original generic type definition back from the bound method. + + This example is part of a larger example provided for the method. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/MethodInfo.Generics/cpp/source.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System/Type/DeclaringMethod/source.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/MethodInfo.Generics/VB/source.vb" id="Snippet2"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/MethodInfo.Generics/VB/source.vb" id="Snippet2"::: :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/MethodInfo.Generics/cpp/source.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System/Type/DeclaringMethod/source.cs" id="Snippet3"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/MethodInfo.Generics/VB/source.vb" id="Snippet3"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/MethodInfo.Generics/VB/source.vb" id="Snippet3"::: :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/MethodInfo.Generics/cpp/source.cpp" id="Snippet4"::: :::code language="csharp" source="~/snippets/csharp/System/Type/DeclaringMethod/source.cs" id="Snippet4"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/MethodInfo.Generics/VB/source.vb" id="Snippet4"::: - +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/MethodInfo.Generics/VB/source.vb" id="Snippet4"::: + ]]> The current method is not a generic method. That is, returns . @@ -901,7 +901,7 @@ public: The object on which to invoke the method or constructor. If a method is static, this argument is ignored. If a constructor is static, this argument must be or an instance of the class that defines the constructor. - An argument list for the invoked method or constructor. This is an array of objects with the same number, order, and type as the parameters of the method or constructor to be invoked. If there are no parameters, should be . + An argument list for the invoked method or constructor. This is an array of objects with the same number, order, and type as the parameters of the method or constructor to be invoked. If there are no parameters, should be . If the method or constructor represented by this instance takes a parameter ( in Visual Basic), no special attribute is required for that parameter in order to invoke the method or constructor using this function. Any object in this array that is not explicitly initialized with a value will contain the default value for that object type. For reference-type elements, this value is . For value-type elements, this value is 0, 0.0, or , depending on the specific element type. Invokes the method or constructor represented by the current instance, using the specified parameters. An object containing the return value of the invoked method, or in the case of a constructor. @@ -969,7 +969,7 @@ public: represents a generic method definition, then: - `IsGenericMethodDefinition` returns `true`. @@ -1055,7 +1055,7 @@ In the constructed type `C` (`C(Of Integer)` in Visual Basic), the generic For a list of the invariant conditions for terms specific to generic methods, see the property. For a list of the invariant conditions for other terms used in generic reflection, see the property. -## Examples +## Examples The following code example uses the `IsGenericMethodDefinition` property to display a message indicating whether a represents a generic method definition. This example is part of a larger example provided for the method. @@ -1067,12 +1067,12 @@ Console.WriteLine(vbTab _ ``` ```csharp -Console.WriteLine("\tIs this a generic method definition? {0}", +Console.WriteLine("\tIs this a generic method definition? {0}", mi.IsGenericMethodDefinition); ``` ```cpp -Console::WriteLine("\tIs this a generic method definition? {0}", +Console::WriteLine("\tIs this a generic method definition? {0}", mi->IsGenericMethodDefinition); ``` @@ -1147,82 +1147,82 @@ Console::WriteLine("\tIs this a generic method definition? {0}", Substitutes the elements of an array of types for the type parameters of the current generic method definition, and returns a object representing the resulting constructed method. A object that represents the constructed method formed by substituting the elements of for the type parameters of the current generic method definition. - method allows you to write code that assigns specific types to the type parameters of a generic method definition, thus creating a object that represents a particular constructed method. If the property of this object returns `true`, you can use it to invoke the method or to create a delegate to invoke the method. - - Methods constructed with the method can be open, that is, some of their type arguments can be type parameters of enclosing generic types. You might use such open constructed methods when you generate dynamic assemblies. For example, consider the following C#, Visual Basic, and C++ code. - -``` -class C -{ - T N(T t, U u) {...} - public V M(V v) - { - return N(v, 42); - } -} - -Class C - Public Function N(Of T,U)(ByVal ta As T, ByVal ua As U) As T - ... - End Function - Public Function M(Of V)(ByVal va As V ) As V - Return N(Of V, Integer)(va, 42) - End Function -End Class - -ref class C -{ -private: - generic T N(T t, U u) {...} -public: - generic V M(V v) - { - return N(v, 42); - } -}; -``` - - The method body of `M` contains a call to method `N`, specifying the type parameter of `M` and the type . The property returns `false` for method `N`. The property returns `true`, so method `N` cannot be invoked. - - For a list of the invariant conditions for terms specific to generic methods, see the property. For a list of the invariant conditions for other terms used in generic reflection, see the property. - - - -## Examples - The following code example demonstrates the properties and methods of that support the examination of generic methods. The example does the following: - -- Defines a class that has a generic method. - -- Creates a that represents the generic method. - -- Displays properties of the generic method definition. - -- Assigns type arguments to the type parameters of the , and invokes the resulting constructed generic method. - -- Displays properties of the constructed generic method. - -- Retrieves the generic method definition from the constructed method and compares it to the original definition. - + method allows you to write code that assigns specific types to the type parameters of a generic method definition, thus creating a object that represents a particular constructed method. If the property of this object returns `true`, you can use it to invoke the method or to create a delegate to invoke the method. + + Methods constructed with the method can be open, that is, some of their type arguments can be type parameters of enclosing generic types. You might use such open constructed methods when you generate dynamic assemblies. For example, consider the following C#, Visual Basic, and C++ code. + +``` +class C +{ + T N(T t, U u) {...} + public V M(V v) + { + return N(v, 42); + } +} + +Class C + Public Function N(Of T,U)(ByVal ta As T, ByVal ua As U) As T + ... + End Function + Public Function M(Of V)(ByVal va As V ) As V + Return N(Of V, Integer)(va, 42) + End Function +End Class + +ref class C +{ +private: + generic T N(T t, U u) {...} +public: + generic V M(V v) + { + return N(v, 42); + } +}; +``` + + The method body of `M` contains a call to method `N`, specifying the type parameter of `M` and the type . The property returns `false` for method `N`. The property returns `true`, so method `N` cannot be invoked. + + For a list of the invariant conditions for terms specific to generic methods, see the property. For a list of the invariant conditions for other terms used in generic reflection, see the property. + + + +## Examples + The following code example demonstrates the properties and methods of that support the examination of generic methods. The example does the following: + +- Defines a class that has a generic method. + +- Creates a that represents the generic method. + +- Displays properties of the generic method definition. + +- Assigns type arguments to the type parameters of the , and invokes the resulting constructed generic method. + +- Displays properties of the constructed generic method. + +- Retrieves the generic method definition from the constructed method and compares it to the original definition. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/MethodInfo.Generics/cpp/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System/Type/DeclaringMethod/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/MethodInfo.Generics/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/MethodInfo.Generics/VB/source.vb" id="Snippet1"::: + ]]> The current does not represent a generic method definition. That is, returns . - is . - - -or- - + is . + + -or- + Any element of is . - The number of elements in is not the same as the number of type parameters of the current generic method definition. - - -or- - + The number of elements in is not the same as the number of type parameters of the current generic method definition. + + -or- + An element of does not satisfy the constraints specified for the corresponding type parameter of the current generic method definition. This method is not supported. @@ -1276,22 +1276,22 @@ public: Gets a value indicating that this member is a method. A value indicating that this member is a method. - . Therefore, when you examine a set of objects - for example, the array returned by - the property returns only when a given member is a method. - - To get the `MemberType` property, first get the class `Type`. From the `Type`, get the `MethodInfo`. From the `MethodInfo`, get the `MemberType`. - - - -## Examples - The following example displays the type of the specified member. - + . Therefore, when you examine a set of objects - for example, the array returned by - the property returns only when a given member is a method. + + To get the `MemberType` property, first get the class `Type`. From the `Type`, get the `MethodInfo`. From the `MethodInfo`, get the `MemberType`. + + + +## Examples + The following example displays the type of the specified member. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic MethodInfo.MemberType Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/MethodInfo/MemberType/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic MethodInfo.MemberType Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic MethodInfo.MemberType Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -1339,8 +1339,8 @@ public: System.Boolean - - + + The first object to compare. @@ -1398,8 +1398,8 @@ public: System.Boolean - - + + The first object to compare. @@ -1453,11 +1453,11 @@ public: Gets a object that contains information about the return type of the method, such as whether the return type has custom modifiers. A object that contains information about the return type. - object returned by this property to discover whether custom modifiers, such as , have been applied to the return type. - + object returned by this property to discover whether custom modifiers, such as , have been applied to the return type. + ]]> This method is not implemented. @@ -1515,20 +1515,20 @@ public: Gets the return type of this method. The return type of this method. - @@ -1610,11 +1610,11 @@ public: System.Void - - - - - + + + + + Reserved for future use. Must be IID_NULL. @@ -1624,11 +1624,11 @@ public: Caller-allocated array that receives the IDs corresponding to the names. Maps a set of names to a corresponding set of dispatch identifiers. - Late-bound access using the COM IDispatch interface is not supported. @@ -1699,9 +1699,9 @@ public: System.Void - - - + + + The type information to return. @@ -1709,11 +1709,11 @@ public: Receives a pointer to the requested type information object. Retrieves the type information for an object, which can be used to get the type information for an interface. - Late-bound access using the COM IDispatch interface is not supported. @@ -1749,17 +1749,17 @@ public: System.Void - + Points to a location that receives the number of type information interfaces provided by the object. Retrieves the number of type information interfaces that an object provides (either 0 or 1). - Late-bound access using the COM IDispatch interface is not supported. @@ -1795,14 +1795,14 @@ public: System.Void - - - - - - - - + + + + + + + + Identifies the member. @@ -1815,11 +1815,11 @@ public: The index of the first argument that has an error. Provides access to properties and methods exposed by an object. - Late-bound access using the COM IDispatch interface is not supported. diff --git a/xml/System.Reflection/Missing.xml b/xml/System.Reflection/Missing.xml index a9a8feffa92..3acae4305c1 100644 --- a/xml/System.Reflection/Missing.xml +++ b/xml/System.Reflection/Missing.xml @@ -79,21 +79,21 @@ Represents a missing . This class cannot be inherited. - class is used to invoke a method with a default argument, typically when using reflection. - - Only one instance of , which is returned by the field, ever exists. - - - -## Examples - The following example shows how to use the object to invoke a method with a default argument by using reflection. - + class is used to invoke a method with a default argument, typically when using reflection. + + Only one instance of , which is returned by the field, ever exists. + + + +## Examples + The following example shows how to use the object to invoke a method with a default argument by using reflection. + :::code language="csharp" source="~/snippets/csharp/System.Reflection/Missing/Overview/Missing1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/System.Reflection.Missing/vb/Missing1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/System.Reflection.Missing/vb/Missing1.vb" id="Snippet1"::: + ]]> @@ -145,8 +145,8 @@ System.Void - - + + The object to be populated with serialization information. @@ -208,11 +208,11 @@ Represents the sole instance of the class. - class to represent missing values, for example, when you invoke methods that have default parameter values. For a code example, see the class. - + class to represent missing values, for example, when you invoke methods that have default parameter values. For a code example, see the class. + ]]> diff --git a/xml/System.Reflection/Module.xml b/xml/System.Reflection/Module.xml index 47880a74ffb..6e8795372fd 100644 --- a/xml/System.Reflection/Module.xml +++ b/xml/System.Reflection/Module.xml @@ -112,33 +112,33 @@ Performs reflection on a module. - - - - - - + + + + + Constructor mscorlib @@ -168,11 +168,11 @@ Initializes a new instance of the class. - objects. - + objects. + ]]> @@ -224,15 +224,15 @@ Gets the appropriate for this instance of . An object. - @@ -379,20 +379,20 @@ A object that filters the list of types defined in this module based upon the name. This field is case-sensitive and read-only. - @@ -439,20 +439,20 @@ A object that filters the list of types defined in this module based upon the name. This field is case-insensitive and read-only. - @@ -508,8 +508,8 @@ System.Type[] - - + + The delegate used to filter the classes. @@ -517,24 +517,24 @@ Returns an array of classes accepted by the given filter and filter criteria. An array of type containing classes that were accepted by the filter. - is a special class load exception. The `ReflectionTypeLoadException.Types` property contains the array of classes that were defined in the module and were loaded. This array may contain some null values. The `ReflectionTypeLoadException.LoaderExceptions` property is an array of exceptions that represent the exceptions that were thrown by the class loader. The holes in the class array line up with the exceptions. - - The delegate given by `filter` is called for each class in the module, passing along the `Type` object representing the class as well as the given `filterCriteria`. If `filter` returns a particular class, that class will be included in the returned array. If `filter` returns `null`, all classes are returned and `filterCriteria` is ignored. - - `FindTypes` cannot be used to look up parameterized types such as arrays. - - - -## Examples - The following example demonstrates the `FindTypes` method. - + is a special class load exception. The `ReflectionTypeLoadException.Types` property contains the array of classes that were defined in the module and were loaded. This array may contain some null values. The `ReflectionTypeLoadException.LoaderExceptions` property is an array of exceptions that represent the exceptions that were thrown by the class loader. The holes in the class array line up with the exceptions. + + The delegate given by `filter` is called for each class in the module, passing along the `Type` object representing the class as well as the given `filterCriteria`. If `filter` returns a particular class, that class will be included in the returned array. If `filter` returns `null`, all classes are returned and `filterCriteria` is ignored. + + `FindTypes` cannot be used to look up parameterized types such as arrays. + + + +## Examples + The following example demonstrates the `FindTypes` method. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Reflection.Module.FilterTypeName Example/CPP/class1.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/Module/FilterTypeName/class1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Reflection.Module.FilterTypeName Example/VB/class1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Reflection.Module.FilterTypeName Example/VB/class1.vb" id="Snippet1"::: + ]]> One or more classes in a module could not be loaded. @@ -593,25 +593,25 @@ Gets a string representing the fully qualified name and path to this module. The fully qualified module name. - . - - If the assembly for this module was loaded from a byte array then the `FullyQualifiedName` for the module will be: \. - + . + + If the assembly for this module was loaded from a byte array then the `FullyQualifiedName` for the module will be: \. + > [!NOTE] -> The case of module name is platform-dependent. - - - -## Examples - The following example displays the fully qualified name of the specified module. - +> The case of module name is platform-dependent. + + + +## Examples + The following example displays the fully qualified name of the specified module. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Reflection.Module.FullyQualifiedName/CPP/class1.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/Module/FullyQualifiedName/class1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Reflection.Module.FullyQualifiedName/VB/class1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Reflection.Module.FullyQualifiedName/VB/class1.vb" id="Snippet1"::: + ]]> The caller does not have the required permissions. @@ -668,22 +668,22 @@ System.Object[] - + This argument is ignored for objects of this type. Returns all custom attributes. An array of type containing all custom attributes. - @@ -729,8 +729,8 @@ System.Object[] - - + + The type of attribute to get. @@ -738,15 +738,15 @@ Gets custom attributes of the specified type. An array of type containing all custom attributes of the specified type. - @@ -795,11 +795,11 @@ Returns a list of objects for the current module, which can be used in the reflection-only context. A generic list of objects representing data about the attributes that have been applied to the current module. - and cannot be used in such cases, because they create instances of the attributes. Code in the reflection-only context cannot be executed. For more information and example code, see the class. - + and cannot be used in such cases, because they create instances of the attributes. Code in the reflection-only context cannot be executed. For more information and example code, see the class. + ]]> @@ -859,7 +859,7 @@ System.Reflection.FieldInfo - + The field name. @@ -920,8 +920,8 @@ System.Reflection.FieldInfo - - + + The field name. @@ -990,11 +990,11 @@ Returns the global fields defined on the module. An array of objects representing the global fields defined on the module; if there are no global fields, an empty array is returned. - method does not return fields in a particular order, such as alphabetical or declaration order. Your code must not depend on the order in which fields are returned, because that order can vary. - + method does not return fields in a particular order, such as alphabetical or declaration order. Your code must not depend on the order in which fields are returned, because that order can vary. + ]]> @@ -1048,18 +1048,18 @@ System.Reflection.FieldInfo[] - + A bitwise combination of values that limit the search. Returns the global fields defined on the module that match the specified binding flags. An array of type representing the global fields defined on the module that match the specified binding flags; if no global fields match the binding flags, an empty array is returned. - method does not return fields in a particular order, such as alphabetical or declaration order. Your code must not depend on the order in which fields are returned, because that order can vary. - + method does not return fields in a particular order, such as alphabetical or declaration order. Your code must not depend on the order in which fields are returned, because that order can vary. + ]]> @@ -1165,7 +1165,7 @@ System.Reflection.MethodInfo - + The method name. @@ -1222,8 +1222,8 @@ System.Reflection.MethodInfo - - + + The method name. @@ -1284,7 +1284,7 @@ System.Reflection.MethodInfo - + [System.Runtime.CompilerServices.Nullable(1)] @@ -1292,10 +1292,10 @@ - - - - + + + + [System.Runtime.CompilerServices.Nullable(1)] @@ -1303,7 +1303,7 @@ - + The method name. @@ -1371,7 +1371,7 @@ System.Reflection.MethodInfo - + [System.Runtime.CompilerServices.Nullable(1)] @@ -1379,10 +1379,10 @@ - - - - + + + + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 2, 1 })] @@ -1390,7 +1390,7 @@ - + The method name. @@ -1518,7 +1518,7 @@ System.Reflection.MethodInfo[] - + A bitwise combination of values that limit the search. @@ -1582,8 +1582,8 @@ System.Void - - + + The information and data needed to serialize or deserialize an object. @@ -1636,8 +1636,8 @@ System.Void - - + + When this method returns, a combination of the values indicating the nature of the code in the module. @@ -1747,31 +1747,31 @@ System.Type - + The name of the type to locate. The name must be fully qualified with the namespace. Returns the specified type, performing a case-sensitive search. A object representing the given type, if the type is in this module; otherwise, . - [!NOTE] -> If the type has been forwarded to another assembly, it is still returned by this method. For information on type forwarding, see [Type Forwarding in the Common Language Runtime](/dotnet/standard/assembly/type-forwarding). - - A type can be retrieved from a specific module using . Calling on the module that contains the manifest will not search the entire assembly. To retrieve a type from an assembly, regardless of which module it is in, you must call . - - - -## Examples - The following example displays the name of a type in the specified module. - +> If the type has been forwarded to another assembly, it is still returned by this method. For information on type forwarding, see [Type Forwarding in the Common Language Runtime](/dotnet/standard/assembly/type-forwarding). + + A type can be retrieved from a specific module using . Calling on the module that contains the manifest will not search the entire assembly. To retrieve a type from an assembly, regardless of which module it is in, you must call . + + + +## Examples + The following example displays the name of a type in the specified module. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Reflection.Module.GetType 1Arg Example/CPP/class1.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/Module/GetType/class1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Reflection.Module.GetType 1Arg Example/VB/class1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Reflection.Module.GetType 1Arg Example/VB/class1.vb" id="Snippet1"::: + ]]> @@ -1782,16 +1782,16 @@ requires a dependent assembly that could not be found. - requires a dependent assembly that was found but could not be loaded. - - -or- - + requires a dependent assembly that was found but could not be loaded. + + -or- + The current assembly was loaded into the reflection-only context, and requires a dependent assembly that was not preloaded. - requires a dependent assembly, but the file is not a valid assembly. - - -or- - + requires a dependent assembly, but the file is not a valid assembly. + + -or- + requires a dependent assembly which was compiled for a version of the runtime later than the currently loaded version. @@ -1849,8 +1849,8 @@ System.Type - - + + The name of the type to locate. The name must be fully qualified with the namespace. @@ -1859,24 +1859,24 @@ Returns the specified type, searching the module with the specified case sensitivity. A object representing the given type, if the type is in this module; otherwise, . - [!NOTE] -> If the type has been forwarded to another assembly, it is still returned by this method. For information on type forwarding, see [Type Forwarding in the Common Language Runtime](/dotnet/standard/assembly/type-forwarding). - - A type can be retrieved from a specific module using . Calling on the module that contains the manifest will not search the entire assembly. To retrieve a type from an assembly, regardless of which module it is in, you must call . - - - -## Examples - The following example displays the name of a type in the specified module, specifying `false` for the `ignoreCase` parameter so that case will not be ignored. - +> If the type has been forwarded to another assembly, it is still returned by this method. For information on type forwarding, see [Type Forwarding in the Common Language Runtime](/dotnet/standard/assembly/type-forwarding). + + A type can be retrieved from a specific module using . Calling on the module that contains the manifest will not search the entire assembly. To retrieve a type from an assembly, regardless of which module it is in, you must call . + + + +## Examples + The following example displays the name of a type in the specified module, specifying `false` for the `ignoreCase` parameter so that case will not be ignored. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Reflection.Module.GetType 2Arg Example/CPP/class1.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/Module/GetType/class11.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Reflection.Module.GetType 2Arg Example/VB/class1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Reflection.Module.GetType 2Arg Example/VB/class1.vb" id="Snippet1"::: + ]]> @@ -1887,16 +1887,16 @@ requires a dependent assembly that could not be found. - requires a dependent assembly that was found but could not be loaded. - - -or- - + requires a dependent assembly that was found but could not be loaded. + + -or- + The current assembly was loaded into the reflection-only context, and requires a dependent assembly that was not preloaded. - requires a dependent assembly, but the file is not a valid assembly. - - -or- - + requires a dependent assembly, but the file is not a valid assembly. + + -or- + requires a dependent assembly which was compiled for a version of the runtime later than the currently loaded version. @@ -1968,25 +1968,25 @@ Returns the specified type, specifying whether to make a case-sensitive search of the module and whether to throw an exception if the type cannot be found. A object representing the specified type, if the type is declared in this module; otherwise, . - can be thrown even if `throwOnError` is `false`. - + can be thrown even if `throwOnError` is `false`. + > [!NOTE] -> If the type has been forwarded to another assembly, it is still returned by this method. For information on type forwarding, see [Type Forwarding in the Common Language Runtime](/dotnet/standard/assembly/type-forwarding). - - A type can be retrieved from a specific module using . Calling on the module that contains the manifest will not search the entire assembly. To retrieve a type from an assembly, regardless of which module it is in, you must call . - - - -## Examples - The following example displays the name of a type in the specified module. The `throwOnError` and `ignoreCase` parameters are specified as `false`. - +> If the type has been forwarded to another assembly, it is still returned by this method. For information on type forwarding, see [Type Forwarding in the Common Language Runtime](/dotnet/standard/assembly/type-forwarding). + + A type can be retrieved from a specific module using . Calling on the module that contains the manifest will not search the entire assembly. To retrieve a type from an assembly, regardless of which module it is in, you must call . + + + +## Examples + The following example displays the name of a type in the specified module. The `throwOnError` and `ignoreCase` parameters are specified as `false`. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Reflection.Module.GetType 3Arg Example/CPP/class1.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/Module/GetType/class12.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Reflection.Module.GetType 3Arg Example/VB/class1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Reflection.Module.GetType 3Arg Example/VB/class1.vb" id="Snippet1"::: + ]]> @@ -1999,16 +1999,16 @@ requires a dependent assembly that could not be found. - requires a dependent assembly that was found but could not be loaded. - - -or- - + requires a dependent assembly that was found but could not be loaded. + + -or- + The current assembly was loaded into the reflection-only context, and requires a dependent assembly that was not preloaded. - requires a dependent assembly, but the file is not a valid assembly. - - -or- - + requires a dependent assembly, but the file is not a valid assembly. + + -or- + requires a dependent assembly which was compiled for a version of the runtime later than the currently loaded version.
@@ -2061,16 +2061,16 @@ Returns all the types defined within this module. An array of type containing types defined within the module that is reflected by this instance. - [!NOTE] -> If a type has been forwarded to another assembly, it is not included in the returned array. For information on type forwarding, see [Type Forwarding in the Common Language Runtime](/dotnet/standard/assembly/type-forwarding). - +> If a type has been forwarded to another assembly, it is not included in the returned array. For information on type forwarding, see [Type Forwarding in the Common Language Runtime](/dotnet/standard/assembly/type-forwarding). + ]]> One or more classes in a module could not be loaded. @@ -2119,8 +2119,8 @@ System.Boolean - - + + The type of custom attribute to test for. @@ -2129,15 +2129,15 @@ if one or more instances of have been applied to this module; otherwise, . - @@ -2194,15 +2194,15 @@ if the object is a resource; otherwise, . - @@ -2250,13 +2250,13 @@ Gets the metadata stream version. A 32-bit integer representing the metadata stream version. The high-order two bytes represent the major version number, and the low-order two bytes represent the minor version number. - [!NOTE] > For more information on the metadata header, see "Partition II: Metadata Definition and Semantics" in the [ECMA 335 Common Language Infrastructure (CLI) specification](https://www.ecma-international.org/publications-and-standards/standards/ecma-335/). - + ]]>
@@ -2304,14 +2304,14 @@ Gets a token that identifies the module in metadata. An integer token that identifies the current module in metadata. - [!NOTE] > Information about metadata tokens can be found in the Common Language Infrastructure (CLI) documentation, especially "Partition II: Metadata Definition and Semantics". For more information, see [ECMA 335 Common Language Infrastructure (CLI)](https://www.ecma-international.org/publications-and-standards/standards/ecma-335/). - + ]]> @@ -2402,14 +2402,14 @@ Gets a universally unique identifier (UUID) that can be used to distinguish between two versions of a module. A that can be used to distinguish between two versions of a module. - property is referred to as the `mvid`, and is stored in the GUID heap. - + property is referred to as the `mvid`, and is stored in the GUID heap. + > [!NOTE] > More information about metadata can be found in the Common Language Infrastructure (CLI) documentation, especially "Partition II: Metadata Definition and Semantics". For more information, see [ECMA 335 Common Language Infrastructure (CLI)](https://www.ecma-international.org/publications-and-standards/standards/ecma-335/). - + ]]> @@ -2467,24 +2467,24 @@ Gets a representing the name of the module with the path removed. The module name with no path. - . - - To get the name and the path, use . - - - -## Examples - This example shows the effect of the `ScopeName`, `FullyQualifiedName`, and `Name` properties. - + . + + To get the name and the path, use . + + + +## Examples + This example shows the effect of the `ScopeName`, `FullyQualifiedName`, and `Name` properties. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Module.Name Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/Module/Name/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Module.Name Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Module.Name Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -2532,8 +2532,8 @@ System.Boolean - - + + The first object to compare. @@ -2587,8 +2587,8 @@ System.Boolean - - + + The first object to compare. @@ -2657,30 +2657,30 @@ System.Reflection.FieldInfo - + A metadata token that identifies a field in the module. Returns the field identified by the specified metadata token. A object representing the field that is identified by the specified metadata token. - method overload, which allows you to supply the necessary context. That is, when you are resolving a metadata token for a field that depends on the generic type parameters of the generic type and/or the generic method in which the token is embedded, you must use the overload that allows you to supply those type parameters. - + method overload, which allows you to supply the necessary context. That is, when you are resolving a metadata token for a field that depends on the generic type parameters of the generic type and/or the generic method in which the token is embedded, you must use the overload that allows you to supply those type parameters. + > [!NOTE] > Information about metadata tokens can be found in the Common Language Infrastructure (CLI) documentation, especially "Partition II: Metadata Definition and Semantics". For more information, see [ECMA 335 Common Language Infrastructure (CLI)](https://www.ecma-international.org/publications-and-standards/standards/ecma-335/). - - For code that demonstrates token resolution using the generic context (that is, the generic type parameters of the generic type and/or the generic method in which the token is embedded) see the method. - + + For code that demonstrates token resolution using the generic context (that is, the generic type parameters of the generic type and/or the generic method in which the token is embedded) see the method. + ]]> - is not a token for a field in the scope of the current module. - - -or- - + is not a token for a field in the scope of the current module. + + -or- + identifies a field whose parent has a signature containing element type (a type parameter of a generic type) or (a type parameter of a generic method). is not a valid token in the scope of the current module. @@ -2739,8 +2739,8 @@ System.Reflection.FieldInfo - - + + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 2, 1 })] @@ -2748,7 +2748,7 @@ - + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 2, 1 })] @@ -2764,23 +2764,23 @@ Returns the field identified by the specified metadata token, in the context defined by the specified generic type parameters. A object representing the field that is identified by the specified metadata token. - method on the type where `metadataToken` is in scope to obtain an array of generic type arguments for `genericTypeArguments`. Use the method on the method where `metadataToken` is in scope to obtain an array of generic type arguments for `genericTypeArguments`. It is always safe to provide these arguments, even when they are not needed. - + method on the type where `metadataToken` is in scope to obtain an array of generic type arguments for `genericTypeArguments`. Use the method on the method where `metadataToken` is in scope to obtain an array of generic type arguments for `genericTypeArguments`. It is always safe to provide these arguments, even when they are not needed. + > [!NOTE] > Information about metadata tokens can be found in the Common Language Infrastructure (CLI) documentation, especially "Partition II: Metadata Definition and Semantics". For more information, see [ECMA 335 Common Language Infrastructure (CLI)](https://www.ecma-international.org/publications-and-standards/standards/ecma-335/). - - For code that demonstrates token resolution using the generic context (that is, the generic type parameters of the generic type and/or the generic method in which the token is embedded) see the method. - + + For code that demonstrates token resolution using the generic context (that is, the generic type parameters of the generic type and/or the generic method in which the token is embedded) see the method. + ]]> - is not a token for a field in the scope of the current module. - - -or- - + is not a token for a field in the scope of the current module. + + -or- + identifies a field whose parent has a signature containing element type (a type parameter of a generic type) or (a type parameter of a generic method), and the necessary generic type arguments were not supplied for either or both of and . is not a valid token in the scope of the current module. @@ -2844,34 +2844,34 @@ System.Reflection.MemberInfo - + A metadata token that identifies a type or member in the module. Returns the type or member identified by the specified metadata token. A object representing the type or member that is identified by the specified metadata token. - method overload, which allows you to supply the necessary context. That is, when you are resolving a metadata token for a member that depends on the generic type parameters of the generic type and/or the generic method in which the token is embedded, you must use the overload that allows you to supply those type parameters. - + method overload, which allows you to supply the necessary context. That is, when you are resolving a metadata token for a member that depends on the generic type parameters of the generic type and/or the generic method in which the token is embedded, you must use the overload that allows you to supply those type parameters. + > [!NOTE] > Information about metadata tokens can be found in the Common Language Infrastructure (CLI) documentation, especially "Partition II: Metadata Definition and Semantics". For more information, see [ECMA 335 Common Language Infrastructure (CLI)](https://www.ecma-international.org/publications-and-standards/standards/ecma-335/). - - For code that demonstrates token resolution using the generic context (that is, the generic type parameters of the generic type and/or the generic method in which the token is embedded) see the method. - + + For code that demonstrates token resolution using the generic context (that is, the generic type parameters of the generic type and/or the generic method in which the token is embedded) see the method. + ]]> - is not a token for a type or member in the scope of the current module. - - -or- - - is a or whose signature contains element type (a type parameter of a generic type) or (a type parameter of a generic method). - - -or- - + is not a token for a type or member in the scope of the current module. + + -or- + + is a or whose signature contains element type (a type parameter of a generic type) or (a type parameter of a generic method). + + -or- + identifies a property or event. is not a valid token in the scope of the current module. @@ -2930,8 +2930,8 @@ System.Reflection.MemberInfo - - + + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 2, 1 })] @@ -2939,7 +2939,7 @@ - + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 2, 1 })] @@ -2955,27 +2955,27 @@ Returns the type or member identified by the specified metadata token, in the context defined by the specified generic type parameters. A object representing the type or member that is identified by the specified metadata token. - method on the type where `metadataToken` is in scope to obtain an array of generic type arguments for `genericTypeArguments`. Use the method on the method where `metadataToken` is in scope to obtain an array of generic type arguments for `genericTypeArguments`. It is always safe to provide these arguments, even when they are not needed. - + method on the type where `metadataToken` is in scope to obtain an array of generic type arguments for `genericTypeArguments`. Use the method on the method where `metadataToken` is in scope to obtain an array of generic type arguments for `genericTypeArguments`. It is always safe to provide these arguments, even when they are not needed. + > [!NOTE] > Information about metadata tokens can be found in the Common Language Infrastructure (CLI) documentation, especially "Partition II: Metadata Definition and Semantics". For more information, see [ECMA 335 Common Language Infrastructure (CLI)](https://www.ecma-international.org/publications-and-standards/standards/ecma-335/). - - For code that demonstrates token resolution using the generic context (that is, the generic type parameters of the generic type and/or the generic method in which the token is embedded) see the method. - + + For code that demonstrates token resolution using the generic context (that is, the generic type parameters of the generic type and/or the generic method in which the token is embedded) see the method. + ]]> - is not a token for a type or member in the scope of the current module. - - -or- - - is a or whose signature contains element type (a type parameter of a generic type) or (a type parameter of a generic method), and the necessary generic type arguments were not supplied for either or both of and . - - -or- - + is not a token for a type or member in the scope of the current module. + + -or- + + is a or whose signature contains element type (a type parameter of a generic type) or (a type parameter of a generic method), and the necessary generic type arguments were not supplied for either or both of and . + + -or- + identifies a property or event. is not a valid token in the scope of the current module. @@ -3039,56 +3039,56 @@ System.Reflection.MethodBase - + A metadata token that identifies a method or constructor in the module. Returns the method or constructor identified by the specified metadata token. A object representing the method or constructor that is identified by the specified metadata token. - method overload, which allows you to supply the necessary context. That is, when you are resolving a metadata token for a method that depends on the generic type parameters of the generic type and/or the generic method in which the token is embedded, you must use the overload that allows you to supply those type parameters. - + method overload, which allows you to supply the necessary context. That is, when you are resolving a metadata token for a method that depends on the generic type parameters of the generic type and/or the generic method in which the token is embedded, you must use the overload that allows you to supply those type parameters. + > [!NOTE] > Information about metadata tokens can be found in the Common Language Infrastructure (CLI) documentation, especially "Partition II: Metadata Definition and Semantics". For more information, see [ECMA 335 Common Language Infrastructure (CLI)](https://www.ecma-international.org/publications-and-standards/standards/ecma-335/). - - - -## Examples - The following example shows how to use the two overloads of the method to resolve metadata tokens from call sites in generic and non-generic contexts. - - The code example defines two generic types, `G1` and `G2` (`G1(Of Tg1)` and `G2(Of Tg2)` in Visual Basic), each of which has a generic method. `G1` also has a non-generic method that uses the type parameter `Tg1` for its parameter. The generic method `GM2` in type `G2` contains several method calls: - -- Case 1: The generic method `GM1` is called, using the type parameters of `G2` and `GM2` as the type arguments. In other words, the parameter types of the called method will depend on the types that are used to construct a closed generic type from the type definition for `G2`. - -- Case 2: The non-generic method `M1` is called. The parameter of this method uses the type parameter of the defining type, `G1`, which is replaced in this case by the type parameter of the enclosing type, `G2`. - -- Case 3: The generic method `GM1` is called, specifying and for the type arguments of the generic type and the generic method, respectively. This method call does not depend on the type parameters of the enclosing type or method. - -- Case 4: The non-generic method `M1` of the `Example` class is called. This method call does not depend on the type parameters of the enclosing type or method. - - In addition, the example defines the non-generic `Example` class. This class has a method `M` that makes a call to a generic method: - -- Case 5: The generic method `GM1` is called, specifying and for the type arguments of the generic type and the generic method, respectively. The context for this method has no enclosing generic type or generic method. - - For each case, the example first constructs a that represents the called method, and then resolves the token using the method overload, using the and methods to get the values for the `genericTypeArguments` and `genericMethodArguments` parameters. This technique works in all cases, because the methods return for non-generic contexts. The example compares the resolved with the constructed . - - The example then attempts to use the method overload to resolve the token. This works in cases 3, 4, and 5, because the method calls do not depend on the generic context. In cases 1 and 2, an exception is thrown because there is insufficient information to resolve the token. - - The metadata token values are hard-coded as an enumeration. If you change this code example, the token values are likely to change. To determine the new token values, compile the code and use Ildasm.exe with the **/TOKENS** option to examine the assembly. The tokens can be found at the points of call. Insert the new values into the enumeration, and recompile the example. - + + + +## Examples + The following example shows how to use the two overloads of the method to resolve metadata tokens from call sites in generic and non-generic contexts. + + The code example defines two generic types, `G1` and `G2` (`G1(Of Tg1)` and `G2(Of Tg2)` in Visual Basic), each of which has a generic method. `G1` also has a non-generic method that uses the type parameter `Tg1` for its parameter. The generic method `GM2` in type `G2` contains several method calls: + +- Case 1: The generic method `GM1` is called, using the type parameters of `G2` and `GM2` as the type arguments. In other words, the parameter types of the called method will depend on the types that are used to construct a closed generic type from the type definition for `G2`. + +- Case 2: The non-generic method `M1` is called. The parameter of this method uses the type parameter of the defining type, `G1`, which is replaced in this case by the type parameter of the enclosing type, `G2`. + +- Case 3: The generic method `GM1` is called, specifying and for the type arguments of the generic type and the generic method, respectively. This method call does not depend on the type parameters of the enclosing type or method. + +- Case 4: The non-generic method `M1` of the `Example` class is called. This method call does not depend on the type parameters of the enclosing type or method. + + In addition, the example defines the non-generic `Example` class. This class has a method `M` that makes a call to a generic method: + +- Case 5: The generic method `GM1` is called, specifying and for the type arguments of the generic type and the generic method, respectively. The context for this method has no enclosing generic type or generic method. + + For each case, the example first constructs a that represents the called method, and then resolves the token using the method overload, using the and methods to get the values for the `genericTypeArguments` and `genericMethodArguments` parameters. This technique works in all cases, because the methods return for non-generic contexts. The example compares the resolved with the constructed . + + The example then attempts to use the method overload to resolve the token. This works in cases 3, 4, and 5, because the method calls do not depend on the generic context. In cases 1 and 2, an exception is thrown because there is insufficient information to resolve the token. + + The metadata token values are hard-coded as an enumeration. If you change this code example, the token values are likely to change. To determine the new token values, compile the code and use Ildasm.exe with the **/TOKENS** option to examine the assembly. The tokens can be found at the points of call. Insert the new values into the enumeration, and recompile the example. + :::code language="csharp" source="~/snippets/csharp/System.Reflection/Module/ResolveMethod/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Module.MethodResolve/vb/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Module.MethodResolve/vb/source.vb" id="Snippet1"::: + ]]> - is not a token for a method or constructor in the scope of the current module. - - -or- - + is not a token for a method or constructor in the scope of the current module. + + -or- + is a whose signature contains element type (a type parameter of a generic type) or (a type parameter of a generic method). is not a valid token in the scope of the current module. @@ -3147,8 +3147,8 @@ System.Reflection.MethodBase - - + + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 2, 1 })] @@ -3156,7 +3156,7 @@ - + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 2, 1 })] @@ -3172,49 +3172,49 @@ Returns the method or constructor identified by the specified metadata token, in the context defined by the specified generic type parameters. A object representing the method that is identified by the specified metadata token. - method on the type where `metadataToken` is in scope to obtain an array of generic type arguments for `genericTypeArguments`. Use the method on the method where `metadataToken` is in scope to obtain an array of generic type arguments for `genericMethodArguments`. It is always safe to provide these arguments, even when they are not needed. - + method on the type where `metadataToken` is in scope to obtain an array of generic type arguments for `genericTypeArguments`. Use the method on the method where `metadataToken` is in scope to obtain an array of generic type arguments for `genericMethodArguments`. It is always safe to provide these arguments, even when they are not needed. + > [!NOTE] > Information about metadata tokens can be found in the Common Language Infrastructure (CLI) documentation, especially "Partition II: Metadata Definition and Semantics". For more information, see [ECMA 335 Common Language Infrastructure (CLI)](https://www.ecma-international.org/publications-and-standards/standards/ecma-335/). - - - -## Examples - The following example shows how to use the two overloads of the method to resolve metadata tokens from call sites in generic and non-generic contexts. - - The code example defines two generic types, `G1` and `G2`, each of which has a generic method. `G1` also has a non-generic method that uses the type parameter `Tg1` for its parameter. The generic method `GM2` in type `G2` contains several method calls: - -- Case 1: The generic method `GM1` is called, using the type parameters of `G2` and `GM2` as the type arguments. In other words, the parameter types of the called method will depend on the types that are used to construct a closed generic type from the type definition for `G2`. - -- Case 2: The non-generic method `M1` is called. The parameter of this method uses the type parameter of the defining type, `G1`, which is replaced in this case by the type parameter of the enclosing type, `G2`. - -- Case 3: The generic method `GM1` is called, specifying and for the type arguments of the generic type and the generic method, respectively. This method call does not depend on the type parameters of the enclosing type or method. - -- Case 4: The non-generic method `M1` of the `Example` class is called. This method call does not depend on the type parameters of the enclosing type or method. - - In addition, the example defines the non-generic `Example` class. This class has a method `M` that makes a call to a generic method. - -- Case 5: The generic method `GM1` is called, specifying and for the type arguments of the generic type and the generic method, respectively. The context for this method has no enclosing generic type or generic method. - - For each case, the example first constructs a that represents the called method, and then resolves the token using the method overload, using the and methods to get the values for the `genericTypeArguments` and `genericMethodArguments` parameters. This technique works in all cases, because the methods return for non-generic contexts. The example compares the resolved with the constructed . - - The example then attempts to use the method overload to resolve the token. This works in cases 3, 4, and 5, because the method calls do not depend on the generic context. In cases 1 and 2, an exception is thrown because there is insufficient information to resolve the token. - - The metadata token values are hard-coded as an enumeration. If you change this code example, the token values are likely to change. To determine the new token values, compile the code and use Ildasm.exe with the **/TOKENS** option to examine the assembly. The tokens can be found at the points of call. Insert the new values into the enumeration, and recompile the example. - + + + +## Examples + The following example shows how to use the two overloads of the method to resolve metadata tokens from call sites in generic and non-generic contexts. + + The code example defines two generic types, `G1` and `G2`, each of which has a generic method. `G1` also has a non-generic method that uses the type parameter `Tg1` for its parameter. The generic method `GM2` in type `G2` contains several method calls: + +- Case 1: The generic method `GM1` is called, using the type parameters of `G2` and `GM2` as the type arguments. In other words, the parameter types of the called method will depend on the types that are used to construct a closed generic type from the type definition for `G2`. + +- Case 2: The non-generic method `M1` is called. The parameter of this method uses the type parameter of the defining type, `G1`, which is replaced in this case by the type parameter of the enclosing type, `G2`. + +- Case 3: The generic method `GM1` is called, specifying and for the type arguments of the generic type and the generic method, respectively. This method call does not depend on the type parameters of the enclosing type or method. + +- Case 4: The non-generic method `M1` of the `Example` class is called. This method call does not depend on the type parameters of the enclosing type or method. + + In addition, the example defines the non-generic `Example` class. This class has a method `M` that makes a call to a generic method. + +- Case 5: The generic method `GM1` is called, specifying and for the type arguments of the generic type and the generic method, respectively. The context for this method has no enclosing generic type or generic method. + + For each case, the example first constructs a that represents the called method, and then resolves the token using the method overload, using the and methods to get the values for the `genericTypeArguments` and `genericMethodArguments` parameters. This technique works in all cases, because the methods return for non-generic contexts. The example compares the resolved with the constructed . + + The example then attempts to use the method overload to resolve the token. This works in cases 3, 4, and 5, because the method calls do not depend on the generic context. In cases 1 and 2, an exception is thrown because there is insufficient information to resolve the token. + + The metadata token values are hard-coded as an enumeration. If you change this code example, the token values are likely to change. To determine the new token values, compile the code and use Ildasm.exe with the **/TOKENS** option to examine the assembly. The tokens can be found at the points of call. Insert the new values into the enumeration, and recompile the example. + :::code language="csharp" source="~/snippets/csharp/System.Reflection/Module/ResolveMethod/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Module.MethodResolve/vb/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Module.MethodResolve/vb/source.vb" id="Snippet1"::: + ]]> - is not a token for a method or constructor in the scope of the current module. - - -or- - + is not a token for a method or constructor in the scope of the current module. + + -or- + is a whose signature contains element type (a type parameter of a generic type) or (a type parameter of a generic method), and the necessary generic type arguments were not supplied for either or both of and . is not a valid token in the scope of the current module. @@ -3268,20 +3268,20 @@ System.Byte[] - + A metadata token that identifies a signature in the module. Returns the signature blob identified by a metadata token. An array of bytes representing the signature blob. - [!NOTE] > Information about metadata tokens and signatures can be found in the Common Language Infrastructure (CLI) documentation, especially "Partition II: Metadata Definition and Semantics". For more information, see [ECMA 335 Common Language Infrastructure (CLI)](https://www.ecma-international.org/publications-and-standards/standards/ecma-335/). - + ]]> @@ -3338,20 +3338,20 @@ System.String - + A metadata token that identifies a string in the string heap of the module. Returns the string identified by the specified metadata token. A containing a string value from the metadata string heap. - [!NOTE] > Information about metadata tokens can be found in the Common Language Infrastructure (CLI) documentation, especially "Partition II: Metadata Definition and Semantics". For more information, see [ECMA 335 Common Language Infrastructure (CLI)](https://www.ecma-international.org/publications-and-standards/standards/ecma-335/). - + ]]> @@ -3413,28 +3413,28 @@ System.Type - + A metadata token that identifies a type in the module. Returns the type identified by the specified metadata token. A object representing the type that is identified by the specified metadata token. - method overload, which allows you to supply the necessary context. That is, when you are resolving a metadata token for a type that depends on the generic type parameters of the generic type and/or the generic method in which the token is embedded, you must use the overload that allows you to supply those type parameters. - + method overload, which allows you to supply the necessary context. That is, when you are resolving a metadata token for a type that depends on the generic type parameters of the generic type and/or the generic method in which the token is embedded, you must use the overload that allows you to supply those type parameters. + > [!NOTE] > Information about metadata tokens can be found in the Common Language Infrastructure (CLI) documentation, especially "Partition II: Metadata Definition and Semantics". For more information, see [ECMA 335 Common Language Infrastructure (CLI)](https://www.ecma-international.org/publications-and-standards/standards/ecma-335/). - + ]]> - is not a token for a type in the scope of the current module. - - -or- - + is not a token for a type in the scope of the current module. + + -or- + is a whose signature contains element type (a type parameter of a generic type) or (a type parameter of a generic method). is not a valid token in the scope of the current module. @@ -3489,8 +3489,8 @@ System.Type - - + + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 2, 1 })] @@ -3498,7 +3498,7 @@ - + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 2, 1 })] @@ -3514,23 +3514,23 @@ Returns the type identified by the specified metadata token, in the context defined by the specified generic type parameters. A object representing the type that is identified by the specified metadata token. - method on the type where `metadataToken` is in scope to obtain an array of generic type arguments for `genericTypeArguments`. Use the method on the method where `metadataToken` is in scope to obtain an array of generic type arguments for `genericTypeArguments`. It is always safe to provide these arguments, even when they are not needed. - + method on the type where `metadataToken` is in scope to obtain an array of generic type arguments for `genericTypeArguments`. Use the method on the method where `metadataToken` is in scope to obtain an array of generic type arguments for `genericTypeArguments`. It is always safe to provide these arguments, even when they are not needed. + > [!NOTE] > Information about metadata tokens can be found in the Common Language Infrastructure (CLI) documentation, especially "Partition II: Metadata Definition and Semantics". For more information, see [ECMA 335 Common Language Infrastructure (CLI)](https://www.ecma-international.org/publications-and-standards/standards/ecma-335/). - - For code that demonstrates token resolution using the generic context (that is, the generic type parameters of the generic type and/or the generic method in which the token is embedded) see the method. - + + For code that demonstrates token resolution using the generic context (that is, the generic type parameters of the generic type and/or the generic method in which the token is embedded) see the method. + ]]> - is not a token for a type in the scope of the current module. - - -or- - + is not a token for a type in the scope of the current module. + + -or- + is a whose signature contains element type (a type parameter of a generic type) or (a type parameter of a generic method), and the necessary generic type arguments were not supplied for either or both of and . is not a valid token in the scope of the current module. @@ -3581,20 +3581,20 @@ Gets a string representing the name of the module. The module name. - @@ -3745,11 +3745,11 @@ System.Void - - - - - + + + + + Reserved for future use. Must be IID_NULL. @@ -3759,11 +3759,11 @@ Caller-allocated array that receives the IDs corresponding to the names. Maps a set of names to a corresponding set of dispatch identifiers. - Late-bound access using the COM IDispatch interface is not supported. @@ -3799,9 +3799,9 @@ System.Void - - - + + + The type information to return. @@ -3809,11 +3809,11 @@ Receives a pointer to the requested type information object. Retrieves the type information for an object, which can then be used to get the type information for an interface. - Late-bound access using the COM IDispatch interface is not supported. @@ -3849,17 +3849,17 @@ System.Void - + Points to a location that receives the number of type information interfaces provided by the object. Retrieves the number of type information interfaces that an object provides (either 0 or 1). - Late-bound access using the COM IDispatch interface is not supported. @@ -3895,14 +3895,14 @@ System.Void - - - - - - - - + + + + + + + + Identifies the member. @@ -3915,11 +3915,11 @@ The index of the first argument that has an error. Provides access to properties and methods exposed by an object. - Late-bound access using the COM IDispatch interface is not supported. @@ -3970,15 +3970,15 @@ Returns the name of the module. A representing the name of this module. - diff --git a/xml/System.Reflection/ParameterInfo.xml b/xml/System.Reflection/ParameterInfo.xml index 4a3fc1e17a2..7ebbc076d24 100644 --- a/xml/System.Reflection/ParameterInfo.xml +++ b/xml/System.Reflection/ParameterInfo.xml @@ -113,33 +113,33 @@ Discovers the attributes of a parameter and provides access to parameter metadata. - returns an array of `ParameterInfo` objects representing the parameters of a method, in order. - - - -## Examples - This example shows how to use various reflection classes to analyze the metadata contained in an assembly. - + returns an array of `ParameterInfo` objects representing the parameters of a method, in order. + + + +## Examples + This example shows how to use various reflection classes to analyze the metadata contained in an assembly. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Reflection/CPP/reflection.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/Assembly/GetReferencedAssemblies/Reflection.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Reflection/VB/Reflection.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Reflection/VB/Reflection.vb" id="Snippet1"::: + ]]> This type is thread safe. - - - - - + + + + + Constructor mscorlib @@ -217,22 +217,22 @@ Gets the attributes for this parameter. A object representing the attributes for this parameter. - method. - - To get the array, first get the method or the constructor and then call . - - - -## Examples - The following example defines a method with three parameters. It uses the property to get the attributes of the second parameter and display them at the console. - + method. + + To get the array, first get the method or the constructor and then call . + + + +## Examples + The following example defines a method with three parameters. It uses the property to get the attributes of the second parameter and display them at the console. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/ParameterInfo_Attributes1/CPP/parameterinfo_attributes1.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/ParameterInfo/Attributes/parameterinfo_attributes1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ParameterInfo_Attributes1/VB/parameterinfo_attributes1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ParameterInfo_Attributes1/VB/parameterinfo_attributes1.vb" id="Snippet1"::: + ]]> @@ -278,13 +278,13 @@ The attributes of the parameter. - . - + . + ]]> @@ -336,13 +336,13 @@ The of the parameter. - . - + . + ]]> @@ -446,17 +446,17 @@ Gets a value indicating the default value if the parameter has a default value. The default value of the parameter, or if the parameter has no default value. - property instead. - - The default value is used when an actual value is not specified in the method call. A parameter can have a default value that is `null`. This is distinct from the case where a default value is not defined. - - This method utilizes the method. - - To get the array, first get the method or the constructor and then call . - + property instead. + + The default value is used when an actual value is not specified in the method call. A parameter can have a default value that is `null`. This is distinct from the case where a default value is not defined. + + This method utilizes the method. + + To get the array, first get the method or the constructor and then call . + ]]> @@ -508,13 +508,13 @@ The default value of the parameter. - . - + . + ]]> @@ -570,29 +570,29 @@ System.Object[] - + This argument is ignored for objects of this type. Gets all the custom attributes defined on this parameter. An array that contains all the custom attributes applied to this parameter. - method. - - - -## Examples - The following example shows how custom attributes that have been applied to the parameters of methods can be retrieved at run time. The example defines a custom attribute named `MyAttribute` that can be applied to parameters. The example then defines a class named `MyClass` with a method named `MyMethod`, and applies `MyAttribute` to a parameter of the method. - - When the example is run, it uses the method to retrieve the custom attributes that have been applied to all parameters of all methods in `MyClass`, and displays them at the console. - + method. + + + +## Examples + The following example shows how custom attributes that have been applied to the parameters of methods can be retrieved at run time. The example defines a custom attribute named `MyAttribute` that can be applied to parameters. The example then defines a class named `MyClass` with a method named `MyMethod`, and applies `MyAttribute` to a parameter of the method. + + When the example is run, it uses the method to retrieve the custom attributes that have been applied to all parameters of all methods in `MyClass`, and displays them at the console. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/ParameterInfo_GetCustomAttributes/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/ParameterInfo/GetCustomAttributes/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ParameterInfo_GetCustomAttributes/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ParameterInfo_GetCustomAttributes/VB/source.vb" id="Snippet1"::: + ]]> A custom attribute type could not be loaded. @@ -639,8 +639,8 @@ System.Object[] - - + + The custom attributes identified by type. @@ -648,11 +648,11 @@ Gets the custom attributes of the specified type or its derived types that are applied to this parameter. An array that contains the custom attributes of the specified type or its derived types. - method. - + method. + ]]> The type must be a type provided by the underlying runtime system. @@ -701,11 +701,11 @@ Returns a list of objects for the current parameter, which can be used in the reflection-only context. A generic list of objects representing data about the attributes that have been applied to the current parameter. - and cannot be used in such cases, because they create instances of the attributes. Code in the reflection-only context cannot be executed. For more information and example code, see the class. - + and cannot be used in such cases, because they create instances of the attributes. Code in the reflection-only context cannot be executed. For more information and example code, see the class. + ]]> @@ -740,15 +740,15 @@ Gets the modified type of this parameter object. A modified type. - , and which are used to obtain custom modifiers from a function pointer. To obtain the normal, unmodified type from a modified type, use . - This method is provided for designers of managed compilers. For more information on custom modifiers, see classes in the namespace. Also see the metadata specification in Partition II of the [Common Language Infrastructure (CLI) documentation](https://www.ecma-international.org/publications-and-standards/standards/ecma-335/). - + This method is provided for designers of managed compilers. For more information on custom modifiers, see classes in the namespace. Also see the metadata specification in Partition II of the [Common Language Infrastructure (CLI) documentation](https://www.ecma-international.org/publications-and-standards/standards/ecma-335/). + ]]> @@ -799,11 +799,11 @@ Gets the optional custom modifiers of the parameter. An array of objects that identify the optional custom modifiers of the current parameter, such as or . - and methods are provided for designers of managed compilers. For more information on custom modifiers, see and related classes in the namespace, and the metadata specification in the ECMA Partition II documentation. For more information, see [ECMA 335 Common Language Infrastructure (CLI)](https://www.ecma-international.org/publications-and-standards/standards/ecma-335/). - + ]]> @@ -861,18 +861,18 @@ System.Object - + The serialized stream from which the current object is deserialized. Returns the real object that should be deserialized instead of the object that the serialized stream specifies. The actual object that is put into the graph. - method. - + method. + ]]> The parameter's position in the parameter list of its associated member is not valid for that member's type. @@ -920,11 +920,11 @@ Gets the required custom modifiers of the parameter. An array of objects that identify the required custom modifiers of the current parameter, such as or . - and methods are provided for designers of managed compilers. For more information on custom modifiers, see and related classes in the namespace, and the metadata specification in Partition II of [ECMA 335 Common Language Infrastructure (CLI)](https://www.ecma-international.org/publications-and-standards/standards/ecma-335/). - + ]]> @@ -1015,8 +1015,8 @@ System.Boolean - - + + The object to search for. @@ -1025,22 +1025,22 @@ if one or more instances of or its derived types are applied to this parameter; otherwise, . - method. - - - -## Examples - The following example defines two custom attributes, `MyAttribute` and `MyDerivedAttribute`. `MyDerivedAttribute` is derived from `MyAttribute`. The example then applies these attributes to the parameters of a method of an example class. - - When the example is run, it uses the method to test all parameters of all methods in the example class. It then displays the parameters that have `MyAttribute` or `MyDerivedAttribute`. - + method. + + + +## Examples + The following example defines two custom attributes, `MyAttribute` and `MyDerivedAttribute`. `MyDerivedAttribute` is derived from `MyAttribute`. The example then applies these attributes to the parameters of a method of an example class. + + When the example is run, it uses the method to test all parameters of all methods in the example class. It then displays the parameters that have `MyAttribute` or `MyDerivedAttribute`. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/ParameterInfo_GetCustomAttribute_IsDefined/CPP/ParameterInfo_GetCustomAttribute_IsDefined.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/ParameterInfo/IsDefined/parameterinfo_getcustomattribute_isdefined.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ParameterInfo_GetCustomAttribute_IsDefined/VB/parameterinfo_getcustomattribute_isdefined.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ParameterInfo_GetCustomAttribute_IsDefined/VB/parameterinfo_getcustomattribute_isdefined.vb" id="Snippet1"::: + ]]> @@ -1094,34 +1094,34 @@ if the parameter is an input parameter; otherwise, . - array, first get the method or the constructor and then call . - - - -## Examples - The following example shows how to test method parameters for the , , and attributes. - - The example contains a `DefineMethod` method that does the following: - -- Creates a dynamic assembly containing a `MyType` type. - -- Adds a `MyMethod` method to `MyType`. `MyMethod` has three parameters. The first parameter is defined with , the second with , and the third with . - -- Calls to complete the type. - - After executing `DefineMethod`, the example searches the assemblies that are currently loaded until it finds the dynamic assembly. It loads `MyType` from the assembly, gets a object for the `MyMethod` method, and examines the parameters. The example uses the , , and properties to display information about the parameters. - + array, first get the method or the constructor and then call . + + + +## Examples + The following example shows how to test method parameters for the , , and attributes. + + The example contains a `DefineMethod` method that does the following: + +- Creates a dynamic assembly containing a `MyType` type. + +- Adds a `MyMethod` method to `MyType`. `MyMethod` has three parameters. The first parameter is defined with , the second with , and the third with . + +- Calls to complete the type. + + After executing `DefineMethod`, the example searches the assemblies that are currently loaded until it finds the dynamic assembly. It loads `MyType` from the assembly, gets a object for the `MyMethod` method, and examines the parameters. The example uses the , , and properties to display information about the parameters. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/ParameterInfo_IsIn_IsOut_IsOptional/CPP/ParameterInfo_IsIn_IsOut_IsOptional.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/ParameterInfo/IsIn/parameterinfo_isin_isout_isoptional.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ParameterInfo_IsIn_IsOut_IsOptional/VB/parameterinfo_isin_isout_isoptional.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ParameterInfo_IsIn_IsOut_IsOptional/VB/parameterinfo_isin_isout_isoptional.vb" id="Snippet1"::: + ]]> @@ -1168,15 +1168,15 @@ if the parameter is a locale identifier; otherwise, . - array, first get the method or the constructor and then call . - + array, first get the method or the constructor and then call . + ]]> @@ -1226,34 +1226,34 @@ if the parameter is optional; otherwise, . - array, first get the method and then call . - - - -## Examples - The following example shows how to test method parameters for the , , and attributes. - - The example contains a `DefineMethod` method that does the following: - -- Creates a dynamic assembly containing a `MyType` type. - -- Adds a `MyMethod` method to `MyType`. `MyMethod` has three parameters. The first parameter is defined with , the second with , and the third with . - -- Calls to complete the type. - - After executing `DefineMethod`, the example searches the assemblies that are currently loaded until it finds the dynamic assembly. It loads `MyType` from the assembly, gets a object for the `MyMethod` method, and examines the parameters. The example uses the , , and properties to display information about the parameters. - + array, first get the method and then call . + + + +## Examples + The following example shows how to test method parameters for the , , and attributes. + + The example contains a `DefineMethod` method that does the following: + +- Creates a dynamic assembly containing a `MyType` type. + +- Adds a `MyMethod` method to `MyType`. `MyMethod` has three parameters. The first parameter is defined with , the second with , and the third with . + +- Calls to complete the type. + + After executing `DefineMethod`, the example searches the assemblies that are currently loaded until it finds the dynamic assembly. It loads `MyType` from the assembly, gets a object for the `MyMethod` method, and examines the parameters. The example uses the , , and properties to display information about the parameters. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/ParameterInfo_IsIn_IsOut_IsOptional/CPP/ParameterInfo_IsIn_IsOut_IsOptional.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/ParameterInfo/IsIn/parameterinfo_isin_isout_isoptional.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ParameterInfo_IsIn_IsOut_IsOptional/VB/parameterinfo_isin_isout_isoptional.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ParameterInfo_IsIn_IsOut_IsOptional/VB/parameterinfo_isin_isout_isoptional.vb" id="Snippet1"::: + ]]> @@ -1303,34 +1303,34 @@ if the parameter is an output parameter; otherwise, . - array, first get the method or the constructor and then call . - - - -## Examples - The following example shows how to test method parameters for the , , and attributes. - - The example contains a `DefineMethod` method that does the following: - -- Creates a dynamic assembly containing a `MyType` type. - -- Adds a `MyMethod` method to `MyType`. `MyMethod` has three parameters. The first parameter is defined with , the second with , and the third with . - -- Calls to complete the type. - - After executing `DefineMethod`, the example searches the assemblies that are currently loaded until it finds the dynamic assembly. It loads `MyType` from the assembly, gets a object for the `MyMethod` method, and examines the parameters. The example uses the , , and properties to display information about the parameters. - + array, first get the method or the constructor and then call . + + + +## Examples + The following example shows how to test method parameters for the , , and attributes. + + The example contains a `DefineMethod` method that does the following: + +- Creates a dynamic assembly containing a `MyType` type. + +- Adds a `MyMethod` method to `MyType`. `MyMethod` has three parameters. The first parameter is defined with , the second with , and the third with . + +- Calls to complete the type. + + After executing `DefineMethod`, the example searches the assemblies that are currently loaded until it finds the dynamic assembly. It loads `MyType` from the assembly, gets a object for the `MyMethod` method, and examines the parameters. The example uses the , , and properties to display information about the parameters. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic ParameterInfo.IsOut Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/ParameterInfo/IsOut/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic ParameterInfo.IsOut Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic ParameterInfo.IsOut Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -1380,15 +1380,15 @@ if the parameter is a ; otherwise, . - array, first get the method or the constructor and then call . - + array, first get the method or the constructor and then call . + ]]> @@ -1479,13 +1479,13 @@ The member in which the field is implemented. - . - + . + ]]> @@ -1533,13 +1533,13 @@ Gets a value that identifies this parameter in metadata. A value which, in combination with the module, uniquely identifies this parameter in metadata. - property of the member that defines this parameter. - - The tokens obtained using this property can be passed to the unmanaged Reflection API. For more information, please see [Unmanaged Reflection API](https://msdn.microsoft.com/library/0c5bb9de-0cf6-438d-ba47-134e6c775fb8). - + property of the member that defines this parameter. + + The tokens obtained using this property can be passed to the unmanaged Reflection API. For more information, please see [Unmanaged Reflection API](https://msdn.microsoft.com/library/0c5bb9de-0cf6-438d-ba47-134e6c775fb8). + ]]> @@ -1599,25 +1599,25 @@ Gets the name of the parameter. The simple name of this parameter. - field, and depends on an optional metadata flag that might not be available in all compilers. - - To get the array, first get the method or the constructor and then call the method. - + field, and depends on an optional metadata flag that might not be available in all compilers. + + To get the array, first get the method or the constructor and then call the method. + > [!WARNING] -> If this represents a return value (that is, if it was obtained by using the property), this property will be `null`. - - - -## Examples - The following example shows how to get objects for the parameters of a method, and then use the property to obtain the parameter names. - +> If this represents a return value (that is, if it was obtained by using the property), this property will be `null`. + + + +## Examples + The following example shows how to get objects for the parameters of a method, and then use the property to obtain the parameter names. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic ParameterInfo.Name Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/ParameterInfo/Name/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic ParameterInfo.Name Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic ParameterInfo.Name Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -1669,13 +1669,13 @@ The name of the parameter. - . - + . + ]]> @@ -1724,22 +1724,22 @@ Gets the of this parameter. The object that represents the of this parameter. - array, first get the method or the constructor and then call . - - - -## Examples - The following example shows how to get objects for the parameters of a method, and then use the property to display the type of each parameter. - + array, first get the method or the constructor and then call . + + + +## Examples + The following example shows how to get objects for the parameters of a method, and then use the property to display the type of each parameter. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic ParameterInfo.ParameterType Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/ParameterInfo/ParameterType/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic ParameterInfo.ParameterType Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic ParameterInfo.ParameterType Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -1788,15 +1788,15 @@ Gets the zero-based position of the parameter in the formal parameter list. An integer representing the position this parameter occupies in the parameter list. - method. - - To get the array, first get the method or the constructor and then call . - + method. + + To get the array, first get the method or the constructor and then call . + ]]> @@ -1842,13 +1842,13 @@ The zero-based position of the parameter in the parameter list. - . - + . + ]]> @@ -1905,15 +1905,15 @@ Gets a value indicating the default value if the parameter has a default value. The default value of the parameter, or if the parameter has no default value. - array, first get the method or the constructor and then call the method. - + array, first get the method or the constructor and then call the method. + ]]> @@ -2064,11 +2064,11 @@ System.Void - - - - - + + + + + Reserved for future use. Must be IID_NULL. @@ -2078,11 +2078,11 @@ Caller-allocated array which receives the IDs corresponding to the names. Maps a set of names to a corresponding set of dispatch identifiers. - Late-bound access using the COM IDispatch interface is not supported. @@ -2118,9 +2118,9 @@ System.Void - - - + + + The type information to return. @@ -2128,11 +2128,11 @@ Receives a pointer to the requested type information object. Retrieves the type information for an object, which can then be used to get the type information for an interface. - Late-bound access using the COM IDispatch interface is not supported. @@ -2168,17 +2168,17 @@ System.Void - + Points to a location that receives the number of type information interfaces provided by the object. Retrieves the number of type information interfaces that an object provides (either 0 or 1). - Late-bound access using the COM IDispatch interface is not supported. @@ -2214,14 +2214,14 @@ System.Void - - - - - - - - + + + + + + + + Identifies the member. @@ -2234,11 +2234,11 @@ The index of the first argument that has an error. Provides access to properties and methods exposed by an object. - Late-bound access using the COM IDispatch interface is not supported. diff --git a/xml/System.Reflection/PropertyInfo.xml b/xml/System.Reflection/PropertyInfo.xml index 2120526896e..0d575284468 100644 --- a/xml/System.Reflection/PropertyInfo.xml +++ b/xml/System.Reflection/PropertyInfo.xml @@ -92,36 +92,36 @@ Discovers the attributes of a property and provides access to property metadata. - [!NOTE] -> To determine whether a property is `static`, you must obtain the for the `get` or `set` accessor, by calling the or the method, and examine its property. - - Several methods in this class assume that the `get` accessor and `set` accessor methods of a property have certain formats. The signatures of the `get` and `set` methods must match the following convention: - -- The return type of the `get` method and the last argument of the `set` method must be identical. This is the type of the property. - -- The `get` and `set` methods must have the same number, type, and order of indices. - - If this format is not followed, the behavior of the `GetValue` and `SetValue` methods is undefined. - - Calling on `PropertyInfo` when the `inherit` parameter of `GetCustomAttributes` is `true` does not walk the type hierarchy. Use to inherit custom attributes. - - - -## Examples - This example shows how to use various reflection classes to analyze the metadata contained in an assembly. - +> To determine whether a property is `static`, you must obtain the for the `get` or `set` accessor, by calling the or the method, and examine its property. + + Several methods in this class assume that the `get` accessor and `set` accessor methods of a property have certain formats. The signatures of the `get` and `set` methods must match the following convention: + +- The return type of the `get` method and the last argument of the `set` method must be identical. This is the type of the property. + +- The `get` and `set` methods must have the same number, type, and order of indices. + + If this format is not followed, the behavior of the `GetValue` and `SetValue` methods is undefined. + + Calling on `PropertyInfo` when the `inherit` parameter of `GetCustomAttributes` is `true` does not walk the type hierarchy. Use to inherit custom attributes. + + + +## Examples + This example shows how to use various reflection classes to analyze the metadata contained in an assembly. + > [!NOTE] -> This example generates about 55,000 lines of data, which you can redirect to a text file at the command prompt, as follows: **example.exe > propertyinfo.txt** - +> This example generates about 55,000 lines of data, which you can redirect to a text file at the command prompt, as follows: **example.exe > propertyinfo.txt** + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Reflection/CPP/reflection.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/Assembly/GetReferencedAssemblies/Reflection.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Reflection/VB/Reflection.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Reflection/VB/Reflection.vb" id="Snippet1"::: + ]]> This type is thread safe. @@ -131,11 +131,11 @@ - - - - - + + + + + Constructor mscorlib @@ -216,24 +216,24 @@ Gets the attributes for this property. The attributes of this property. - property returns the attributes associated with the property represented by this object. The attributes are primarily modifiers applied by a compiler when creating a property; they indicate whether a property is the default property, a `SpecialName` property, and so on. Note that, for almost all properties found in types in the .NET Framework class library, the value of the property is . - + property returns the attributes associated with the property represented by this object. The attributes are primarily modifiers applied by a compiler when creating a property; they indicate whether a property is the default property, a `SpecialName` property, and so on. Note that, for almost all properties found in types in the .NET Framework class library, the value of the property is . + > [!TIP] -> In most cases, you probably want to retrieve the custom attributes associated with a property. To do this, retrieve the value of the property, or call one of the overloads of the method. - - To get the property: - -1. Get a object that represents the type to which the property belongs. - -2. Get the object by calling an overload of the method. - -3. Retrieve the property's attributes from the property. - - You can define the attributes of a property for a type created dynamically using reflection emit by calling an overload of the method and supplying a value for the `attributes` argument. - +> In most cases, you probably want to retrieve the custom attributes associated with a property. To do this, retrieve the value of the property, or call one of the overloads of the method. + + To get the property: + +1. Get a object that represents the type to which the property belongs. + +2. Get the object by calling an overload of the method. + +3. Retrieve the property's attributes from the property. + + You can define the attributes of a property for a type created dynamically using reflection emit by calling an overload of the method and supplying a value for the `attributes` argument. + ]]> @@ -288,22 +288,22 @@ if this property can be read; otherwise, . - @@ -356,28 +356,28 @@ if this property can be written to; otherwise, . - returns `true` if the property has a `set` accessor, even if the accessor is `private`, `internal` (or `Friend` in Visual Basic), or `protected`. If the property does not have a `set` accessor, the method returns `false`. - - To get the value of the property: - -1. Get the object of the type that includes the property. - -2. Call the to get the object that represents the property. - -3. Retrieve the value of the property. - - - -## Examples - The following example defines two properties. The first property is writable and the `CanWrite` property is `true`. The second property is not writable (there is no `set` accessor), and the `CanWrite` property is `false`. - + returns `true` if the property has a `set` accessor, even if the accessor is `private`, `internal` (or `Friend` in Visual Basic), or `protected`. If the property does not have a `set` accessor, the method returns `false`. + + To get the value of the property: + +1. Get the object of the type that includes the property. + +2. Call the to get the object that represents the property. + +3. Retrieve the value of the property. + + + +## Examples + The following example defines two properties. The first property is writable and the `CanWrite` property is `true`. The second property is not writable (there is no `set` accessor), and the `CanWrite` property is `false`. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic PropertyInfo.CanWrite Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/PropertyInfo/CanWrite/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic PropertyInfo.CanWrite Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic PropertyInfo.CanWrite Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -499,25 +499,25 @@ Returns an array whose elements reflect the public and accessors of the property reflected by the current instance. An array of objects that reflect the public and accessors of the property reflected by the current instance, if found; otherwise, this method returns an array with zero (0) elements. - method: - -1. Get a object that represents the class. - -2. From the object, get the object. - -3. From the object, call the method. - - - -## Examples - The following example retrieves the public accessors of the `ClassWithProperty.Caption` property and displays information about them. It also calls the method of the setter to set the property value and of the getter to retrieve the property value. - + method: + +1. Get a object that represents the class. + +2. From the object, get the object. + +3. From the object, call the method. + + + +## Examples + The following example retrieves the public accessors of the `ClassWithProperty.Caption` property and displays information about them. It also calls the method of the setter to set the property value and of the getter to retrieve the property value. + :::code language="csharp" source="~/snippets/csharp/System.Reflection/PropertyInfo/GetAccessors/source1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.reflection.propertyinfo.getaccessors/vb/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.reflection.propertyinfo.getaccessors/vb/source.vb" id="Snippet1"::: + ]]> @@ -570,32 +570,32 @@ System.Reflection.MethodInfo[] - + Indicates whether non-public methods should be returned in the returned array. if non-public methods are to be included; otherwise, . Returns an array whose elements reflect the public and, if specified, non-public and accessors of the property reflected by the current instance. An array whose elements reflect the and accessors of the property reflected by the current instance. If is , this array contains public and non-public and accessors. If is , this array contains only public and accessors. If no accessors with the specified visibility are found, this method returns an array with zero (0) elements. - method: - -1. Get a object that represents the class. - -2. From the object, get the object. - -3. From the object, call the method. - - - -## Examples - The following example retrieves the accessors of the `ClassWithProperty.Caption` property and displays information about them. It also calls the method of the setter to set the property value and of the getter to retrieve the property value. - + method: + +1. Get a object that represents the class. + +2. From the object, get the object. + +3. From the object, call the method. + + + +## Examples + The following example retrieves the accessors of the `ClassWithProperty.Caption` property and displays information about them. It also calls the method of the setter to set the property value and of the getter to retrieve the property value. + :::code language="csharp" source="~/snippets/csharp/System.Reflection/PropertyInfo/GetAccessors/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic PropertyInfo.GetAccessors1 Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic PropertyInfo.GetAccessors1 Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -645,19 +645,19 @@ Returns a literal value associated with the property by a compiler. An that contains the literal value associated with the property. If the literal value is a class type with an element value of zero, the return value is . - [!NOTE] -> Do not use this method in the reflection-only context, because it might cause code to execute. Use the method instead. - - In unmanaged metadata, the Constant table is used to store constant values for fields, parameters, and properties. Constant information does not directly influence runtime behavior. Compilers inspect this information, at compile time, when importing metadata. If used, the value of a constant is embedded in the Microsoft intermediate language (MSIL) stream the compiler emits. There are no MSIL instructions that can be used to access the Constant table at run time. - +> Do not use this method in the reflection-only context, because it might cause code to execute. Use the method instead. + + In unmanaged metadata, the Constant table is used to store constant values for fields, parameters, and properties. Constant information does not directly influence runtime behavior. Compilers inspect this information, at compile time, when importing metadata. If used, the value of a constant is embedded in the Microsoft intermediate language (MSIL) stream the compiler emits. There are no MSIL instructions that can be used to access the Constant table at run time. + > [!NOTE] > For more information on constant values and the Constant table, see Partition II of the [Common Language Infrastructure (CLI) specification](https://www.ecma-international.org/publications-and-standards/standards/ecma-335/). - + ]]> The Constant table in unmanaged metadata does not contain a constant value for the current property. @@ -723,13 +723,13 @@ Returns the public accessor for this property. A object representing the public accessor for this property, or if the accessor is non-public or does not exist. - . From the , use the `GetGetMethod` method. - + . From the , use the `GetGetMethod` method. + ]]> @@ -777,29 +777,29 @@ System.Reflection.MethodInfo - + Indicates whether a non-public accessor should be returned. if a non-public accessor is to be returned; otherwise, . When overridden in a derived class, returns the public or non-public accessor for this property. A object representing the accessor for this property, if is . Returns if is and the accessor is non-public, or if is but no accessors exist. - representing the get accessor. - - To use the `GetGetMethod` method, first get the class `Type`. From the `Type`, get the . From the , use the `GetGetMethod` method. - - - -## Examples - The following example displays the public or non-public `get` accessor for the specified property. - + representing the get accessor. + + To use the `GetGetMethod` method, first get the class `Type`. From the `Type`, get the . From the , use the `GetGetMethod` method. + + + +## Examples + The following example displays the public or non-public `get` accessor for the specified property. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic PropertyInfo.GetGetMethod1 Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/PropertyInfo/GetGetMethod/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic PropertyInfo.GetGetMethod1 Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic PropertyInfo.GetGetMethod1 Example/VB/source.vb" id="Snippet1"::: + ]]> The requested method is non-public and the caller does not have to reflect on this non-public method. @@ -907,22 +907,22 @@ When overridden in a derived class, returns an array of all the index parameters for the property. An array of type containing the parameters for the indexes. If the property is not indexed, the array has 0 (zero) elements. - @@ -1008,15 +1008,15 @@ Gets the modified type of this property object. A modified type. - , and which are used to obtain custom modifiers from a function pointer. To obtain the normal, unmodified type from a modified type, use . - - This method is provided for designers of managed compilers. For more information on custom modifiers, see classes in the namespace. Also see the metadata specification in Partition II of the [Common Language Infrastructure (CLI) documentation](https://www.ecma-international.org/publications-and-standards/standards/ecma-335/). - + + This method is provided for designers of managed compilers. For more information on custom modifiers, see classes in the namespace. Also see the metadata specification in Partition II of the [Common Language Infrastructure (CLI) documentation](https://www.ecma-international.org/publications-and-standards/standards/ecma-335/). + ]]> @@ -1073,11 +1073,11 @@ Returns an array of types representing the optional custom modifiers of the property. An array of objects that identify the optional custom modifiers of the current property, such as or . - and methods are provided for designers of managed compilers. For more information on custom modifiers, see and related classes in the namespace. Also see the metadata specification in Partition II of the [Common Language Infrastructure (CLI) specification](https://www.ecma-international.org/publications-and-standards/standards/ecma-335/). - + ]]> @@ -1125,18 +1125,18 @@ Returns a literal value associated with the property by a compiler. An that contains the literal value associated with the property. If the literal value is a class type with an element value of zero, the return value is . - [!NOTE] > For more information on constant values and the Constant table, , see Partition II of the [Common Language Infrastructure (CLI) specification](https://www.ecma-international.org/publications-and-standards/standards/ecma-335/). - + ]]> The Constant table in unmanaged metadata does not contain a constant value for the current property. @@ -1191,11 +1191,11 @@ Returns an array of types representing the required custom modifiers of the property. An array of objects that identify the required custom modifiers of the current property, such as or . - and methods are provided for designers of managed compilers. For more information on custom modifiers, see and related classes in the namespace. Also see the metadata specification in Partition II of the [Common Language Infrastructure (CLI) specification](https://www.ecma-international.org/publications-and-standards/standards/ecma-335/). - + ]]> @@ -1259,13 +1259,13 @@ Returns the public accessor for this property. The object representing the method for this property if the accessor is public, or if the accessor is not public. - . From the `PropertyInfo`, use the `GetSetMethod` method. - + . From the `PropertyInfo`, use the `GetSetMethod` method. + ]]> @@ -1313,39 +1313,39 @@ System.Reflection.MethodInfo - + Indicates whether the accessor should be returned if it is non-public. if a non-public accessor is to be returned; otherwise, . When overridden in a derived class, returns the accessor for this property. - This property's method, or , as shown in the following table. - - Value - - Condition - - The method for this property. - - The accessor is public, OR is and the accessor is non-public. - - is , but the property is read-only, OR is and the accessor is non-public, OR there is no accessor. - + This property's method, or , as shown in the following table. + + Value + + Condition + + The method for this property. + + The accessor is public, OR is and the accessor is non-public. + + is , but the property is read-only, OR is and the accessor is non-public, OR there is no accessor. + - . From the `PropertyInfo`, use the `GetSetMethod` method. - - - -## Examples - The following example displays the `set` accessor for the specified property. - + . From the `PropertyInfo`, use the `GetSetMethod` method. + + + +## Examples + The following example displays the `set` accessor for the specified property. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic PropertyInfo.GetSetMethod1 Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/PropertyInfo/GetSetMethod/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic PropertyInfo.GetSetMethod1 Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic PropertyInfo.GetSetMethod1 Example/VB/source.vb" id="Snippet1"::: + ]]> The requested method is non-public and the caller does not have to reflect on this non-public method. @@ -1449,21 +1449,21 @@ Returns the property value of a specified object. The property value of the specified object. - overload to retrieve the value of a non-indexed property; if you try to retrieve the value of an indexed property, the method throws a exception. You can determine whether a property is indexed or not by calling the method. If the length of the returned array is zero, the property is not indexed. - - This is a convenience method that provides an implementation for the abstract method with the parameter set to , the set to `null`, the object array of index values set to `null`, and the set to `null`. - - - -## Examples - The following example defines a `Planet` class that has two properties: `Name`, the name of the planet; and `Distance`, the planet's distance from Earth. The example instantiates a `Planet` object that represents the planet Jupiter and passes it to a `GetPropertyValues` method that displays information about the properties and uses the method to get the value of each `Planet` property. - + overload to retrieve the value of a non-indexed property; if you try to retrieve the value of an indexed property, the method throws a exception. You can determine whether a property is indexed or not by calling the method. If the length of the returned array is zero, the property is not indexed. + + This is a convenience method that provides an implementation for the abstract method with the parameter set to , the set to `null`, the object array of index values set to `null`, and the set to `null`. + + + +## Examples + The following example defines a `Planet` class that has two properties: `Name`, the name of the planet; and `Distance`, the planet's distance from Earth. The example instantiates a `Planet` object that represents the planet Jupiter and passes it to a `GetPropertyValues` method that displays information about the properties and uses the method to get the value of each `Planet` property. + :::code language="csharp" source="~/snippets/csharp/System.Reflection/PropertyInfo/GetValue/getvalue1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.reflection.propertyinfo.getvalue/vb/getvalue1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.reflection.propertyinfo.getvalue/vb/getvalue1.vb" id="Snippet1"::: + ]]> @@ -1528,41 +1528,41 @@ Returns the property value of a specified object with optional index values for indexed properties. The property value of the specified object. - method. If the resulting array has 0 (zero) elements, the property is not indexed. - - This is a convenience method that provides an implementation for the abstract `GetValue` method with a `BindingFlags` parameter of `Default`, the `Binder` set to `null`, and the `CultureInfo` set to `null`. - - Because static properties belong to the type, not individual objects, get static properties by passing `null` as the object argument. For example, use the following code to get the static `CurrentCulture` property of `CultureInfo` : - -```csharp -PropertyInfo CurCultProp = - (typeof(CultureInfo)).GetProperty("CurrentCulture"); -Console.WriteLine("CurrCult: " + - CurCultProp.GetValue(null,null)); -``` - - To use the `GetValue` method, first get the class `Type`. From the `Type`, get the `PropertyInfo`. From the `PropertyInfo`, use the `GetValue` method. - + method. If the resulting array has 0 (zero) elements, the property is not indexed. + + This is a convenience method that provides an implementation for the abstract `GetValue` method with a `BindingFlags` parameter of `Default`, the `Binder` set to `null`, and the `CultureInfo` set to `null`. + + Because static properties belong to the type, not individual objects, get static properties by passing `null` as the object argument. For example, use the following code to get the static `CurrentCulture` property of `CultureInfo` : + +```csharp +PropertyInfo CurCultProp = + (typeof(CultureInfo)).GetProperty("CurrentCulture"); +Console.WriteLine("CurrCult: " + + CurCultProp.GetValue(null,null)); +``` + + To use the `GetValue` method, first get the class `Type`. From the `Type`, get the `PropertyInfo`. From the `PropertyInfo`, use the `GetValue` method. + > [!NOTE] -> Starting with .NET Framework 2.0, this method can be used to access non-public members if the caller has been granted with the flag and if the grant set of the non-public members is restricted to the caller's grant set, or a subset thereof. (See [Security Considerations for Reflection](/dotnet/framework/reflection-and-codedom/security-considerations-for-reflection).) To use this functionality, your application should target .NET Framework 3.5 or later. - - - -## Examples - The following example shows how to get the value of an indexed property. The property is the default property (the indexer in C#) of the class. - +> Starting with .NET Framework 2.0, this method can be used to access non-public members if the caller has been granted with the flag and if the grant set of the non-public members is restricted to the caller's grant set, or a subset thereof. (See [Security Considerations for Reflection](/dotnet/framework/reflection-and-codedom/security-considerations-for-reflection).) To use this functionality, your application should target .NET Framework 3.5 or later. + + + +## Examples + The following example shows how to get the value of an indexed property. The property is the default property (the indexer in C#) of the class. + :::code language="csharp" source="~/snippets/csharp/System.Reflection/PropertyInfo/GetValue/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.reflection.PropertyInfo.GetValue Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.reflection.PropertyInfo.GetValue Example/VB/source.vb" id="Snippet1"::: + ]]> - The array does not contain the type of arguments needed. - - -or- - + The array does not contain the type of arguments needed. + + -or- + The property's accessor is not found. The object does not match the target type, or a property is an instance property but is . @@ -1616,11 +1616,11 @@ Note: In - - - - + + + + + The object whose property value will be returned. @@ -1631,31 +1631,31 @@ Note: In method. If the resulting array has 0 (zero) elements, the property is not indexed. - - Because static properties belong to the type, not individual objects, get static properties by passing `null` as the object argument. For example, use the following code to get the static `CurrentCulture` property of `CultureInfo` : - -```csharp -PropertyInfo CurCultProp = - (typeof(CultureInfo)).GetProperty("CurrentCulture"); -Console.WriteLine("CurrCult: " + - CurCultProp.GetValue(null,null)); -``` - - To use the `GetValue` method, first get the class `Type`. From the `Type`, get the `PropertyInfo`. From the `PropertyInfo`, use the `GetValue` method. - + method. If the resulting array has 0 (zero) elements, the property is not indexed. + + Because static properties belong to the type, not individual objects, get static properties by passing `null` as the object argument. For example, use the following code to get the static `CurrentCulture` property of `CultureInfo` : + +```csharp +PropertyInfo CurCultProp = + (typeof(CultureInfo)).GetProperty("CurrentCulture"); +Console.WriteLine("CurrCult: " + + CurCultProp.GetValue(null,null)); +``` + + To use the `GetValue` method, first get the class `Type`. From the `Type`, get the `PropertyInfo`. From the `PropertyInfo`, use the `GetValue` method. + > [!NOTE] -> Starting with .NET Framework 2.0, this method can be used to access non-public members if the caller has been granted with the flag and if the grant set of the non-public members is restricted to the caller's grant set, or a subset thereof. (See [Security Considerations for Reflection](/dotnet/framework/reflection-and-codedom/security-considerations-for-reflection).) To use this functionality, your application should target .NET Framework 3.5 or later. - +> Starting with .NET Framework 2.0, this method can be used to access non-public members if the caller has been granted with the flag and if the grant set of the non-public members is restricted to the caller's grant set, or a subset thereof. (See [Security Considerations for Reflection](/dotnet/framework/reflection-and-codedom/security-considerations-for-reflection).) To use this functionality, your application should target .NET Framework 3.5 or later. + ]]> - The array does not contain the type of arguments needed. - - -or- - + The array does not contain the type of arguments needed. + + -or- + The property's accessor is not found. The object does not match the target type, or a property is an instance property but is . The number of parameters in does not match the number of parameters the indexed property takes. @@ -1714,13 +1714,13 @@ Console.WriteLine("CurrCult: " + if this property is the special name; otherwise, . - @@ -1770,24 +1770,24 @@ Console.WriteLine("CurrCult: " + Gets a value indicating that this member is a property. A value indicating that this member is a property. - . Therefore, when you examine a set of objects - for example, the array returned by - the property returns only when a given member is a property. - - `MemberType` is a derived class of `MemberInfo` and specifies the type of member this is. Member types are constructors, properties, fields, and methods. Since this is a `PropertyInfo` property, the returned type is a property. - - To get the `MemberType` property, first get the class `Type`. From the `Type`, get the `PropertyInfo`. From the `PropertyInfo`, get the `MemberType` value. - - - -## Examples - The following example displays the type of the specified member. - + . Therefore, when you examine a set of objects - for example, the array returned by - the property returns only when a given member is a property. + + `MemberType` is a derived class of `MemberInfo` and specifies the type of member this is. Member types are constructors, properties, fields, and methods. Since this is a `PropertyInfo` property, the returned type is a property. + + To get the `MemberType` property, first get the class `Type`. From the `Type`, get the `PropertyInfo`. From the `PropertyInfo`, get the `MemberType` value. + + + +## Examples + The following example displays the type of the specified member. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic PropertyInfo.MemberType Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/PropertyInfo/MemberType/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic PropertyInfo.MemberType Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic PropertyInfo.MemberType Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -1829,8 +1829,8 @@ Console.WriteLine("CurrCult: " + System.Boolean - - + + The first object to compare. @@ -1884,8 +1884,8 @@ Console.WriteLine("CurrCult: " + System.Boolean - - + + The first object to compare. @@ -1953,25 +1953,25 @@ Console.WriteLine("CurrCult: " + Gets the type of this property. The type of this property. - object that represents the type (the class or structure) that contains the property. If you are working with an object (an instance of a type), you can call its method. Otherwise, you can use the C# operator or the Visual Basic [GetType](/dotnet/visual-basic/language-reference/operators/gettype-operator) operator, as the example illustrates. - -2. Get a object that represents the property in which you're interested. You can do this by getting an array of all properties from the method and then iterating the elements in the array, or you can retrieve the object that represents the property directly by calling the method and specifying the property name. - -3. Retrieve the value of the property from the object. - - - -## Examples - The following example defines an `Employee` class that has five properties. It then uses retrieves an array of objects that represent those properties and displays the name and type of each. - + object that represents the type (the class or structure) that contains the property. If you are working with an object (an instance of a type), you can call its method. Otherwise, you can use the C# operator or the Visual Basic [GetType](/dotnet/visual-basic/language-reference/operators/gettype-operator) operator, as the example illustrates. + +2. Get a object that represents the property in which you're interested. You can do this by getting an array of all properties from the method and then iterating the elements in the array, or you can retrieve the object that represents the property directly by calling the method and specifying the property name. + +3. Retrieve the value of the property from the object. + + + +## Examples + The following example defines an `Employee` class that has five properties. It then uses retrieves an array of objects that represent those properties and displays the name and type of each. + :::code language="csharp" source="~/snippets/csharp/System.Reflection/PropertyInfo/PropertyType/propertytype1.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.reflection.propertyinfo.propertytype/vb/propertytype1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.reflection.propertyinfo.propertytype/vb/propertytype1.vb" id="Snippet1"::: + ]]> @@ -2019,11 +2019,11 @@ Console.WriteLine("CurrCult: " + Gets the accessor for this property. The accessor for this property, or if the property is read-only. - property is equivalent to calling the method with a value of `true` for the `nonPublic` argument. - + property is equivalent to calling the method with a value of `true` for the `nonPublic` argument. + ]]> @@ -2099,35 +2099,35 @@ Console.WriteLine("CurrCult: " + The new property value. Sets the property value of a specified object. - overload sets the value of a non-indexed property. To determine whether a property is indexed, call the method. If the resulting array has 0 (zero) elements, the property is not indexed. To set the value of an indexed property, call the overload. - - If the property type of this object is a value type and `value` is `null`, the property will be set to the default value for that type. - - This is a convenience method that calls the runtime implementation of the abstract method, specifying for the `BindingFlags` parameter, `null` for `Binder`, `null` for `Object[]`, and `null` for `CultureInfo`. - - To use the method, first get a object that represents the class. From the , get the object. From the object, call the method. - + overload sets the value of a non-indexed property. To determine whether a property is indexed, call the method. If the resulting array has 0 (zero) elements, the property is not indexed. To set the value of an indexed property, call the overload. + + If the property type of this object is a value type and `value` is `null`, the property will be set to the default value for that type. + + This is a convenience method that calls the runtime implementation of the abstract method, specifying for the `BindingFlags` parameter, `null` for `Binder`, `null` for `Object[]`, and `null` for `CultureInfo`. + + To use the method, first get a object that represents the class. From the , get the object. From the object, call the method. + > [!NOTE] -> Starting with .NET Framework 2.0, this method can be used to access non-public members if the caller has been granted with the flag and if the grant set of the non-public members is restricted to the caller's grant set, or a subset thereof. (See [Security Considerations for Reflection](/dotnet/framework/reflection-and-codedom/security-considerations-for-reflection).) To use this functionality, your application should target .NET Framework 3.5 or later. - - - -## Examples - The following example declares a class named `Example` with one `static` (`Shared` in Visual Basic) and one instance property. The example uses the method to change the original property values and displays the original and final values. - +> Starting with .NET Framework 2.0, this method can be used to access non-public members if the caller has been granted with the flag and if the grant set of the non-public members is restricted to the caller's grant set, or a subset thereof. (See [Security Considerations for Reflection](/dotnet/framework/reflection-and-codedom/security-considerations-for-reflection).) To use this functionality, your application should target .NET Framework 3.5 or later. + + + +## Examples + The following example declares a class named `Example` with one `static` (`Shared` in Visual Basic) and one instance property. The example uses the method to change the original property values and displays the original and final values. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/PropertyInfo.SetValue/cpp/example2.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/PropertyInfo/SetValue/example2.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/PropertyInfo.SetValue/vb/example2.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/PropertyInfo.SetValue/vb/example2.vb" id="Snippet2"::: + ]]> - The property's accessor is not found. - - -or- - + The property's accessor is not found. + + -or- + cannot be converted to the type of . The type of does not match the target type, or a property is an instance property but is . @@ -2203,55 +2203,55 @@ Note: In Optional index values for indexed properties. This value should be for non-indexed properties. Sets the property value of a specified object with optional index values for index properties. - object is a value type and `value` is `null`, then the property will be set to the default value for that type. - - To determine whether a property is indexed, use the method. If the resulting array has 0 (zero) elements, the property is not indexed. - - This is a convenience method that calls the runtime implementation of the abstract method, specifying for the `BindingFlags` parameter, `null` for `Binder`, and `null` for `CultureInfo`. - - To use the method, first get a object that represents the class. From the , get the . From the , use the method. - + object is a value type and `value` is `null`, then the property will be set to the default value for that type. + + To determine whether a property is indexed, use the method. If the resulting array has 0 (zero) elements, the property is not indexed. + + This is a convenience method that calls the runtime implementation of the abstract method, specifying for the `BindingFlags` parameter, `null` for `Binder`, and `null` for `CultureInfo`. + + To use the method, first get a object that represents the class. From the , get the . From the , use the method. + > [!NOTE] -> Starting with .NET Framework 2.0, this method can be used to access non-public members if the caller has been granted with the flag and if the grant set of the non-public members is restricted to the caller's grant set, or a subset thereof. (See [Security Considerations for Reflection](/dotnet/framework/reflection-and-codedom/security-considerations-for-reflection).) To use this functionality, your application should target .NET Framework 3.5 or later. - - - -## Examples - The following example defines a class named `TestClass` that has a read-write property named `Caption`. It displays the default value of the `Caption` property, calls the method to change the property value, and displays the result. - +> Starting with .NET Framework 2.0, this method can be used to access non-public members if the caller has been granted with the flag and if the grant set of the non-public members is restricted to the caller's grant set, or a subset thereof. (See [Security Considerations for Reflection](/dotnet/framework/reflection-and-codedom/security-considerations-for-reflection).) To use this functionality, your application should target .NET Framework 3.5 or later. + + + +## Examples + The following example defines a class named `TestClass` that has a read-write property named `Caption`. It displays the default value of the `Caption` property, calls the method to change the property value, and displays the result. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic PropertyInfo.SetValue1 Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/PropertyInfo/SetValue/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic PropertyInfo.SetValue1 Example/VB/source.vb" id="Snippet1"::: - - Note that, because the `Caption` property is not a parameter array, the `index` argument is `null`. - - The following example declares a class named `Example` with three properties: a `static` property (`Shared` in Visual Basic), an instance property, and an indexed instance property. The example uses the method to change the default values of the properties and displays the original and final values. - - The name that is used to search for an indexed instance property with reflection is different depending on the language and on attributes applied to the property. - -- In Visual Basic, the property name is always used to search for the property with reflection. You can use the `Default` keyword to make the property a default indexed property, in which case you can omit the name when accessing the property, as in this example. You can also use the property name. - -- In C#, the indexed instance property is a default property called an indexer, and the name is never used when accessing the property in code. By default, the name of the property is `Item`, and you must use that name when you search for the property with reflection. You can use the attribute to give the indexer a different name. In this example, the name is `IndexedInstanceProperty`. - -- In C++, the `default` specifier can be used to make an indexed property a default indexed property (class indexer). In that case, the name of the property by default is `Item`, and you must use that name when you search for the property with reflection, as in this example. You can use the attribute to give the class indexer a different name in reflection, but you cannot use that name to access the property in code. An indexed property that is not a class indexer is accessed using its name, both in code and in reflection. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic PropertyInfo.SetValue1 Example/VB/source.vb" id="Snippet1"::: + + Note that, because the `Caption` property is not a parameter array, the `index` argument is `null`. + + The following example declares a class named `Example` with three properties: a `static` property (`Shared` in Visual Basic), an instance property, and an indexed instance property. The example uses the method to change the default values of the properties and displays the original and final values. + + The name that is used to search for an indexed instance property with reflection is different depending on the language and on attributes applied to the property. + +- In Visual Basic, the property name is always used to search for the property with reflection. You can use the `Default` keyword to make the property a default indexed property, in which case you can omit the name when accessing the property, as in this example. You can also use the property name. + +- In C#, the indexed instance property is a default property called an indexer, and the name is never used when accessing the property in code. By default, the name of the property is `Item`, and you must use that name when you search for the property with reflection. You can use the attribute to give the indexer a different name. In this example, the name is `IndexedInstanceProperty`. + +- In C++, the `default` specifier can be used to make an indexed property a default indexed property (class indexer). In that case, the name of the property by default is `Item`, and you must use that name when you search for the property with reflection, as in this example. You can use the attribute to give the class indexer a different name in reflection, but you cannot use that name to access the property in code. An indexed property that is not a class indexer is accessed using its name, both in code and in reflection. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/PropertyInfo.SetValue/cpp/Example.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/PropertyInfo/SetValue/Example.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/PropertyInfo.SetValue/vb/Example.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/PropertyInfo.SetValue/vb/Example.vb" id="Snippet1"::: + ]]> - The array does not contain the type of arguments needed. - - -or- - - The property's accessor is not found. - - -or- - + The array does not contain the type of arguments needed. + + -or- + + The property's accessor is not found. + + -or- + cannot be converted to the type of . The object does not match the target type, or a property is an instance property but is . @@ -2305,12 +2305,12 @@ Note: In - - - - - + + + + + + The object whose property value will be set. @@ -2321,30 +2321,30 @@ Note: In The culture for which the resource is to be localized. If the resource is not localized for this culture, the property will be called successively in search of a match. If this value is , the culture-specific information is obtained from the property. When overridden in a derived class, sets the property value for a specified object that has the specified binding, index, and culture-specific information. - object is a value type and `value` is `null`, then the property will be set to the default value for that type. - - To determine whether a property is indexed, use the method. If the resulting array has 0 (zero) elements, the property is not indexed. - - Access restrictions are ignored for fully trusted code. That is, private constructors, methods, fields, and properties can be accessed and invoked via Reflection whenever the code is fully trusted. - - To use the `SetValue` method, first get the class `Type`. From the `Type`, get the `PropertyInfo`. From the `PropertyInfo`, use the `SetValue` method. - + object is a value type and `value` is `null`, then the property will be set to the default value for that type. + + To determine whether a property is indexed, use the method. If the resulting array has 0 (zero) elements, the property is not indexed. + + Access restrictions are ignored for fully trusted code. That is, private constructors, methods, fields, and properties can be accessed and invoked via Reflection whenever the code is fully trusted. + + To use the `SetValue` method, first get the class `Type`. From the `Type`, get the `PropertyInfo`. From the `PropertyInfo`, use the `SetValue` method. + > [!NOTE] -> Starting with .NET Framework 2.0, this method can be used to access non-public members if the caller has been granted with the flag and if the grant set of the non-public members is restricted to the caller's grant set, or a subset thereof. (See [Security Considerations for Reflection](/dotnet/framework/reflection-and-codedom/security-considerations-for-reflection).) To use this functionality, your application should target .NET Framework 3.5 or later. - +> Starting with .NET Framework 2.0, this method can be used to access non-public members if the caller has been granted with the flag and if the grant set of the non-public members is restricted to the caller's grant set, or a subset thereof. (See [Security Considerations for Reflection](/dotnet/framework/reflection-and-codedom/security-considerations-for-reflection).) To use this functionality, your application should target .NET Framework 3.5 or later. + ]]> - The array does not contain the type of arguments needed. - - -or- - - The property's accessor is not found. - - -or- - + The array does not contain the type of arguments needed. + + -or- + + The property's accessor is not found. + + -or- + cannot be converted to the type of . The object does not match the target type, or a property is an instance property but is . The number of parameters in does not match the number of parameters the indexed property takes. @@ -2382,11 +2382,11 @@ Note: In - - - - + + + + + Reserved for future use. Must be IID_NULL. @@ -2396,11 +2396,11 @@ Note: In Caller-allocated array which receives the IDs corresponding to the names. Maps a set of names to a corresponding set of dispatch identifiers. - Late-bound access using the COM IDispatch interface is not supported. @@ -2471,9 +2471,9 @@ Note: In - - + + + The type information to return. @@ -2481,11 +2481,11 @@ Note: In Receives a pointer to the requested type information object. Retrieves the type information for an object, which can then be used to get the type information for an interface. - Late-bound access using the COM IDispatch interface is not supported. @@ -2521,17 +2521,17 @@ Note: In + Points to a location that receives the number of type information interfaces provided by the object. Retrieves the number of type information interfaces that an object provides (either 0 or 1). - Late-bound access using the COM IDispatch interface is not supported. @@ -2567,14 +2567,14 @@ Note: In - - - - - - - + + + + + + + + Identifies the member. @@ -2587,11 +2587,11 @@ Note: In The index of the first argument that has an error. Provides access to properties and methods exposed by an object. - Late-bound access using the COM IDispatch interface is not supported. diff --git a/xml/System.Reflection/ReflectionTypeLoadException.xml b/xml/System.Reflection/ReflectionTypeLoadException.xml index 2c071679973..638ef66a335 100644 --- a/xml/System.Reflection/ReflectionTypeLoadException.xml +++ b/xml/System.Reflection/ReflectionTypeLoadException.xml @@ -88,15 +88,15 @@ The exception that is thrown by the method if any of the classes in a module cannot be loaded. This class cannot be inherited. - @@ -281,8 +281,8 @@ System.Void - - + + The information and data needed to serialize or deserialize an object. @@ -345,11 +345,11 @@ Gets the array of exceptions thrown by the class loader. An array of type containing the exceptions thrown by the class loader. The null values in the array of this instance line up with the exceptions in this array. - property retrieves an array of type `Exception` that is parallel to the array. This array will contain null values whenever reflection cannot load a class. - + property retrieves an array of type `Exception` that is parallel to the array. This array will contain null values whenever reflection cannot load a class. + ]]> @@ -479,11 +479,11 @@ Gets the array of classes that were defined in the module and loaded. An array of type containing the classes that were defined in the module and loaded. This array can contain some values. - property retrieves an array of type `Exception` that is parallel to this `Types` array. This array will contain null values whenever reflection cannot load a class. - + property retrieves an array of type `Exception` that is parallel to this `Types` array. This array will contain null values whenever reflection cannot load a class. + ]]> diff --git a/xml/System.Resources/MissingManifestResourceException.xml b/xml/System.Resources/MissingManifestResourceException.xml index 22d4bad16e2..20458d68d8d 100644 --- a/xml/System.Resources/MissingManifestResourceException.xml +++ b/xml/System.Resources/MissingManifestResourceException.xml @@ -255,8 +255,8 @@ - - + + The object that holds the serialized object data. diff --git a/xml/System.Resources/NeutralResourcesLanguageAttribute.xml b/xml/System.Resources/NeutralResourcesLanguageAttribute.xml index aa9a0979dbe..d0e681542bd 100644 --- a/xml/System.Resources/NeutralResourcesLanguageAttribute.xml +++ b/xml/System.Resources/NeutralResourcesLanguageAttribute.xml @@ -177,8 +177,8 @@ For a detailed list of culture names available on Windows systems, see the **Lan 9.0.0.0 - - + + The name of the culture that the current assembly's neutral resources were written in. diff --git a/xml/System.Resources/ResourceManager.xml b/xml/System.Resources/ResourceManager.xml index fa4e9f06cfb..2760a668635 100644 --- a/xml/System.Resources/ResourceManager.xml +++ b/xml/System.Resources/ResourceManager.xml @@ -287,9 +287,9 @@ - - - + + + [System.Diagnostics.CodeAnalysis.DynamicallyAccessedMembers(System.Diagnostics.CodeAnalysis.DynamicallyAccessedMemberTypes.NonPublicConstructors | System.Diagnostics.CodeAnalysis.DynamicallyAccessedMemberTypes.PublicConstructors)] @@ -471,9 +471,9 @@ System.Resources.ResourceManager - - - + + + [System.Diagnostics.CodeAnalysis.DynamicallyAccessedMembers(System.Diagnostics.CodeAnalysis.DynamicallyAccessedMemberTypes.NonPublicConstructors | System.Diagnostics.CodeAnalysis.DynamicallyAccessedMemberTypes.PublicConstructors)] @@ -606,7 +606,7 @@ System.Globalization.CultureInfo - + The assembly for which to return culture-specific information. @@ -664,7 +664,7 @@ System.Object - + The name of the resource to get. @@ -723,7 +723,7 @@ System.Object - + [System.Runtime.CompilerServices.Nullable(1)] @@ -731,7 +731,7 @@ - + The name of the resource to get. @@ -788,7 +788,7 @@ System.String - + The culture object for which a resource file name is constructed. @@ -855,9 +855,9 @@ System.Resources.ResourceSet - - - + + + The culture whose resources are to be retrieved. @@ -988,7 +988,7 @@ al /out:fr-FR\ShowNumbers.resources.dll /culture:fr-FR /embed:NumberResources.fr System.Version - + The assembly to check for the attribute. @@ -1066,7 +1066,7 @@ al /out:fr-FR\ShowNumbers.resources.dll /culture:fr-FR /embed:NumberResources.fr System.IO.UnmanagedMemoryStream - + The name of a resource. @@ -1169,7 +1169,7 @@ csc GetStream.cs /resource:AppResources.resources System.IO.UnmanagedMemoryStream - + [System.Runtime.CompilerServices.Nullable(1)] @@ -1177,7 +1177,7 @@ csc GetStream.cs /resource:AppResources.resources - + The name of a resource. @@ -1493,9 +1493,9 @@ csc GetStream.cs /resource:AppResources.resources System.Resources.ResourceSet - - - + + + The culture object to look for. diff --git a/xml/System.Runtime.CompilerServices/CompilationRelaxationsAttribute.xml b/xml/System.Runtime.CompilerServices/CompilationRelaxationsAttribute.xml index 640b4dc13dc..7f5225bbf66 100644 --- a/xml/System.Runtime.CompilerServices/CompilationRelaxationsAttribute.xml +++ b/xml/System.Runtime.CompilerServices/CompilationRelaxationsAttribute.xml @@ -66,23 +66,23 @@ Controls the strictness of the code generated by the common language runtime's just-in-time (JIT) compiler. - attribute to assemblies to specify assembly compilation parameters. Use the enumeration to specify compilation options. - - This attribute is ignored in version 1.0 of the Microsoft .NET Framework. - - The classes in are for compiler writers' use only. - - - -## Examples - The following example demonstrates how to apply the . - + attribute to assemblies to specify assembly compilation parameters. Use the enumeration to specify compilation options. + + This attribute is ignored in version 1.0 of the Microsoft .NET Framework. + + The classes in are for compiler writers' use only. + + + +## Examples + The following example demonstrates how to apply the . + :::code language="csharp" source="~/snippets/csharp/System.Runtime.CompilerServices/CompilationRelaxationsAttribute/Overview/example.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Runtime.CompilerServices.CompilationRelaxationsAttribute/vb/example.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Runtime.CompilerServices.CompilationRelaxationsAttribute/vb/example.vb" id="Snippet1"::: + ]]> @@ -143,13 +143,13 @@ The compilation relaxations. Initializes a new instance of the class with the specified compilation relaxations. - attribute to assemblies to specify assembly compilation parameters. - - This attribute is ignored in version 1.0 of the Microsoft .NET Framework. - + attribute to assemblies to specify assembly compilation parameters. + + This attribute is ignored in version 1.0 of the Microsoft .NET Framework. + ]]> @@ -186,19 +186,19 @@ 9.0.0.0 - + One of the values. Initializes a new instance of the class with the specified value. - attribute to assemblies to specify assembly compilation parameters. - - This attribute is ignored in version 1.0 of the Microsoft .NET Framework. - + attribute to assemblies to specify assembly compilation parameters. + + This attribute is ignored in version 1.0 of the Microsoft .NET Framework. + ]]> @@ -244,8 +244,8 @@ Gets the compilation relaxations specified when the current object was constructed. - The compilation relaxations specified when the current object was constructed. - + The compilation relaxations specified when the current object was constructed. + Use the enumeration with the property. To be added. diff --git a/xml/System.Runtime.CompilerServices/MethodImplAttribute.xml b/xml/System.Runtime.CompilerServices/MethodImplAttribute.xml index 36a13cf32e6..6c708a65b1d 100644 --- a/xml/System.Runtime.CompilerServices/MethodImplAttribute.xml +++ b/xml/System.Runtime.CompilerServices/MethodImplAttribute.xml @@ -62,26 +62,26 @@ Specifies the details of how a method is implemented. This class cannot be inherited. - value to its class constructor. The members of the enumeration correspond to bit fields in the `CorMethodImpl` metadata table. This means that information on the attribute cannot be retrieved at run time by calling the method; instead, it is retrieved by calling either the `MethodInfo.GetMethodImplementationFlags` or the `ConstructorInfo.GetMethodImplementationFlags` method. - - - -## Examples - The following example applies the to the `GetCalendarName` method to ensure that it is not inlined at run time by the just-in-time (JIT) compiler. - + value to its class constructor. The members of the enumeration correspond to bit fields in the `CorMethodImpl` metadata table. This means that information on the attribute cannot be retrieved at run time by calling the method; instead, it is retrieved by calling either the `MethodInfo.GetMethodImplementationFlags` or the `ConstructorInfo.GetMethodImplementationFlags` method. + + + +## Examples + The following example applies the to the `GetCalendarName` method to ensure that it is not inlined at run time by the just-in-time (JIT) compiler. + :::code language="csharp" source="~/snippets/csharp/System.Runtime.CompilerServices/MethodImplAttribute/Overview/methodimplattribute1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.runtime.compilerservices.methodimplattribute/vb/methodimplattribute1.vb" id="Snippet1"::: - - The following example then calls the `MethodInfo.GetMethodImplementationFlags` method to determine which flags are set for the `GetCalendarName` method. It also demonstrates that this information is not retrieved by the method. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.runtime.compilerservices.methodimplattribute/vb/methodimplattribute1.vb" id="Snippet1"::: + + The following example then calls the `MethodInfo.GetMethodImplementationFlags` method to determine which flags are set for the `GetCalendarName` method. It also demonstrates that this information is not retrieved by the method. + :::code language="csharp" source="~/snippets/csharp/System.Runtime.CompilerServices/MethodImplAttribute/Overview/getmethodimplattribute1.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.runtime.compilerservices.methodimplattribute/vb/getmethodimplattribute1.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.runtime.compilerservices.methodimplattribute/vb/getmethodimplattribute1.vb" id="Snippet2"::: + ]]> @@ -165,7 +165,7 @@ 9.0.0.0 - + A bitmask representing the desired value which specifies properties of the attributed method. @@ -215,11 +215,11 @@ A value specifying properties of the attributed method. Initializes a new instance of the class with the specified value. - diff --git a/xml/System.Runtime.CompilerServices/RuntimeHelpers.xml b/xml/System.Runtime.CompilerServices/RuntimeHelpers.xml index fc7650cdd7d..2754d0db9a7 100644 --- a/xml/System.Runtime.CompilerServices/RuntimeHelpers.xml +++ b/xml/System.Runtime.CompilerServices/RuntimeHelpers.xml @@ -282,8 +282,8 @@ This method is intended for compiler use rather than use directly in code. `T` m System.Boolean - - + + The first object to compare. @@ -355,9 +355,9 @@ This method is intended for compiler use rather than use directly in code. `T` m System.Void - - - + + + [System.Runtime.CompilerServices.Nullable(2)] @@ -979,7 +979,7 @@ This method is intended for compiler use rather than use directly in code. `T` m System.Void - + The event delegate to prepare. @@ -1042,7 +1042,7 @@ This method is intended for compiler use rather than use directly in code. `T` m System.Void - + The delegate type to prepare. @@ -1107,7 +1107,7 @@ This method is intended for compiler use rather than use directly in code. `T` m System.Void - + A handle to the method to prepare. @@ -1167,8 +1167,8 @@ This method is intended for compiler use rather than use directly in code. `T` m System.Void - - + + A handle to the method to prepare. @@ -1349,7 +1349,7 @@ This method is intended for compiler use rather than use directly in code. `T` m System.Void - + A handle that specifies the module constructor method to run. diff --git a/xml/System.Runtime.InteropServices/COMException.xml b/xml/System.Runtime.InteropServices/COMException.xml index 87c88b303d7..db705d5cd09 100644 --- a/xml/System.Runtime.InteropServices/COMException.xml +++ b/xml/System.Runtime.InteropServices/COMException.xml @@ -252,8 +252,8 @@ - - + + The object that holds the serialized object data. diff --git a/xml/System.Runtime.InteropServices/ComAwareEventInfo.xml b/xml/System.Runtime.InteropServices/ComAwareEventInfo.xml index d57c98c1678..491076e532c 100644 --- a/xml/System.Runtime.InteropServices/ComAwareEventInfo.xml +++ b/xml/System.Runtime.InteropServices/ComAwareEventInfo.xml @@ -68,15 +68,15 @@ Permits late-bound registration of an event handler. - and methods instead of using regular add handler and remove handler methods for events. This occurs if the interface that the corresponding event is defined on needs to be embedded. - - You can specify this by embedding the entire assembly that contains the interface by using the **/link** option on the compilers or by setting the **Embed Interop Types** property to `True` in Visual Studio. - - The type derives from the class and overrides the and methods. - + and methods instead of using regular add handler and remove handler methods for events. This occurs if the interface that the corresponding event is defined on needs to be embedded. + + You can specify this by embedding the entire assembly that contains the interface by using the **/link** option on the compilers or by setting the **Embed Interop Types** property to `True` in Visual Studio. + + The type derives from the class and overrides the and methods. + ]]> @@ -185,25 +185,25 @@ The event delegate. Attaches an event handler to a COM object. - method except that it allows you to attach events to COM objects. - - If `target` is a COM object, this method adds a delegate to an event by using the method. - - facilitates registering COM event sinks that forward calls to corresponding managed delegates. It requires the following information: - -- The target object itself (`target`). - -- The GUID of the source interface. - -- The DispID of the method on the COM interface that corresponds to the specified event. - -- The delegate that would be invoked when the COM object triggers the corresponding event (`handler`). - - looks up the corresponding COM source interface (specified as the first parameter of the constructor). It then looks up a method on the source interface whose name is identical to the event name. The value of `GuidAttribute` on the source interface is the GUID that is passed to ; the value of `DispIDAttribute` on the method is the DispID value that is passed to . - + method except that it allows you to attach events to COM objects. + + If `target` is a COM object, this method adds a delegate to an event by using the method. + + facilitates registering COM event sinks that forward calls to corresponding managed delegates. It requires the following information: + +- The target object itself (`target`). + +- The GUID of the source interface. + +- The DispID of the method on the COM interface that corresponds to the specified event. + +- The delegate that would be invoked when the COM object triggers the corresponding event (`handler`). + + looks up the corresponding COM source interface (specified as the first parameter of the constructor). It then looks up a method on the source interface whose name is identical to the event name. The value of `GuidAttribute` on the source interface is the GUID that is passed to ; the value of `DispIDAttribute` on the method is the DispID value that is passed to . + ]]> @@ -249,11 +249,11 @@ Gets the attributes for this event. The read-only attributes for this event. - @@ -353,7 +353,7 @@ System.Reflection.MethodInfo - + @@ -361,11 +361,11 @@ Gets the method that was used to add an event handler delegate to the event source. The method that was used to add an event handler delegate to the event source. - method. - + method. + ]]> @@ -415,7 +415,7 @@ System.Object[] - + @@ -423,11 +423,11 @@ When overridden in a derived class, gets an array that contains all the custom attributes that are applied to this member. An array that contains all the custom attributes, or an array that has no elements if no attributes were defined. - method of the underlying object. - + method of the underlying object. + ]]> This member belongs to a type that is loaded into the reflection-only context. See [How to: Load Assemblies into the Reflection-Only Context](/dotnet/framework/reflection-and-codedom/how-to-load-assemblies-into-the-reflection-only-context). @@ -468,8 +468,8 @@ System.Object[] - - + + The attribute type to search for. Only attributes that are assignable to this type can be returned. @@ -597,7 +597,7 @@ System.Reflection.MethodInfo - + @@ -605,11 +605,11 @@ When overridden in a derived class, returns the method that was called when the event was raised. The object that was called when the event was raised. - @@ -656,7 +656,7 @@ System.Reflection.MethodInfo - + @@ -702,8 +702,8 @@ System.Boolean - - + + The attribute type to search for. @@ -929,33 +929,33 @@ The event delegate. Detaches an event handler from a COM object. - method, except that it allows you to detach events from COM objects. - - If `target` is a COM object, this method releases a delegate to an event by using the method. - - facilitates unregistering COM event sinks that forward calls to corresponding managed delegates. It requires the following information: - -- The target object itself (`target`). - -- The GUID of the source interface. - -- The DispID of the method on the COM interface that corresponds to the specified event. - -- The delegate that would be invoked when the COM object triggers the corresponding event (`handler`). - - looks up the corresponding COM source interface (specified as the first parameter of the constructor). It then it looks up a method on the source interface whose name is identical to the event name. The value of `GuidAttribute` on the source interface is the GUID that is passed to ; the value of `DispIDAttribute` on the method is the DispID value that is passed to . - + method, except that it allows you to detach events from COM objects. + + If `target` is a COM object, this method releases a delegate to an event by using the method. + + facilitates unregistering COM event sinks that forward calls to corresponding managed delegates. It requires the following information: + +- The target object itself (`target`). + +- The GUID of the source interface. + +- The DispID of the method on the COM interface that corresponds to the specified event. + +- The delegate that would be invoked when the COM object triggers the corresponding event (`handler`). + + looks up the corresponding COM source interface (specified as the first parameter of the constructor). It then it looks up a method on the source interface whose name is identical to the event name. The value of `GuidAttribute` on the source interface is the GUID that is passed to ; the value of `DispIDAttribute` on the method is the DispID value that is passed to . + ]]> The event does not have a public accessor. The handler that was passed in cannot be used. - The parameter is and the event is not static. - - -or- - + The parameter is and the event is not static. + + -or- + The is not declared on the target. Note: In .NET for Windows Store apps or the Portable Class Library, catch instead. diff --git a/xml/System.Runtime.InteropServices/InvalidComObjectException.xml b/xml/System.Runtime.InteropServices/InvalidComObjectException.xml index 980030ca253..d8bcc541012 100644 --- a/xml/System.Runtime.InteropServices/InvalidComObjectException.xml +++ b/xml/System.Runtime.InteropServices/InvalidComObjectException.xml @@ -73,13 +73,13 @@ The exception thrown when an invalid COM object is used. - . - - `InvalidComObjectException` uses the HRESULT COR_E_INVALIDCOMOBJECT which has the value 0x80131527. - + . + + `InvalidComObjectException` uses the HRESULT COR_E_INVALIDCOMOBJECT which has the value 0x80131527. + ]]> @@ -139,16 +139,16 @@ Initializes an instance of the with default properties. - . This constructor sets the properties of the object as shown in the following table. - -|Property Type|Value| -|-------------------|-----------| -||`null`.| -||A localized error message string.| - + . This constructor sets the properties of the object as shown in the following table. + +|Property Type|Value| +|-------------------|-----------| +||`null`.| +||A localized error message string.| + ]]> @@ -197,16 +197,16 @@ The message that indicates the reason for the exception. Initializes an instance of the with a message. - . This constructor sets the properties of the object as shown in the following table. - -|Property Type|Value| -|-------------------|-----------| -||`null`.| -||`message`| - + . This constructor sets the properties of the object as shown in the following table. + +|Property Type|Value| +|-------------------|-----------| +||`null`.| +||`message`| + ]]> @@ -261,21 +261,21 @@ - - + + The object that holds the serialized object data. The contextual information about the source or destination. Initializes a new instance of the class from serialization data. - . - - `InvalidComObjectException` inherits from . - + . + + `InvalidComObjectException` inherits from . + ]]> @@ -328,18 +328,18 @@ The exception that is the cause of the current exception. If the parameter is not , the current exception is raised in a block that handles the inner exception. Initializes a new instance of the class with a specified error message and a reference to the inner exception that is the cause of this exception. - property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||The inner exception reference.| -||The error message string.| - + property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||The inner exception reference.| +||The error message string.| + ]]> diff --git a/xml/System.Runtime.InteropServices/InvalidOleVariantTypeException.xml b/xml/System.Runtime.InteropServices/InvalidOleVariantTypeException.xml index b25f05ee79a..a0ed7f00034 100644 --- a/xml/System.Runtime.InteropServices/InvalidOleVariantTypeException.xml +++ b/xml/System.Runtime.InteropServices/InvalidOleVariantTypeException.xml @@ -73,11 +73,11 @@ The exception thrown by the marshaler when it encounters an argument of a variant type that can not be marshaled to managed code. - @@ -137,16 +137,16 @@ Initializes a new instance of the class with default values. - . This constructor sets the properties of the object as shown in the following table. - -|Property|Value| -|--------------|-----------| -||`null`.| -||A localized error message string.| - + . This constructor sets the properties of the object as shown in the following table. + +|Property|Value| +|--------------|-----------| +||`null`.| +||A localized error message string.| + ]]> @@ -195,16 +195,16 @@ The message that indicates the reason for the exception. Initializes a new instance of the class with a specified message. - . This constructor sets the properties of the object as shown in the following table. - -|Property|Value| -|--------------|-----------| -||`null`.| -||`message`| - + . This constructor sets the properties of the object as shown in the following table. + +|Property|Value| +|--------------|-----------| +||`null`.| +||`message`| + ]]> @@ -259,21 +259,21 @@ - - + + The object that holds the serialized object data. The contextual information about the source or destination. Initializes a new instance of the class from serialization data. - . - - `InvalidOleVariantTypeException` inherits from . - + . + + `InvalidOleVariantTypeException` inherits from . + ]]> @@ -326,18 +326,18 @@ The exception that is the cause of the current exception. If the parameter is not , the current exception is raised in a block that handles the inner exception. Initializes a new instance of the class with a specified error message and a reference to the inner exception that is the cause of this exception. - property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||The inner exception reference.| -||The error message string.| - + property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||The inner exception reference.| +||The error message string.| + ]]> diff --git a/xml/System.Runtime.InteropServices/Marshal.xml b/xml/System.Runtime.InteropServices/Marshal.xml index 33db38a1fa7..09d336e79b0 100644 --- a/xml/System.Runtime.InteropServices/Marshal.xml +++ b/xml/System.Runtime.InteropServices/Marshal.xml @@ -504,7 +504,7 @@ System.Object - + The moniker corresponding to the desired interface pointer. @@ -566,8 +566,8 @@ System.Void - - + + The object whose CCW holds a reference counted handle. The handle is strong if the reference count on the CCW is greater than zero; otherwise, it is weak. @@ -2721,7 +2721,7 @@ System.Guid - + The type to generate a GUID for. @@ -2779,7 +2779,7 @@ System.String - + The type to get a ProgID for. @@ -2827,7 +2827,7 @@ System.Object - + The programmatic identifier (ProgID) of the object that was requested. @@ -3188,8 +3188,8 @@ The code retrieves a reference to an instance of Microsoft Word successfully. Ho System.IntPtr - - + + The object that provides the interface. @@ -3270,8 +3270,8 @@ The code retrieves a reference to an instance of Microsoft Word successfully. Ho System.Object - - + + The COM object that contains the data that you want. @@ -3331,7 +3331,7 @@ The code retrieves a reference to an instance of Microsoft Word successfully. Ho System.Int32 - + An object that represents an interface method. @@ -3574,7 +3574,7 @@ The code retrieves a reference to an instance of Microsoft Word successfully. Ho System.Int32 - + A type that represents an interface or class. @@ -4064,7 +4064,7 @@ The code retrieves a reference to an instance of Microsoft Word successfully. Ho System.IntPtr - + The module whose HINSTANCE is desired. @@ -4267,7 +4267,7 @@ The code retrieves a reference to an instance of Microsoft Word successfully. Ho System.IntPtr - + The object whose interface is requested. @@ -4318,7 +4318,7 @@ The code retrieves a reference to an instance of Microsoft Word successfully. Ho System.IntPtr - + The object whose interface is requested. @@ -4370,7 +4370,7 @@ The code retrieves a reference to an instance of Microsoft Word successfully. Ho System.IntPtr - + The type whose interface is being requested. @@ -4510,7 +4510,7 @@ The code retrieves a reference to an instance of Microsoft Word successfully. Ho System.IntPtr - + The object whose interface is requested. @@ -4776,9 +4776,9 @@ On .NET 6 and later versions, this method is functionally equivalent to System.IntPtr - - - + + + A pointer to the method to marshal. @@ -4826,9 +4826,9 @@ On .NET 6 and later versions, this method is functionally equivalent to System.Reflection.MemberInfo - - - + + + The type for which the is to be retrieved. @@ -5592,7 +5592,7 @@ On .NET 6 and later versions, this method is functionally equivalent to System.Threading.Thread - + An integer that represents a fiber cookie. @@ -5654,8 +5654,8 @@ On .NET 6 and later versions, this method is functionally equivalent to System.Object - - + + A pointer to the interface of the unmanaged object. @@ -5711,7 +5711,7 @@ On .NET 6 and later versions, this method is functionally equivalent to System.Type - + The interface to marshal. @@ -5907,7 +5907,7 @@ On .NET 6 and later versions, this method is functionally equivalent to System.String - + An object that represents an pointer. @@ -5963,7 +5963,7 @@ On .NET 6 and later versions, this method is functionally equivalent to System.Guid - + The type library whose LIBID is to be retrieved. @@ -6017,7 +6017,7 @@ On .NET 6 and later versions, this method is functionally equivalent to System.Guid - + The type library whose LIBID is to be retrieved. @@ -6067,7 +6067,7 @@ On .NET 6 and later versions, this method is functionally equivalent to System.Guid - + The assembly from which the type library was exported. @@ -6128,7 +6128,7 @@ On .NET 6 and later versions, this method is functionally equivalent to System.Int32 - + The type library whose LCID is to be retrieved. @@ -6171,7 +6171,7 @@ On .NET 6 and later versions, this method is functionally equivalent to System.Int32 - + The type library whose LCID is to be retrieved. @@ -6219,7 +6219,7 @@ On .NET 6 and later versions, this method is functionally equivalent to System.String - + The type library whose name is to be retrieved. @@ -6273,7 +6273,7 @@ On .NET 6 and later versions, this method is functionally equivalent to System.String - + The type library whose name is to be retrieved. @@ -6321,9 +6321,9 @@ On .NET 6 and later versions, this method is functionally equivalent to System.Void - - - + + + A managed assembly. @@ -6446,9 +6446,9 @@ On .NET 6 and later versions, this method is functionally equivalent to System.IntPtr - - - + + + A pointer to the method to marshal. @@ -6610,7 +6610,7 @@ On .NET 6 and later versions, this method is functionally equivalent to System.Boolean - + The type to check for COM visibility. @@ -6658,7 +6658,7 @@ On .NET 6 and later versions, this method is functionally equivalent to System.Int32 - + The method to be checked. @@ -6867,7 +6867,7 @@ On .NET 6 and later versions, this method is functionally equivalent to System.Void - + The method to be checked. @@ -6937,7 +6937,7 @@ On .NET 6 and later versions, this method is functionally equivalent to System.Void - + The class whose methods are to be checked. @@ -7175,7 +7175,7 @@ On .NET 6 and later versions, this method is functionally equivalent to System.String - + For Unicode platforms, the address of the first Unicode character. @@ -7247,8 +7247,8 @@ On .NET 6 and later versions, this method is functionally equivalent to System.String - - + + For Unicode platforms, the address of the first Unicode character. @@ -9834,7 +9834,7 @@ On .NET 6 and later versions, this method is functionally equivalent to System.IntPtr - + The managed object to copy. @@ -9896,7 +9896,7 @@ On .NET 6 and later versions, this method is functionally equivalent to System.IntPtr - + The managed object to copy. @@ -9966,7 +9966,7 @@ On .NET 6 and later versions, this method is functionally equivalent to System.IntPtr - + The managed object to copy. @@ -10036,7 +10036,7 @@ On .NET 6 and later versions, this method is functionally equivalent to System.IntPtr - + The managed object to copy. @@ -10106,7 +10106,7 @@ On .NET 6 and later versions, this method is functionally equivalent to System.IntPtr - + The managed object to copy. @@ -10177,9 +10177,9 @@ On .NET 6 and later versions, this method is functionally equivalent to System.Boolean - - - + + + [System.Runtime.CompilerServices.Nullable(2)] @@ -10809,7 +10809,7 @@ The system error is based on the current operating system—that is, `errno` System.IntPtr - + A managed string to be copied. @@ -11093,7 +11093,7 @@ The system error is based on the current operating system—that is, `errno` System.IntPtr - + A managed string to be copied. diff --git a/xml/System.Runtime.InteropServices/MarshalDirectiveException.xml b/xml/System.Runtime.InteropServices/MarshalDirectiveException.xml index 36f70bd3589..44bb528e57c 100644 --- a/xml/System.Runtime.InteropServices/MarshalDirectiveException.xml +++ b/xml/System.Runtime.InteropServices/MarshalDirectiveException.xml @@ -73,11 +73,11 @@ The exception that is thrown by the marshaler when it encounters a it does not support. - @@ -137,16 +137,16 @@ Initializes a new instance of the class with default properties. - |`null`.| -||A localized error message string.| - + |`null`.| +||A localized error message string.| + ]]> @@ -195,16 +195,16 @@ The error message that specifies the reason for the exception. Initializes a new instance of the class with a specified error message. - |`null`.| -||`message`| - + |`null`.| +||`message`| + ]]> @@ -259,19 +259,19 @@ - - + + The object that holds the serialized object data. The contextual information about the source or destination. Initializes a new instance of the class from serialization data. - @@ -324,18 +324,18 @@ The exception that is the cause of the current exception. If the parameter is not , the current exception is raised in a block that handles the inner exception. Initializes a new instance of the class with a specified error message and a reference to the inner exception that is the cause of this exception. - property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||The inner exception reference.| -||The error message string.| - + property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||The inner exception reference.| +||The error message string.| + ]]> diff --git a/xml/System.Runtime.InteropServices/RegistrationServices.xml b/xml/System.Runtime.InteropServices/RegistrationServices.xml index 474f263d634..adc91b7dc5a 100644 --- a/xml/System.Runtime.InteropServices/RegistrationServices.xml +++ b/xml/System.Runtime.InteropServices/RegistrationServices.xml @@ -36,23 +36,23 @@ Provides a set of services for registering and unregistering managed assemblies for use from COM. - class to add or remove COM-enabling registry entries for managed assemblies. - - You can use the following methods to assist you in preparing a registration file: - -- - -- - -- - -- - - Although these methods help in gathering information to be used in a registration file, they do not actually produce a registration file. Instead, you can use the [Regasm.exe (Assembly Registration Tool)](/dotnet/framework/tools/regasm-exe-assembly-registration-tool) tool with the `/regfile` option to perform this task. methods cannot export and register a type library. To export and register a type library, you can use the [Regasm.exe (Assembly Registration Tool)](/dotnet/framework/tools/regasm-exe-assembly-registration-tool) tool and the [Tlbexp.exe (Type Library Exporter)](/dotnet/framework/tools/tlbexp-exe-type-library-exporter) tool. - + class to add or remove COM-enabling registry entries for managed assemblies. + + You can use the following methods to assist you in preparing a registration file: + +- + +- + +- + +- + + Although these methods help in gathering information to be used in a registration file, they do not actually produce a registration file. Instead, you can use the [Regasm.exe (Assembly Registration Tool)](/dotnet/framework/tools/regasm-exe-assembly-registration-tool) tool with the `/regfile` option to perform this task. methods cannot export and register a type library. To export and register a type library, you can use the [Regasm.exe (Assembly Registration Tool)](/dotnet/framework/tools/regasm-exe-assembly-registration-tool) tool and the [Tlbexp.exe (Type Library Exporter)](/dotnet/framework/tools/tlbexp-exe-type-library-exporter) tool. + ]]> Regasm.exe (Assembly Registration Tool) @@ -214,29 +214,29 @@ if contains types that were successfully registered; otherwise if the assembly contains no eligible types. - to get an assembly. - + to get an assembly. + ]]> is . - The full name of is . - - -or- - - A method marked with is not . - - -or- - - There is more than one method marked with at a given level of the hierarchy. - - -or- - + The full name of is . + + -or- + + A method marked with is not . + + -or- + + There is more than one method marked with at a given level of the hierarchy. + + -or- + The signature of the method marked with is not valid. A user-defined custom registration function (marked with the attribute) throws an exception. @@ -249,11 +249,11 @@ Registers the specified type with COM. - @@ -293,15 +293,15 @@ The used to register the specified type. Registers the specified type with COM using the specified GUID. - method is not atomic and can cause unpredictable results when used in a multithreaded context. - - In version 2.0 and later, use the method to unregister a type in COM. - - Note that using platform invoke to call the unmanaged `CoRegisterClassObject` and `CoDisconnectObject` methods for registration and unregistration of COM objects is not supported. - + method is not atomic and can cause unpredictable results when used in a multithreaded context. + + In version 2.0 and later, use the method to unregister a type in COM. + + Note that using platform invoke to call the unmanaged `CoRegisterClassObject` and `CoDisconnectObject` methods for registration and unregistration of COM objects is not supported. + ]]> The parameter is . @@ -336,9 +336,9 @@ System.Int32 - - - + + + The object to register for use from COM. @@ -347,15 +347,15 @@ Registers the specified type with COM using the specified execution context and connection type. An integer that represents a cookie value. - method is not atomic and can cause unpredictable results when used in a multithreaded context. - - In the .NET Framework version 2.0 and later, use the method to unregister a type in COM. - - Note that using platform invoke to call the unmanaged `CoRegisterClassObject` and `CoDisconnectObject` methods for registration and unregistration of COM objects is not supported. - + method is not atomic and can cause unpredictable results when used in a multithreaded context. + + In the .NET Framework version 2.0 and later, use the method to unregister a type in COM. + + Note that using platform invoke to call the unmanaged `CoRegisterClassObject` and `CoDisconnectObject` methods for registration and unregistration of COM objects is not supported. + ]]> The parameter is . @@ -471,27 +471,27 @@ if contains types that were successfully unregistered; otherwise if the assembly contains no eligible types. - . This method also calls any unregistration functions found in the assembly. - + . This method also calls any unregistration functions found in the assembly. + ]]> is . - The full name of is . - - -or- - - A method marked with is not . - - -or- - - There is more than one method marked with at a given level of the hierarchy. - - -or- - + The full name of is . + + -or- + + A method marked with is not . + + -or- + + There is more than one method marked with at a given level of the hierarchy. + + -or- + The signature of the method marked with is not valid. A user-defined custom unregistration function (marked with the attribute) throws an exception. @@ -523,17 +523,17 @@ System.Void - + The cookie value returned by a previous call to the method overload. Removes references to a type registered with the method. - diff --git a/xml/System.Runtime.InteropServices/SEHException.xml b/xml/System.Runtime.InteropServices/SEHException.xml index 56ae9570789..a67dd9762c6 100644 --- a/xml/System.Runtime.InteropServices/SEHException.xml +++ b/xml/System.Runtime.InteropServices/SEHException.xml @@ -73,49 +73,49 @@ Represents structured exception handling (SEH) errors. - class handles SEH errors that are thrown from unmanaged code, but that have not been mapped to another .NET Framework exception. The class also corresponds to the `HRESULT` `E_FAIL` (0x80004005). - - The .NET Framework often encounters unmanaged SEH exceptions that are automatically mapped to managed equivalents. There are two common unmanaged SEH exceptions: - -- `STATUS_NO_MEMORY` exceptions are automatically mapped to the class. - -- `STATUS_ACCESS_VIOLATION` exceptions are automatically mapped as follows: - - - If `legacyNullReferencePolicy` is applied, all access violations are mapped to the class. - - - If the address at which the read/write was attempted is not in JIT-compiled code, the exception is mapped to the class. - - - If the address at which the read/write was attempted is in JIT-compiled code, but it is not in the OS Null partition area, the exception is mapped to the class. - - - If there is no `legacyNullReferencePolicy`, and the address at which the read/write was attempted is in JIT-compiled code and in the OS Null partition area, the exception is mapped to the class. - - Any SEH exception that is not automatically mapped to a specific exception is mapped to the class by default. - - Note that the class does not cause unmanaged C++ exception destructors to be called. To ensure that unmanaged C++ exception destructors are called, use the following syntax in the `catch` block. - -```vb -Catch - ' Handle catch here. -End Try -``` - -```csharp -catch -{ - // Handle catch here. -} -``` - -```cpp -catch(…) -{ - // Handle catch here. -} -``` - + class handles SEH errors that are thrown from unmanaged code, but that have not been mapped to another .NET Framework exception. The class also corresponds to the `HRESULT` `E_FAIL` (0x80004005). + + The .NET Framework often encounters unmanaged SEH exceptions that are automatically mapped to managed equivalents. There are two common unmanaged SEH exceptions: + +- `STATUS_NO_MEMORY` exceptions are automatically mapped to the class. + +- `STATUS_ACCESS_VIOLATION` exceptions are automatically mapped as follows: + + - If `legacyNullReferencePolicy` is applied, all access violations are mapped to the class. + + - If the address at which the read/write was attempted is not in JIT-compiled code, the exception is mapped to the class. + + - If the address at which the read/write was attempted is in JIT-compiled code, but it is not in the OS Null partition area, the exception is mapped to the class. + + - If there is no `legacyNullReferencePolicy`, and the address at which the read/write was attempted is in JIT-compiled code and in the OS Null partition area, the exception is mapped to the class. + + Any SEH exception that is not automatically mapped to a specific exception is mapped to the class by default. + + Note that the class does not cause unmanaged C++ exception destructors to be called. To ensure that unmanaged C++ exception destructors are called, use the following syntax in the `catch` block. + +```vb +Catch + ' Handle catch here. +End Try +``` + +```csharp +catch +{ + // Handle catch here. +} +``` + +```cpp +catch(…) +{ + // Handle catch here. +} +``` + ]]> @@ -177,16 +177,16 @@ catch(…) Initializes a new instance of the class. - class inherits from the class. This constructor sets the properties of the object to the values in the following table. - -|Property|Value| -|--------------|-----------| -||A null reference (`Nothing` in Visual Basic).| -||A localized error message string.| - + class inherits from the class. This constructor sets the properties of the object to the values in the following table. + +|Property|Value| +|--------------|-----------| +||A null reference (`Nothing` in Visual Basic).| +||A localized error message string.| + ]]> @@ -235,16 +235,16 @@ catch(…) The message that indicates the reason for the exception. Initializes a new instance of the class with a specified message. - inherits from . This constructor sets the properties of the object as shown in the following table. - -|Property|Value| -|--------------|-----------| -||A null reference (`Nothing` in Visual Basic).| -||`message`.| - + inherits from . This constructor sets the properties of the object as shown in the following table. + +|Property|Value| +|--------------|-----------| +||A null reference (`Nothing` in Visual Basic).| +||`message`.| + ]]> @@ -299,21 +299,21 @@ catch(…) - - + + The object that holds the serialized object data. The contextual information about the source or destination. Initializes a new instance of the class from serialization data. - namespace. - - inherits from . - + namespace. + + inherits from . + ]]> @@ -366,18 +366,18 @@ catch(…) The exception that is the cause of the current exception. If the parameter is not , the current exception is raised in a block that handles the inner exception. Initializes a new instance of the class with a specified error message and a reference to the inner exception that is the cause of this exception. - property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||The inner exception reference.| -||The error message string.| - + property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||The inner exception reference.| +||The error message string.| + ]]> @@ -428,11 +428,11 @@ catch(…) Indicates whether the exception can be recovered from, and whether the code can continue from the point at which the exception was thrown. Always , because resumable exceptions are not implemented. - returns `true`, then a filtered exception handler can correct the problem that caused the exception, and the code will continue from the point at which the exception was thrown. - + returns `true`, then a filtered exception handler can correct the problem that caused the exception, and the code will continue from the point at which the exception was thrown. + ]]> diff --git a/xml/System.Runtime.InteropServices/SafeArrayRankMismatchException.xml b/xml/System.Runtime.InteropServices/SafeArrayRankMismatchException.xml index 65fdb5a7d59..d2cdc49078d 100644 --- a/xml/System.Runtime.InteropServices/SafeArrayRankMismatchException.xml +++ b/xml/System.Runtime.InteropServices/SafeArrayRankMismatchException.xml @@ -73,13 +73,13 @@ The exception thrown when the rank of an incoming does not match the rank specified in the managed signature. - @@ -139,16 +139,16 @@ Initializes a new instance of the class with default values. - . This constructor sets the properties of the object as shown in the following table. - -|Property|Value| -|--------------|-----------| -||`null`.| -||A localized error message string.| - + . This constructor sets the properties of the object as shown in the following table. + +|Property|Value| +|--------------|-----------| +||`null`.| +||A localized error message string.| + ]]> @@ -197,16 +197,16 @@ The message that indicates the reason for the exception. Initializes a new instance of the class with the specified message. - . This constructor sets the properties of the object as shown in the following table. - -|Property|Value| -|--------------|-----------| -||`null`.| -||`message`| - + . This constructor sets the properties of the object as shown in the following table. + +|Property|Value| +|--------------|-----------| +||`null`.| +||`message`| + ]]> @@ -261,21 +261,21 @@ - - + + The object that holds the serialized object data. The contextual information about the source or destination. Initializes a new instance of the class from serialization data. - . - - `SafeArrayRankMismatchException` inherits from . - + . + + `SafeArrayRankMismatchException` inherits from . + ]]> @@ -328,18 +328,18 @@ The exception that is the cause of the current exception. If the parameter is not , the current exception is raised in a block that handles the inner exception. Initializes a new instance of the class with a specified error message and a reference to the inner exception that is the cause of this exception. - property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||The inner exception reference.| -||The error message string.| - + property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||The inner exception reference.| +||The error message string.| + ]]> diff --git a/xml/System.Runtime.InteropServices/SafeArrayTypeMismatchException.xml b/xml/System.Runtime.InteropServices/SafeArrayTypeMismatchException.xml index 27fd5e51313..0f093fde56e 100644 --- a/xml/System.Runtime.InteropServices/SafeArrayTypeMismatchException.xml +++ b/xml/System.Runtime.InteropServices/SafeArrayTypeMismatchException.xml @@ -73,11 +73,11 @@ The exception thrown when the type of the incoming does not match the type specified in the managed signature. - @@ -137,16 +137,16 @@ Initializes a new instance of the class with default values. - . This constructor sets the properties of the object as shown in the following table. - -|Property|Value| -|--------------|-----------| -||`null`.| -||A localized error message string.| - + . This constructor sets the properties of the object as shown in the following table. + +|Property|Value| +|--------------|-----------| +||`null`.| +||A localized error message string.| + ]]> @@ -195,16 +195,16 @@ The message that indicates the reason for the exception. Initializes a new instance of the class with the specified message. - . This constructor sets the properties of the object as shown in the following table. - -|Property|Value| -|--------------|-----------| -||`null`.| -||`message`| - + . This constructor sets the properties of the object as shown in the following table. + +|Property|Value| +|--------------|-----------| +||`null`.| +||`message`| + ]]> @@ -259,21 +259,21 @@ - - + + The object that holds the serialized object data. The contextual information about the source or destination. Initializes a new instance of the class from serialization data. - . - - `SafeArrayTypeMismatchException` inherits from . - + . + + `SafeArrayTypeMismatchException` inherits from . + ]]> @@ -326,18 +326,18 @@ The exception that is the cause of the current exception. If the parameter is not , the current exception is raised in a block that handles the inner exception. Initializes a new instance of the class with a specified error message and a reference to the inner exception that is the cause of this exception. - property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||The inner exception reference.| -||The error message string.| - + property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||The inner exception reference.| +||The error message string.| + ]]> diff --git a/xml/System.Runtime.InteropServices/StructLayoutAttribute.xml b/xml/System.Runtime.InteropServices/StructLayoutAttribute.xml index cc473b21011..598cf535434 100644 --- a/xml/System.Runtime.InteropServices/StructLayoutAttribute.xml +++ b/xml/System.Runtime.InteropServices/StructLayoutAttribute.xml @@ -57,24 +57,24 @@ Lets you control the physical layout of the data fields of a class or structure in memory. - attribute to control the unmanaged layout of the type. Use the attribute with to force the members to be laid out sequentially in the order they appear. For blittable types, controls both the layout in managed memory and the layout in unmanaged memory. For non-blittable types, it controls the layout when the class or structure is marshaled to unmanaged code, but does not control the layout in managed memory. Use the attribute with to control the precise position of each data member. This affects both managed and unmanaged layout, for both blittable and non-blittable types. Using requires that you use the attribute to indicate the position of each field within the type. - - C#, Visual Basic, and C++ compilers apply the layout value to structures by default. For classes, you must apply the value explicitly. The [Tlbimp.exe (Type Library Importer)](/dotnet/framework/tools/tlbimp-exe-type-library-importer) also applies the attribute; it always applies the value when it imports a type library. - - - -## Examples - The following example demonstrates a managed declaration of the `GetSystemTime` function and defines `MySystemTime` class with layout. `GetSystemTime` gets the system time and prints to the console. - + attribute to control the unmanaged layout of the type. Use the attribute with to force the members to be laid out sequentially in the order they appear. For blittable types, controls both the layout in managed memory and the layout in unmanaged memory. For non-blittable types, it controls the layout when the class or structure is marshaled to unmanaged code, but does not control the layout in managed memory. Use the attribute with to control the precise position of each data member. This affects both managed and unmanaged layout, for both blittable and non-blittable types. Using requires that you use the attribute to indicate the position of each field within the type. + + C#, Visual Basic, and C++ compilers apply the layout value to structures by default. For classes, you must apply the value explicitly. The [Tlbimp.exe (Type Library Importer)](/dotnet/framework/tools/tlbimp-exe-type-library-importer) also applies the attribute; it always applies the value when it imports a type library. + + + +## Examples + The following example demonstrates a managed declaration of the `GetSystemTime` function and defines `MySystemTime` class with layout. `GetSystemTime` gets the system time and prints to the console. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/StructLayoutAttribute/CPP/structlayoutattribute.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Runtime.InteropServices/StructLayoutAttribute/Overview/structlayoutattribute.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/StructLayoutAttribute/VB/structlayoutattribute.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/StructLayoutAttribute/VB/structlayoutattribute.vb" id="Snippet1"::: + ]]> Tlbimp.exe (Type Library Importer) @@ -122,17 +122,17 @@ 9.0.0.0 - + A 16-bit integer that represents one of the values that specifies how the class or structure should be arranged. Initializes a new instance of the class with the specified enumeration member. - enumeration member. The [Tlbimp.exe (Type Library Importer)](/dotnet/framework/tools/tlbimp-exe-type-library-importer) uses this constructor. - + enumeration member. The [Tlbimp.exe (Type Library Importer)](/dotnet/framework/tools/tlbimp-exe-type-library-importer) uses this constructor. + ]]> @@ -181,11 +181,11 @@ One of the enumeration values that specifies how the class or structure should be arranged. Initializes a new instance of the class with the specified enumeration member. - @@ -232,11 +232,11 @@ Indicates whether string data fields within the class should be marshaled as or by default. - or , all string arguments are converted to Unicode characters (`LPWSTR`) before they are passed to the unmanaged implementation. If the field is set to , the strings are converted to ANSI strings (`LPSTR`). - + ]]> @@ -283,58 +283,58 @@ Controls the alignment of data fields of a class or structure in memory. - field controls the alignment of a type's fields in memory. It affects . By default, the value is 0, indicating the default packing size for the current platform. The value of must be 0, 1, 2, 4, 8, 16, 32, 64, or 128: - - The fields of a type instance are aligned by using the following rules: - -- The alignment of the type is the size of its largest element (1, 2, 4, 8, etc., bytes) or the specified packing size, whichever is smaller. - -- Each field must align with fields of its own size (1, 2, 4, 8, etc., bytes) or the alignment of the type, whichever is smaller. Because the default alignment of the type is the size of its largest element, which is greater than or equal to all other field lengths, this usually means that fields are aligned by their size. For example, even if the largest field in a type is a 64-bit (8-byte) integer or the Pack field is set to 8, fields align on 1-byte boundaries, fields align on 2-byte boundaries, and fields align on 4-byte boundaries. - -- Padding is added between fields to satisfy the alignment requirements. - - For example, consider the following structure, which consists of two fields and one field, when it is used with various values for the field. - - :::code language="csharp" source="~/snippets/csharp/System.Runtime.InteropServices/StructLayoutAttribute/Pack/packex0.cs" id="Snippet1"::: - + field controls the alignment of a type's fields in memory. It affects . By default, the value is 0, indicating the default packing size for the current platform. The value of must be 0, 1, 2, 4, 8, 16, 32, 64, or 128: + + The fields of a type instance are aligned by using the following rules: + +- The alignment of the type is the size of its largest element (1, 2, 4, 8, etc., bytes) or the specified packing size, whichever is smaller. + +- Each field must align with fields of its own size (1, 2, 4, 8, etc., bytes) or the alignment of the type, whichever is smaller. Because the default alignment of the type is the size of its largest element, which is greater than or equal to all other field lengths, this usually means that fields are aligned by their size. For example, even if the largest field in a type is a 64-bit (8-byte) integer or the Pack field is set to 8, fields align on 1-byte boundaries, fields align on 2-byte boundaries, and fields align on 4-byte boundaries. + +- Padding is added between fields to satisfy the alignment requirements. + + For example, consider the following structure, which consists of two fields and one field, when it is used with various values for the field. + + :::code language="csharp" source="~/snippets/csharp/System.Runtime.InteropServices/StructLayoutAttribute/Pack/packex0.cs" id="Snippet1"::: + > [!IMPORTANT] -> To successfully compile the C# examples, you must specify the `/unsafe` compiler switch. - - If you specify the default packing size, the size of the structure is 8 bytes. The two bytes occupy the first two bytes of memory, because bytes must align on one-byte boundaries. Because the default alignment of the type is 4 bytes, which is the size of its largest fields, `i3`, there are two bytes of padding followed by the integer field. - - :::code language="csharp" source="~/snippets/csharp/System.Runtime.InteropServices/StructLayoutAttribute/Pack/packex1.cs" id="Snippet2"::: - - If is set to 2, the size of the structure is 6 bytes. As before, the two bytes occupy the first two bytes of memory. Because fields now align on 2-byte boundaries, there is no padding between the second byte and the integer. - - :::code language="csharp" source="~/snippets/csharp/System.Runtime.InteropServices/StructLayoutAttribute/Pack/packex2.cs" id="Snippet3"::: - - If is set to 4, the size of the structure is the same as in the default case, where the type's alignment was defined by the size of its largest field, `i3`, which is 4. - - :::code language="csharp" source="~/snippets/csharp/System.Runtime.InteropServices/StructLayoutAttribute/Pack/packex3.cs" id="Snippet4"::: - - If is set to 8, the size of the structure is the still same as in the default case, because the `i3` field aligns on a 4-byte boundary, which is smaller than the 8-byte boundary specified by the Pack field. - - :::code language="csharp" source="~/snippets/csharp/System.Runtime.InteropServices/StructLayoutAttribute/Pack/packex4.cs" id="Snippet5"::: - - To take another example, consider the following structure, which consists of two byte fields, one 32-bit signed integer field, one single-element byte array, and a decimal value. With the default packing size, the size of the structure is 28 bytes. The two bytes occupy the first two bytes of memory, followed by two bytes of padding, followed by the integer. Next is the one-byte array, followed by three bytes of padding. Finally, the field, d5, aligns on a 4-byte boundary because a decimal value consists of four fields, so its alignment is based on the size of the largest of its fields rather than on the size of the structure as a whole. - - :::code language="csharp" source="~/snippets/csharp/System.Runtime.InteropServices/StructLayoutAttribute/Pack/packex5.cs" id="Snippet6"::: - - If is set to 2, the size of the structure is 24 bytes. In comparison with the default alignment, the two bytes of padding between the two bytes and the integer have been removed because the type's alignment is now 4 rather than 2. And the three bytes of padding after `a4` have been replaced by one byte of padding, since `d5` now aligns on a 2-byte boundary rather than a 4-byte boundary. - - :::code language="csharp" source="~/snippets/csharp/System.Runtime.InteropServices/StructLayoutAttribute/Pack/packex6.cs" id="Snippet7"::: - - If is set to 8, the size of the structure is the same as in the default case, because all the alignment requirements in this structure are less than 8. - - :::code language="csharp" source="~/snippets/csharp/System.Runtime.InteropServices/StructLayoutAttribute/Pack/packex7.cs" id="Snippet8"::: - - The field is frequently used when structures are exported during disk and network write operations. The field is also frequently used during platform invoke and interop operations. - - Occasionally, the field is used to reduce memory requirements by producing a tighter packing size. However, this usage requires careful consideration of actual hardware constraints, and may actually degrade performance. - +> To successfully compile the C# examples, you must specify the `/unsafe` compiler switch. + + If you specify the default packing size, the size of the structure is 8 bytes. The two bytes occupy the first two bytes of memory, because bytes must align on one-byte boundaries. Because the default alignment of the type is 4 bytes, which is the size of its largest fields, `i3`, there are two bytes of padding followed by the integer field. + + :::code language="csharp" source="~/snippets/csharp/System.Runtime.InteropServices/StructLayoutAttribute/Pack/packex1.cs" id="Snippet2"::: + + If is set to 2, the size of the structure is 6 bytes. As before, the two bytes occupy the first two bytes of memory. Because fields now align on 2-byte boundaries, there is no padding between the second byte and the integer. + + :::code language="csharp" source="~/snippets/csharp/System.Runtime.InteropServices/StructLayoutAttribute/Pack/packex2.cs" id="Snippet3"::: + + If is set to 4, the size of the structure is the same as in the default case, where the type's alignment was defined by the size of its largest field, `i3`, which is 4. + + :::code language="csharp" source="~/snippets/csharp/System.Runtime.InteropServices/StructLayoutAttribute/Pack/packex3.cs" id="Snippet4"::: + + If is set to 8, the size of the structure is the still same as in the default case, because the `i3` field aligns on a 4-byte boundary, which is smaller than the 8-byte boundary specified by the Pack field. + + :::code language="csharp" source="~/snippets/csharp/System.Runtime.InteropServices/StructLayoutAttribute/Pack/packex4.cs" id="Snippet5"::: + + To take another example, consider the following structure, which consists of two byte fields, one 32-bit signed integer field, one single-element byte array, and a decimal value. With the default packing size, the size of the structure is 28 bytes. The two bytes occupy the first two bytes of memory, followed by two bytes of padding, followed by the integer. Next is the one-byte array, followed by three bytes of padding. Finally, the field, d5, aligns on a 4-byte boundary because a decimal value consists of four fields, so its alignment is based on the size of the largest of its fields rather than on the size of the structure as a whole. + + :::code language="csharp" source="~/snippets/csharp/System.Runtime.InteropServices/StructLayoutAttribute/Pack/packex5.cs" id="Snippet6"::: + + If is set to 2, the size of the structure is 24 bytes. In comparison with the default alignment, the two bytes of padding between the two bytes and the integer have been removed because the type's alignment is now 4 rather than 2. And the three bytes of padding after `a4` have been replaced by one byte of padding, since `d5` now aligns on a 2-byte boundary rather than a 4-byte boundary. + + :::code language="csharp" source="~/snippets/csharp/System.Runtime.InteropServices/StructLayoutAttribute/Pack/packex6.cs" id="Snippet7"::: + + If is set to 8, the size of the structure is the same as in the default case, because all the alignment requirements in this structure are less than 8. + + :::code language="csharp" source="~/snippets/csharp/System.Runtime.InteropServices/StructLayoutAttribute/Pack/packex7.cs" id="Snippet8"::: + + The field is frequently used when structures are exported during disk and network write operations. The field is also frequently used during platform invoke and interop operations. + + Occasionally, the field is used to reduce memory requirements by producing a tighter packing size. However, this usage requires careful consideration of actual hardware constraints, and may actually degrade performance. + ]]> @@ -380,11 +380,11 @@ Indicates the absolute size of the class or structure. - diff --git a/xml/System.Runtime.Remoting.Channels/ChannelServices.xml b/xml/System.Runtime.Remoting.Channels/ChannelServices.xml index 699417d20b8..d63943cea2b 100644 --- a/xml/System.Runtime.Remoting.Channels/ChannelServices.xml +++ b/xml/System.Runtime.Remoting.Channels/ChannelServices.xml @@ -381,8 +381,8 @@ System.Void - - + + The channel to register. diff --git a/xml/System.Runtime.Remoting.Messaging/CallContext.xml b/xml/System.Runtime.Remoting.Messaging/CallContext.xml index ddf665e6491..184afedde40 100644 --- a/xml/System.Runtime.Remoting.Messaging/CallContext.xml +++ b/xml/System.Runtime.Remoting.Messaging/CallContext.xml @@ -33,28 +33,28 @@ Provides a set of properties that are carried with the execution code path. This class cannot be inherited. - is a specialized collection object similar to a Thread Local Storage for method calls and provides data slots that are unique to each logical thread of execution. The slots are not shared across call contexts on other logical threads. Objects can be added to the as it travels down and back up the execution code path, and examined by various objects along the path. - - When a remote method call is made to an object in another , the class generates a instance that travels along with the remote call. Only objects that expose the interface and are stored in the are propagated outside the in a . Objects that do not support this interface are not transmitted in instances with remote method calls. - + is a specialized collection object similar to a Thread Local Storage for method calls and provides data slots that are unique to each logical thread of execution. The slots are not shared across call contexts on other logical threads. Objects can be added to the as it travels down and back up the execution code path, and examined by various objects along the path. + + When a remote method call is made to an object in another , the class generates a instance that travels along with the remote call. Only objects that expose the interface and are stored in the are propagated outside the in a . Objects that do not support this interface are not transmitted in instances with remote method calls. + > [!NOTE] -> All methods in are static and operate on the call context in the current . - +> All methods in are static and operate on the call context in the current . + > [!NOTE] -> This class makes a link demand. A `SecurityException` is thrown if the immediate caller does not have infrastructure permission. See [Link Demands](/dotnet/framework/misc/link-demands) for more information. - - - -## Examples - The following code example demonstrates the use of the class to transmit [Principal and Identity Objects](/dotnet/standard/security/principal-and-identity-objects) to a remote location for identification. To view the code for the `LogicalCallContextData` class used in this sample, see the example for the interface. To view the code for the `HelloServiceClass` class used in this sample, see the example for the method. To view the code for the server class used in this sample, see the example for the class. - +> This class makes a link demand. A `SecurityException` is thrown if the immediate caller does not have infrastructure permission. See [Link Demands](/dotnet/framework/misc/link-demands) for more information. + + + +## Examples + The following code example demonstrates the use of the class to transmit [Principal and Identity Objects](/dotnet/standard/security/principal-and-identity-objects) to a remote location for identification. To view the code for the `LogicalCallContextData` class used in this sample, see the example for the interface. To view the code for the `HelloServiceClass` class used in this sample, see the example for the method. To view the code for the server class used in this sample, see the example for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/CallContext/CPP/client.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Messaging/CallContext/Overview/client.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/CallContext/VB/client.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/CallContext/VB/client.vb" id="Snippet1"::: + ]]> @@ -90,15 +90,15 @@ The name of the data slot to empty. Empties a data slot with the specified name. - The immediate caller does not have infrastructure permission. @@ -135,15 +135,15 @@ Retrieves an object with the specified name from the . The object in the call context associated with the specified name. - method to transmit [Principal and Identity Objects](/dotnet/standard/security/principal-and-identity-objects) to a remote location for identification. To view the code for the `LogicalCallContextData` class used in this sample, see the example for the interface. To view the code for the client class used in the sample, see the example for the class. To view the code for the server class used in this sample, see the example for the class. - + method to transmit [Principal and Identity Objects](/dotnet/standard/security/principal-and-identity-objects) to a remote location for identification. To view the code for the `LogicalCallContextData` class used in this sample, see the example for the interface. To view the code for the client class used in the sample, see the example for the class. To view the code for the server class used in this sample, see the example for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/CallContext/CPP/service.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Messaging/CallContext/Overview/service.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/CallContext/VB/service.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/CallContext/VB/service.vb" id="Snippet3"::: + ]]> The immediate caller does not have infrastructure permission. @@ -177,15 +177,15 @@ Returns the headers that are sent along with the method call. The headers that are sent along with the method call. - The immediate caller does not have infrastructure permission. @@ -247,7 +247,7 @@ System.Object - + The name of the item in the logical call context. @@ -280,8 +280,8 @@ System.Void - - + + The name with which to associate the new item in the logical call context. @@ -323,15 +323,15 @@ The object to store in the call context. Stores a given object and associates it with the specified name. - method to transmit [Principal and Identity Objects](/dotnet/standard/security/principal-and-identity-objects) to a remote location for identification. To view the code for the `LogicalCallContextData` class used in this sample, see the example for the interface. To view the code for the `HelloServiceClass` class used in this sample, see the example for the method. To view the code for the server class used in this sample, see the example for the class. - + method to transmit [Principal and Identity Objects](/dotnet/standard/security/principal-and-identity-objects) to a remote location for identification. To view the code for the `LogicalCallContextData` class used in this sample, see the example for the interface. To view the code for the `HelloServiceClass` class used in this sample, see the example for the method. To view the code for the server class used in this sample, see the example for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/CallContext/CPP/client.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Messaging/CallContext/Overview/client.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/CallContext/VB/client.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/CallContext/VB/client.vb" id="Snippet1"::: + ]]> The immediate caller does not have infrastructure permission. @@ -367,15 +367,15 @@ A array of the headers that are to be sent along with the method call. Sets the headers that are sent along with the method call. - The immediate caller does not have infrastructure permission. diff --git a/xml/System.Runtime.Remoting/RemotingConfiguration.xml b/xml/System.Runtime.Remoting/RemotingConfiguration.xml index bca3ee84e85..3b74e800816 100644 --- a/xml/System.Runtime.Remoting/RemotingConfiguration.xml +++ b/xml/System.Runtime.Remoting/RemotingConfiguration.xml @@ -202,8 +202,8 @@ System.Void - - + + The name of the remoting configuration file. Can be . diff --git a/xml/System.Runtime.Serialization.Formatters.Binary/BinaryFormatter.xml b/xml/System.Runtime.Serialization.Formatters.Binary/BinaryFormatter.xml index 9540cef095d..8e73ff90f32 100644 --- a/xml/System.Runtime.Serialization.Formatters.Binary/BinaryFormatter.xml +++ b/xml/System.Runtime.Serialization.Formatters.Binary/BinaryFormatter.xml @@ -489,8 +489,8 @@ The property may contain more information abou System.Object - - + + The stream from which to deserialize the object graph. @@ -549,9 +549,9 @@ For deserialization to succeed, the current position in the stream must be at th System.Object - - - + + + The stream from which to deserialize the object graph. @@ -757,9 +757,9 @@ For deserialization to succeed, the current position in the stream must be at th System.Void - - - + + + The stream to which the object is to be serialized. @@ -916,8 +916,8 @@ The surrogate selector is used by to generate System.Object - - + + The stream from which to deserialize the object graph. @@ -978,9 +978,9 @@ For successful deserialization, the current position in the stream must be at th System.Object - - - + + + The stream from which to deserialize the object graph. diff --git a/xml/System.Runtime.Serialization.Json/DataContractJsonSerializer.xml b/xml/System.Runtime.Serialization.Json/DataContractJsonSerializer.xml index e81627a1aa1..84bd7e33be4 100644 --- a/xml/System.Runtime.Serialization.Json/DataContractJsonSerializer.xml +++ b/xml/System.Runtime.Serialization.Json/DataContractJsonSerializer.xml @@ -314,8 +314,8 @@ - - + + [System.Runtime.CompilerServices.Nullable(2)] @@ -375,8 +375,8 @@ - - + + [System.Runtime.CompilerServices.Nullable(2)] @@ -436,8 +436,8 @@ - - + + [System.Runtime.CompilerServices.Nullable(2)] @@ -445,7 +445,7 @@ - + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 2, 1 })] @@ -506,8 +506,8 @@ - - + + [System.Runtime.CompilerServices.Nullable(2)] @@ -515,7 +515,7 @@ - + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 2, 1 })] @@ -556,12 +556,12 @@ netstandard - - - - - - + + + + + + The type of the instances that is serialized or deserialized. @@ -600,13 +600,13 @@ netstandard - - - - - - - + + + + + + + The type of the instances that is serialized or deserialized. @@ -646,13 +646,13 @@ netstandard - - - - - - - + + + + + + + The type of the instances that are serialized or deserialized. @@ -947,7 +947,7 @@ System.Boolean - + The used to read the XML stream mapped from JSON. @@ -1012,7 +1012,7 @@ System.Boolean - + The used to read the XML stream. @@ -1243,7 +1243,7 @@ System.Object - + An used to read the XML document mapped from JSON. @@ -1299,7 +1299,7 @@ System.Object - + An used to read the XML document mapped from JSON. @@ -1355,8 +1355,8 @@ System.Object - - + + An used to read the XML document mapped from JSON. @@ -1414,8 +1414,8 @@ System.Object - - + + An used to read the XML document mapped from JSON. @@ -1610,7 +1610,7 @@ System.Void - + An used to write the XML document to map to JSON. @@ -1671,7 +1671,7 @@ System.Void - + An used to write the XML document mapped to JSON. @@ -1810,8 +1810,8 @@ System.Void - - + + [System.Runtime.CompilerServices.Nullable(2)] @@ -1877,8 +1877,8 @@ System.Void - - + + [System.Runtime.CompilerServices.Nullable(2)] @@ -1955,8 +1955,8 @@ System.Void - - + + [System.Runtime.CompilerServices.Nullable(2)] @@ -2022,8 +2022,8 @@ System.Void - - + + [System.Runtime.CompilerServices.Nullable(2)] @@ -2100,8 +2100,8 @@ System.Void - - + + [System.Runtime.CompilerServices.Nullable(2)] @@ -2164,8 +2164,8 @@ System.Void - - + + [System.Runtime.CompilerServices.Nullable(2)] diff --git a/xml/System.Runtime.Serialization/DataContractSerializer.xml b/xml/System.Runtime.Serialization/DataContractSerializer.xml index 5ba5e6d5183..2997bc984b6 100644 --- a/xml/System.Runtime.Serialization/DataContractSerializer.xml +++ b/xml/System.Runtime.Serialization/DataContractSerializer.xml @@ -502,12 +502,12 @@ netstandard - - - - - - + + + + + + The type of the instances that are serialized or deserialized. @@ -559,13 +559,13 @@ netstandard - - - - - - - + + + + + + + The type of the instances that are serialized or deserialized. @@ -610,14 +610,14 @@ netstandard - - - - - - - - + + + + + + + + The type of the instances that are serialized or deserialized. @@ -672,14 +672,14 @@ netstandard - - - - - - - - + + + + + + + + The type of the instances that are serialized or deserialized. @@ -732,15 +732,15 @@ netstandard - - - - - - - - - + + + + + + + + + The type of the instances that are serialized or deserialized. @@ -777,15 +777,15 @@ netstandard - - - - - - - - - + + + + + + + + + The type of the instances that are serialized or deserialized. @@ -1482,7 +1482,7 @@ OperationDescription operation = host.Description.Endpoints[0].Contract.Operatio System.Object - + [System.Runtime.CompilerServices.Nullable(1)] @@ -1490,8 +1490,8 @@ OperationDescription operation = host.Description.Endpoints[0].Contract.Operatio - - + + The XML reader used to read the content. @@ -1800,7 +1800,7 @@ OperationDescription operation = host.Description.Endpoints[0].Contract.Operatio System.Void - + [System.Runtime.CompilerServices.Nullable(1)] @@ -1808,8 +1808,8 @@ OperationDescription operation = host.Description.Endpoints[0].Contract.Operatio - - + + An XmlDictionaryWriter used to write the content to the XML document or stream. diff --git a/xml/System.Runtime.Serialization/InvalidDataContractException.xml b/xml/System.Runtime.Serialization/InvalidDataContractException.xml index 3e97c9cc4f7..e163c3e1153 100644 --- a/xml/System.Runtime.Serialization/InvalidDataContractException.xml +++ b/xml/System.Runtime.Serialization/InvalidDataContractException.xml @@ -72,19 +72,19 @@ The exception that is thrown when the or encounters an invalid data contract during serialization and deserialization. - or detects that the type of the instance being serialized or deserialized is invalid. An instance of this type will also be thrown if an invalid type is passed to the schema import or export engine. - - - -## Examples - The following example shows a service contract, `ICalculator`, that includes two methods, `Add` and `MoreData`. The `MoreData` method returns an instance of the `ExtraData` class, which is also declared in the code. When the implemented interface `Calculator` runs, an `InvalidDataContractException` will be thrown because the `ExtraData` class does not have the applied to it. - + or detects that the type of the instance being serialized or deserialized is invalid. An instance of this type will also be thrown if an invalid type is passed to the schema import or export engine. + + + +## Examples + The following example shows a service contract, `ICalculator`, that includes two methods, `Add` and `MoreData`. The `MoreData` method returns an instance of the `ExtraData` class, which is also declared in the code. When the implemented interface `Calculator` runs, an `InvalidDataContractException` will be thrown because the `ExtraData` class does not have the applied to it. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/invaliddatacontractexception/cs/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/invaliddatacontractexception/vb/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/invaliddatacontractexception/vb/source.vb" id="Snippet1"::: + ]]> @@ -234,19 +234,19 @@ - - + + A that contains data needed to serialize and deserialize an object. A that specifies user context during serialization and deserialization. Initializes a new instance of the class with the specified and . - namespace. - + namespace. + ]]> diff --git a/xml/System.Runtime.Serialization/SerializationException.xml b/xml/System.Runtime.Serialization/SerializationException.xml index 132379fbd22..3c18884f3c2 100644 --- a/xml/System.Runtime.Serialization/SerializationException.xml +++ b/xml/System.Runtime.Serialization/SerializationException.xml @@ -81,15 +81,15 @@ The exception thrown when an error occurs during serialization or deserialization. - uses the `HRESULT` COR_E_SERIALIZATION with the value 0x8013150C. - - uses the default implementation, which supports reference equality. - + uses the `HRESULT` COR_E_SERIALIZATION with the value 0x8013150C. + + uses the default implementation, which supports reference equality. + For a list of initial property values for an instance of , see the constructors. - + ]]> @@ -144,16 +144,16 @@ Initializes a new instance of the class with default properties. - inherits from the class. The following table shows initial property values for an instance of initialized with the current constructor. - -|Property|Condition| -|--------------|---------------| -||`null`| -||Localized error message for .| - + inherits from the class. The following table shows initial property values for an instance of initialized with the current constructor. + +|Property|Condition| +|--------------|---------------| +||`null`| +||Localized error message for .| + ]]> @@ -202,16 +202,16 @@ Indicates the reason why the exception occurred. Initializes a new instance of the class with a specified message. - inherits from the class. The following table shows initial property values for an instance of initialized with the current constructor. - -|Property|Condition| -|--------------|---------------| -||`null`| -||The `message` string.| - + inherits from the class. The following table shows initial property values for an instance of initialized with the current constructor. + +|Property|Condition| +|--------------|---------------| +||`null`| +||The `message` string.| + ]]> @@ -269,19 +269,19 @@ - - + + The serialization information object holding the serialized object data in the name-value form. The contextual information about the source or destination of the exception. Initializes a new instance of the class from serialized data. - The parameter is . @@ -333,18 +333,18 @@ The exception that is the cause of the current exception. If the parameter is not , the current exception is raised in a block that handles the inner exception. Initializes a new instance of the class with a specified error message and a reference to the inner exception that is the cause of this exception. - property. The property returns the same value that is passed into the constructor or `null` if the property does not supply the inner exception value to the constructor. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||The inner exception reference.| -||The error message string.| - + property. The property returns the same value that is passed into the constructor or `null` if the property does not supply the inner exception value to the constructor. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||The inner exception reference.| +||The error message string.| + ]]> diff --git a/xml/System.Runtime.Serialization/StreamingContext.xml b/xml/System.Runtime.Serialization/StreamingContext.xml index 2919508b2aa..a04a937ec42 100644 --- a/xml/System.Runtime.Serialization/StreamingContext.xml +++ b/xml/System.Runtime.Serialization/StreamingContext.xml @@ -80,11 +80,11 @@ Describes the source and destination of a given serialized stream, and provides an additional caller-defined context. - can serialize or ignore fields and values based on the information stored in the streaming context. For example, a window handle is still valid if the property is set to `System.Runtime.Serialization.StreamingContextStates.CrossProcess`. - + ]]> @@ -142,7 +142,7 @@ - + A bitwise combination of the values that specify the source or destination context for this . @@ -193,8 +193,8 @@ - - + + A bitwise combination of the values that specify the source or destination context for this . @@ -306,11 +306,11 @@ if the specified object is an instance of and equals the value of the current instance; otherwise, . - and . - + and . + ]]> @@ -408,11 +408,11 @@ Gets the source or destination of the transmitted data. During serialization, the destination of the transmitted data. During deserialization, the source of the data. - is . During deserialization, the state indicates the source of the deserialized stream. - + ]]> diff --git a/xml/System.Security.Claims/ClaimsIdentity.xml b/xml/System.Security.Claims/ClaimsIdentity.xml index cf5292fad22..7d93641ab37 100644 --- a/xml/System.Security.Claims/ClaimsIdentity.xml +++ b/xml/System.Security.Claims/ClaimsIdentity.xml @@ -67,19 +67,19 @@ class is a concrete implementation of a claims-based identity; that is, an identity described by a collection of claims. A claim is a statement about an entity made by an issuer that describes a property, right, or some other quality of that entity. Such an entity is said to be the subject of the claim. A claim is represented by the class. The claims contained in a describe the entity that the corresponding identity represents, and can be used to make authorization and authentication decisions. A claims-based access model has many advantages over more traditional access models that rely exclusively on roles. For example, claims can provide much richer information about the identity they represent and can be evaluated for authorization or authentication in a far more specific manner. - - Beginning with .NET Framework 4.5, Windows Identity Foundation (WIF) and claims-based identity have been fully integrated into the .NET Framework. This means that many classes that represent an identity in the .NET Framework now derive from and describe their properties through a collection of claims. This is different from previous versions of the .NET Framework, in which, these classes implemented the interface directly. The collection of claims that describe the identity can be accessed through the property. The class provides several methods for finding and modifying claims and fully supports language integrated queries (LINQ). In application code, objects are typically accessed through objects; for example, the principal returned by . - +## Remarks + The class is a concrete implementation of a claims-based identity; that is, an identity described by a collection of claims. A claim is a statement about an entity made by an issuer that describes a property, right, or some other quality of that entity. Such an entity is said to be the subject of the claim. A claim is represented by the class. The claims contained in a describe the entity that the corresponding identity represents, and can be used to make authorization and authentication decisions. A claims-based access model has many advantages over more traditional access models that rely exclusively on roles. For example, claims can provide much richer information about the identity they represent and can be evaluated for authorization or authentication in a far more specific manner. + + Beginning with .NET Framework 4.5, Windows Identity Foundation (WIF) and claims-based identity have been fully integrated into the .NET Framework. This means that many classes that represent an identity in the .NET Framework now derive from and describe their properties through a collection of claims. This is different from previous versions of the .NET Framework, in which, these classes implemented the interface directly. The collection of claims that describe the identity can be accessed through the property. The class provides several methods for finding and modifying claims and fully supports language integrated queries (LINQ). In application code, objects are typically accessed through objects; for example, the principal returned by . + > [!NOTE] -> The class has a property as well. In the majority of cases you should access the user's claims through the collection rather than through the collection. You will need to access the claims of an individual only in the cases where the principal contains more than one and you need to evaluate or modify a specific identity. - +> The class has a property as well. In the majority of cases you should access the user's claims through the collection rather than through the collection. You will need to access the claims of an individual only in the cases where the principal contains more than one and you need to evaluate or modify a specific identity. + > [!IMPORTANT] -> To add or remove claims from the collection, a caller must have full trust. - - In the claims-based model, the property and the method are implemented by evaluating the claims contained by an identity. The base implementations in the claims-based model are provided by the property and the method. The and properties enable you to specify a claim type that should be used to evaluate the claims contained by the identity when performing these operations. - +> To add or remove claims from the collection, a caller must have full trust. + + In the claims-based model, the property and the method are implemented by evaluating the claims contained by an identity. The base implementations in the claims-based model are provided by the property and the method. The and properties enable you to specify a claim type that should be used to evaluate the claims contained by the identity when performing these operations. + Delegation scenarios are supported through the and properties. ]]> @@ -137,19 +137,19 @@ class. - -|Property|Value| -|--------------|-----------| -||`null`.| -||`null`.| -||`null`.| -||A empty collection.| -||**Note:** When accessed, the value of the property is returned based on the value of the property.| -||`null`.| -||**Note:** When accessed, the value of the property is returned based on the and the collection.| -||.| +## Remarks + The following table shows initial property values for an instance of the class. + +|Property|Value| +|--------------|-----------| +||`null`.| +||`null`.| +||`null`.| +||A empty collection.| +||**Note:** When accessed, the value of the property is returned based on the value of the property.| +||`null`.| +||**Note:** When accessed, the value of the property is returned based on the and the collection.| +||.| ||.| ]]> @@ -204,19 +204,19 @@ class. - -|Property|Value| -|--------------|-----------| -||`null`.| -||`null`.| -||`null`.| -||Initialized from the `claims` parameter.| -||**Note:** When accessed, the value of the property is returned based on the value of the property.| -||`null`.| -||**Note:** When accessed, the value of the property is returned based on the and the collection.| -||.| +## Remarks + The following table shows initial property values for an instance of the class. + +|Property|Value| +|--------------|-----------| +||`null`.| +||`null`.| +||`null`.| +||Initialized from the `claims` parameter.| +||**Note:** When accessed, the value of the property is returned based on the value of the property.| +||`null`.| +||**Note:** When accessed, the value of the property is returned based on the and the collection.| +||.| ||.| ]]> @@ -263,7 +263,7 @@ . ]]> @@ -316,7 +316,7 @@ - + The serialized data. @@ -366,9 +366,9 @@ class from the provided to the constructor. - +## Remarks + The following table shows the property value assignments for an instance of the class from the provided to the constructor. + | Property | Value | | -------- | ----- | ||If the value of the `other.Actor` property isn't `null`, the `other.Actor` is cloned and assigned; otherwise, `null`.| @@ -433,19 +433,19 @@ class. - -|Property|Value| -|--------------|-----------| -||If `identity` is assignable from , the value of the `identity.Actor` property; otherwise, `null`.| -||The value of the `identity.AuthenticationType` () property is used.| -||If `identity` is assignable from , the value of the `identity.BootStrapContext` property; otherwise, `null`.| -||If `identity` is assignable from , the claims from `identity` are added to the new instance; otherwise, an empty collection.| -||**Note:** When accessed, the value of the property is returned based on the value of the property.| -||If `identity` is assignable from , the value of the `identity.Label` property; otherwise, `null`.| -||If `identity` is not assignable from , is not `null`, and has an property that is not `null`; a name claim is added to the new instance using the value of the property. **Note:** When accessed, the value of the property is returned based on the and the collection.| -||If `identity` is assignable from , the value of the `identity.NameClaimType` property is used; otherwise, is used.| +## Remarks + The following table shows initial property values for an instance of the class. + +|Property|Value| +|--------------|-----------| +||If `identity` is assignable from , the value of the `identity.Actor` property; otherwise, `null`.| +||The value of the `identity.AuthenticationType` () property is used.| +||If `identity` is assignable from , the value of the `identity.BootStrapContext` property; otherwise, `null`.| +||If `identity` is assignable from , the claims from `identity` are added to the new instance; otherwise, an empty collection.| +||**Note:** When accessed, the value of the property is returned based on the value of the property.| +||If `identity` is assignable from , the value of the `identity.Label` property; otherwise, `null`.| +||If `identity` is not assignable from , is not `null`, and has an property that is not `null`; a name claim is added to the new instance using the value of the property. **Note:** When accessed, the value of the property is returned based on the and the collection.| +||If `identity` is assignable from , the value of the `identity.NameClaimType` property is used; otherwise, is used.| ||If `identity` is assignable from , the value of the `identity.RoleClaimType` property is used; otherwise, is used.| ]]> @@ -499,19 +499,19 @@ class. - -|Property|Value| -|--------------|-----------| -||`null`.| -||The value of the `authenticationType` parameter. If the `authenticationType` parameter is `null` or an empty string, the property is set to `null`.| -||`null`.| -||An empty collection.| -||**Note:** When accessed, the value of the property is returned based on the value of the property.| -||`null`.| -||**Note:** When accessed, the value of the property is returned based on the and the collection.| -||.| +## Remarks + The following table shows initial property values for an instance of the class. + +|Property|Value| +|--------------|-----------| +||`null`.| +||The value of the `authenticationType` parameter. If the `authenticationType` parameter is `null` or an empty string, the property is set to `null`.| +||`null`.| +||An empty collection.| +||**Note:** When accessed, the value of the property is returned based on the value of the property.| +||`null`.| +||**Note:** When accessed, the value of the property is returned based on the and the collection.| +||.| ||.| ]]> @@ -574,19 +574,19 @@ class. - -|Property|Value| -|--------------|-----------| -||`null`.| -||The value of the `authenticationType` parameter. If the `authenticationType` parameter is `null` or an empty string, the property is set to `null`.| -||`null`.| -||Initialized from the `claims` parameter.| -||**Note:** When accessed, the value of the property is returned based on the value of the property.| -||`null`.| -||**Note:** When accessed, the value of the property is returned based on the and the collection.| -||.| +## Remarks + The following table shows initial property values for an instance of the class. + +|Property|Value| +|--------------|-----------| +||`null`.| +||The value of the `authenticationType` parameter. If the `authenticationType` parameter is `null` or an empty string, the property is set to `null`.| +||`null`.| +||Initialized from the `claims` parameter.| +||**Note:** When accessed, the value of the property is returned based on the value of the property.| +||`null`.| +||**Note:** When accessed, the value of the property is returned based on the and the collection.| +||.| ||.| ]]> @@ -637,8 +637,8 @@ - - + + The serialized data. @@ -705,19 +705,19 @@ class. - -|Property|Value| -|--------------|-----------| -||If `identity` is assignable from , the value of the `identity.Actor` property; otherwise, `null`.| -||The `authenticationType` parameter. If the `authenticationType` parameter is `null` or an empty string, the value of the `identity.AuthenticationType` () property is used.| -||If `identity` is assignable from , the value of the `identity.BootStrapContext` property; otherwise, `null`.| -||Initialized from the `claims` parameter. If `identity` is assignable from , the claims from `identity` are added to the new instance before those specified by the `claims` parameter.| -||**Note:** When accessed, the value of the property is returned based on the value of the property.| -||If `identity` is assignable from , the value of the `identity.Label` property; otherwise, `null`.| -||If `identity` is not assignable from , is not `null`, and has an property that is not `null`; a name claim is added to the new instance using the value of the property. **Note:** When accessed, the value of the property is returned based on the and the collection.| -||If `identity` is assignable from , the value of the `identity.NameClaimType` property is used; otherwise, is used.| +## Remarks + The following table shows initial property values for an instance of the class. + +|Property|Value| +|--------------|-----------| +||If `identity` is assignable from , the value of the `identity.Actor` property; otherwise, `null`.| +||The `authenticationType` parameter. If the `authenticationType` parameter is `null` or an empty string, the value of the `identity.AuthenticationType` () property is used.| +||If `identity` is assignable from , the value of the `identity.BootStrapContext` property; otherwise, `null`.| +||Initialized from the `claims` parameter. If `identity` is assignable from , the claims from `identity` are added to the new instance before those specified by the `claims` parameter.| +||**Note:** When accessed, the value of the property is returned based on the value of the property.| +||If `identity` is assignable from , the value of the `identity.Label` property; otherwise, `null`.| +||If `identity` is not assignable from , is not `null`, and has an property that is not `null`; a name claim is added to the new instance using the value of the property. **Note:** When accessed, the value of the property is returned based on the and the collection.| +||If `identity` is assignable from , the value of the `identity.NameClaimType` property is used; otherwise, is used.| ||If `identity` is assignable from , the value of the `identity.RoleClaimType` property is used; otherwise, is used.| ]]> @@ -775,19 +775,19 @@ class. - -|Property|Value| -|--------------|-----------| -||`null`.| -||The value of the `authenticationType` parameter. If the `authenticationType` parameter is `null` or an empty string, the property is set to `null`.| -||`null`.| -||An empty collection.| -||**Note:** When accessed, the value of the property is returned based on the value of the property.| -||`null`.| -||**Note:** When accessed, the value of the property is returned based on the and the collection.| -||The value of the `nameType` parameter. If the `nameType` parameter is null or an empty string, the property is set to .| +## Remarks + The following table shows initial property values for an instance of the class. + +|Property|Value| +|--------------|-----------| +||`null`.| +||The value of the `authenticationType` parameter. If the `authenticationType` parameter is `null` or an empty string, the property is set to `null`.| +||`null`.| +||An empty collection.| +||**Note:** When accessed, the value of the property is returned based on the value of the property.| +||`null`.| +||**Note:** When accessed, the value of the property is returned based on the and the collection.| +||The value of the `nameType` parameter. If the `nameType` parameter is null or an empty string, the property is set to .| ||The value of the `roleType` parameter. If the `roleType` parameter is null or an empty string, the property is set to .| ]]> @@ -854,19 +854,19 @@ class. - -|Property|Value| -|--------------|-----------| -||`null`.| -||The value of the `authenticationType` parameter. If the `authenticationType` parameter is `null` or an empty string, the property is set to `null`.| -||`null`.| -||Initialized from the `claims` parameter.| -||**Note:** When accessed, the value of the property is returned based on the value of the property.| -||`null`.| -||**Note:** When accessed, the value of the property is returned based on the and the collection.| -||The value of the `nameType` parameter. However, if the `nameType` parameter is `null` or an empty string, the property is set to .| +## Remarks + The following table shows initial property values for an instance of the class. + +|Property|Value| +|--------------|-----------| +||`null`.| +||The value of the `authenticationType` parameter. If the `authenticationType` parameter is `null` or an empty string, the property is set to `null`.| +||`null`.| +||Initialized from the `claims` parameter.| +||**Note:** When accessed, the value of the property is returned based on the value of the property.| +||`null`.| +||**Note:** When accessed, the value of the property is returned based on the and the collection.| +||The value of the `nameType` parameter. However, if the `nameType` parameter is `null` or an empty string, the property is set to .| ||The value of the `roleClaimType` parameter. However, if the `roleClaimType` parameter is `null` or an empty string, the property is set to .| ]]> @@ -935,19 +935,19 @@ class. - -|Property|Value| -|--------------|-----------| -||If `identity` is assignable from , the value of the `identity.Actor` property; otherwise, `null`.| -||The `authenticationType` parameter. If the `authenticationType` parameter is `null` or an empty string, the value of the `identity.AuthenticationType` () property is used.| -||If `identity` is assignable from , the value of the `identity.BootStrapContext` property; otherwise, `null`.| -||Initialized from the `claims` parameter. If `identity` is assignable from , the claims from `identity` are added to the new instance before those specified by the `claims` parameter.| -||**Note:** When accessed, the value of the property is returned based on the value of the property.| -||If `identity` is assignable from , the value of the `identity.Label` property; otherwise, `null`.| -||If `identity` is not assignable from , is not `null`, and has an property that is not `null`; a name claim is added to the new instance using the value of the property. **Note:** When accessed, the value of the property is returned based on the and the collection.| -||The value of the `nameType` parameter. However, if the value of the `nameType` parameter is `null` or an empty string and `identity` is assignable from , the value of the `identity.NameClaimType` property is used; otherwise, is used.| +## Remarks + The following table shows initial property values for an instance of the class. + +|Property|Value| +|--------------|-----------| +||If `identity` is assignable from , the value of the `identity.Actor` property; otherwise, `null`.| +||The `authenticationType` parameter. If the `authenticationType` parameter is `null` or an empty string, the value of the `identity.AuthenticationType` () property is used.| +||If `identity` is assignable from , the value of the `identity.BootStrapContext` property; otherwise, `null`.| +||Initialized from the `claims` parameter. If `identity` is assignable from , the claims from `identity` are added to the new instance before those specified by the `claims` parameter.| +||**Note:** When accessed, the value of the property is returned based on the value of the property.| +||If `identity` is assignable from , the value of the `identity.Label` property; otherwise, `null`.| +||If `identity` is not assignable from , is not `null`, and has an property that is not `null`; a name claim is added to the new instance using the value of the property. **Note:** When accessed, the value of the property is returned based on the and the collection.| +||The value of the `nameType` parameter. However, if the value of the `nameType` parameter is `null` or an empty string and `identity` is assignable from , the value of the `identity.NameClaimType` property is used; otherwise, is used.| ||The value of the `roleClaimType` parameter. However, if the value of the `roleClaimType` parameter is `null` or an empty string and identity is assignable from , the value of the `identity.RoleClaimType` property is used; otherwise, is used.| ]]> @@ -1011,7 +1011,7 @@ property. The token on whose behalf the call is being delegated can be accessed through the property. ]]> @@ -1072,9 +1072,9 @@ method is invoked with this claims identity as the parameter to create a new claim with the correct subject. - +## Remarks + The claim is examined and if the subject is different than this claims identity, the method is invoked with this claims identity as the parameter to create a new claim with the correct subject. + This method has the `SecurityCritical` attribute applied to control which entities can add claims to the identity. Further down the pipe, authorization decisions are made based on the claims that are present in the collection. ]]> @@ -1140,9 +1140,9 @@ method is invoked with this claims identity as the parameter to create a new claim with the correct subject. - +## Remarks + Each claim is examined and if the subject is different than this claims identity, the method is invoked with this claims identity as the parameter to create a new claim with the correct subject. + This method has the `SecurityCritical` attribute applied to control which entities can add claims to the identity. Further down the pipe, authorization decisions are made based on the claims that are present in the collection. ]]> @@ -1269,11 +1269,11 @@ class. - - Set the `saveBootstrapContext` attribute on either the [<identityConfiguration>](/dotnet/framework/configure-apps/file-schema/windows-identity-foundation/identityconfiguration) or the [<securityTokenHandlerConfiguration>](/dotnet/framework/configure-apps/file-schema/windows-identity-foundation/securitytokenhandlerconfiguration) element in a configuration file to specify whether the token used to generate the should be preserved in the property. - +## Remarks + The underlying object is an instance of the class. + + Set the `saveBootstrapContext` attribute on either the [<identityConfiguration>](/dotnet/framework/configure-apps/file-schema/windows-identity-foundation/identityconfiguration) or the [<securityTokenHandlerConfiguration>](/dotnet/framework/configure-apps/file-schema/windows-identity-foundation/securitytokenhandlerconfiguration) element in a configuration file to specify whether the token used to generate the should be preserved in the property. + If the property is not `null`, applications can access the original token and the claims it produced through the properties and methods of the class. ]]> @@ -1331,11 +1331,11 @@ collection essentially describe the entity that is represented by the . The claims describe the properties and rights possessed by the entity and can be examined by applications to make decisions about authentication and authorization. - +## Remarks + The collection may contain entries that are `null`. + + The claims contained in the collection essentially describe the entity that is represented by the . The claims describe the properties and rights possessed by the entity and can be examined by applications to make decisions about authentication and authorization. + > [!NOTE] > The class has a property as well. In the majority of cases you should access the user's claims through the collection rather than through the collection. You will need to access the claims of an individual only in the cases where the principal contains more than one and you need to evaluate or modify a specific identity. @@ -1699,7 +1699,7 @@ @@ -1857,8 +1857,8 @@ The comparison is done in System.Void - - + + The object to populate with data. @@ -1973,7 +1973,7 @@ The comparison is done in or properties. The comparison is made using Ordinal, case sensitive on value; case in-sensitive on type. ]]> @@ -2026,7 +2026,7 @@ The comparison is done in property is not `null` or an empty string. ]]> @@ -2142,7 +2142,7 @@ The comparison is done in property. If no claim is found that matches the name claim type, returns `null`. ]]> @@ -2190,9 +2190,9 @@ The comparison is done in property specifies the claim type () that is used to provide the name for this identity. The name is accessed through the property. - +## Remarks + The property specifies the claim type () that is used to provide the name for this identity. The name is accessed through the property. + This property is set by the constructor. ]]> @@ -2254,11 +2254,11 @@ The comparison is done in method, which returns a Boolean value that indicates whether the claim has been removed, throws an exception if the claim could not be removed - - The specified claim is matched by object reference (). - +## Remarks + It is possible that the claim cannot be removed because it is not owned by the identity. For example, this would be the case for role claims that are owned by the principal. Unlike the method, which returns a Boolean value that indicates whether the claim has been removed, throws an exception if the claim could not be removed + + The specified claim is matched by object reference (). + This method has the `SecurityCritical` attribute applied to control which entities can remove claims from the identity. Further down the pipe, authorization decisions are made based on the claims that are present in the collection. ]]> @@ -2306,7 +2306,7 @@ The comparison is done in ) that is used when evaluating this identity for the method. The method is called to determine whether the current principal is in a specified role. The claims-based model extends this check to use claims presented by the principal. A object can contain one or more objects and each identity object can contain multiple objects. The property specifies the claim type of the claim that should be used to provide the value for the role when evaluating this object. The property is set by the constructor. A common value is . ]]> @@ -2370,11 +2370,11 @@ The comparison is done in ). - +## Remarks + It is possible that the claim cannot be removed because it is not owned by the identity. For example, this would be the case for role claims that are owned by the principal. + + The specified claim is matched by object reference (). + This method has the `SecurityCritical` attribute applied to control which entities can remove claims from the identity. Further down the pipe, authorization decisions are made based on the claims that are present in the collection. ]]> diff --git a/xml/System.Security.Claims/ClaimsPrincipal.xml b/xml/System.Security.Claims/ClaimsPrincipal.xml index e1722c56ea7..c41401aad07 100644 --- a/xml/System.Security.Claims/ClaimsPrincipal.xml +++ b/xml/System.Security.Claims/ClaimsPrincipal.xml @@ -67,41 +67,41 @@ rather than simply implementing the interface. In addition to implementing the interface, exposes properties and methods that are useful for working with claims. - - exposes a collection of identities, each of which is a . In the common case, this collection, which is accessed through the property, will only have a single element. - - The introduction of in .NET 4.5 as the principal from which most principal classes derive does not force you to change anything in the way in which you deal with identity. It does, however open up more possibilities and offer more chances to exercise finer access control. For example: - -- The application code itself can work directly with the claims contained in the current principal to drive extra authentication, authorization, and personalization tasks. - -- You can front your resources with a claims processing pipeline, which can deal with authentication requests and authorization policy even before execution reaches your code. For example, you can configure a web-based application or service with a custom claims authentication manager, an instance of a class that derives from the class. When so configured, the request processing pipeline invokes the method on your claims authentication manager passing it a that represents the context of the incoming request. Your claims authentication manager can then perform authentication based on the values of the incoming claims. It can also filter, transform, or add claims to the incoming claim set. For example, it could be used to enrich the incoming claim set with new claims created from a local data source such as a local user profile - -- You can configure a web-based application with a custom claims authorization manager, an instance of a class that derives from the class. When so configured, the request processing pipeline packages the incoming in an and invokes the method on your claims authorization manager. Your claims authorization manager can then enforce authorization based on the incoming claims. - -- Inline claims-based code access checks can be performed by configuring your application with a custom claims authorization manager and using either the class to perform imperative access checks or the to perform declarative access checks. Claims-based code access checks are performed inline, outside of the processing pipeline, and so are available to all applications as long as a claims authorization manager is configured. - - You can obtain a instance for the principal associated with a request, or the principal under which a thread is executing, in a [relying party (RP) application](/archive/msdn-magazine/2010/august/federated-identity-passive-authentication-for-asp-net-with-wif) by casting the property to . The claims associated with an object are available through its property. The property returns all of the claims contained by the identities associated with the principal. In the uncommon case in which the contains multiple instances, you can use the property or you can access the primary identity by using the property. provides several methods through which these claims may be searched and fully supports Language Integrated Query (LINQ). Identities can be added to the principal by using the or methods. - +## Remarks + Beginning with .NET Framework 4.5, Windows Identity Foundation (WIF) and claims-based identity are fully integrated into .NET Framework. This means that many classes that represent a principal in the .NET Framework now derive from rather than simply implementing the interface. In addition to implementing the interface, exposes properties and methods that are useful for working with claims. + + exposes a collection of identities, each of which is a . In the common case, this collection, which is accessed through the property, will only have a single element. + + The introduction of in .NET 4.5 as the principal from which most principal classes derive does not force you to change anything in the way in which you deal with identity. It does, however open up more possibilities and offer more chances to exercise finer access control. For example: + +- The application code itself can work directly with the claims contained in the current principal to drive extra authentication, authorization, and personalization tasks. + +- You can front your resources with a claims processing pipeline, which can deal with authentication requests and authorization policy even before execution reaches your code. For example, you can configure a web-based application or service with a custom claims authentication manager, an instance of a class that derives from the class. When so configured, the request processing pipeline invokes the method on your claims authentication manager passing it a that represents the context of the incoming request. Your claims authentication manager can then perform authentication based on the values of the incoming claims. It can also filter, transform, or add claims to the incoming claim set. For example, it could be used to enrich the incoming claim set with new claims created from a local data source such as a local user profile + +- You can configure a web-based application with a custom claims authorization manager, an instance of a class that derives from the class. When so configured, the request processing pipeline packages the incoming in an and invokes the method on your claims authorization manager. Your claims authorization manager can then enforce authorization based on the incoming claims. + +- Inline claims-based code access checks can be performed by configuring your application with a custom claims authorization manager and using either the class to perform imperative access checks or the to perform declarative access checks. Claims-based code access checks are performed inline, outside of the processing pipeline, and so are available to all applications as long as a claims authorization manager is configured. + + You can obtain a instance for the principal associated with a request, or the principal under which a thread is executing, in a [relying party (RP) application](/archive/msdn-magazine/2010/august/federated-identity-passive-authentication-for-asp-net-with-wif) by casting the property to . The claims associated with an object are available through its property. The property returns all of the claims contained by the identities associated with the principal. In the uncommon case in which the contains multiple instances, you can use the property or you can access the primary identity by using the property. provides several methods through which these claims may be searched and fully supports Language Integrated Query (LINQ). Identities can be added to the principal by using the or methods. + > [!NOTE] -> To add identities to the , a caller must have full trust. - - By default, WIF prioritizes objects when selecting the primary identity to return through the property. You can modify this behavior by supplying a delegate through the property to perform the selection. The property provides similar functionality for the property. - +> To add identities to the , a caller must have full trust. + + By default, WIF prioritizes objects when selecting the primary identity to return through the property. You can modify this behavior by supplying a delegate through the property to perform the selection. The property provides similar functionality for the property. + In the claim-based model, whether a principal is in a specified role is determined by the claims presented by its underlying identities. The method essentially examines each identity associated with the principal to determine whether it possesses a claim with the specified role value. The type of the claim (represented by its property) used to determine which claims should be examined during role checks is specified on an identity through its property. Thus, the claims examined during role checks can be of a different type for different identities associated with the principal. - -## Examples - The following example extracts the claims presented by a user in an HTTP request and writes them to the HTTP response. The current user is read from the as a . The claims are then read from it and then are written to the response. - + +## Examples + The following example extracts the claims presented by a user in an HTTP request and writes them to the HTTP response. The current user is read from the as a . The claims are then read from it and then are written to the response. + ```csharp -if (HttpContext.Current.User is ClaimsPrincipal principal) -{ - foreach (Claim claim in principal.Claims) - { - Response.Write("CLAIM TYPE: " + claim.Type + "; CLAIM VALUE: " + claim.Value + "
"); - } -} +if (HttpContext.Current.User is ClaimsPrincipal principal) +{ + foreach (Claim claim in principal.Claims) + { + Response.Write("CLAIM TYPE: " + claim.Type + "; CLAIM VALUE: " + claim.Value + "
"); + } +} ``` ]]>
@@ -158,7 +158,7 @@ if (HttpContext.Current.User is ClaimsPrincipal principal) collection is empty). ]]> @@ -205,7 +205,7 @@ if (HttpContext.Current.User is ClaimsPrincipal principal) collection is initialized with the specified identities. ]]> @@ -254,7 +254,7 @@ if (HttpContext.Current.User is ClaimsPrincipal principal) is constructed using the bytes from and initialized in the same way as the . ]]> @@ -303,7 +303,7 @@ if (HttpContext.Current.User is ClaimsPrincipal principal) , it is used to initialize the collection. Otherwise, a is created using the specified identity and is used to initialize the collection. ]]> @@ -352,7 +352,7 @@ if (HttpContext.Current.User is ClaimsPrincipal principal) , all of its identities are added to the collection. If the specified principal is not assignable from , a new is created from the in its property and added to the collection. ]]> @@ -405,8 +405,8 @@ if (HttpContext.Current.User is ClaimsPrincipal principal) - - + + The serialized data. @@ -466,7 +466,7 @@ if (HttpContext.Current.User is ClaimsPrincipal principal) collection. ]]> @@ -524,7 +524,7 @@ if (HttpContext.Current.User is ClaimsPrincipal principal) collection. ]]> @@ -583,9 +583,9 @@ if (HttpContext.Current.User is ClaimsPrincipal principal) objects that is accessible through the Identities property. Each in the collection contains one or more claims. The property returns all of the claims from all of the claims identities in this collection. - +## Remarks + A claims principal has a collection of objects that is accessible through the Identities property. Each in the collection contains one or more claims. The property returns all of the claims from all of the claims identities in this collection. + The property can be examined by custom implementations of the class to make authentication decisions or to filter, transform, or enrich an incoming claim set; by custom implementations of the class to enforce authorization policy; or by application code to make authorization decisions or to customize user experience based on the claims present in the collection. ]]> @@ -638,7 +638,7 @@ if (HttpContext.Current.User is ClaimsPrincipal principal) property. ]]> @@ -784,7 +784,7 @@ if (HttpContext.Current.User is ClaimsPrincipal principal) is returned. You can change this behavior by setting the property to specify a delegate to be called to determine the current principal. ]]> @@ -897,7 +897,7 @@ if (HttpContext.Current.User is ClaimsPrincipal principal) @@ -950,7 +950,7 @@ if (HttpContext.Current.User is ClaimsPrincipal principal) @@ -1016,7 +1016,7 @@ if (HttpContext.Current.User is ClaimsPrincipal principal) ## Remarks -Each is called. +Each is called. ## See also @@ -1077,7 +1077,7 @@ Each is called. Each is called. ## See also - + . ]]>
@@ -1125,8 +1125,8 @@ Each is called. System.Void - - + + The object to populate with data. @@ -1194,7 +1194,7 @@ Each is called. ## Remarks -Each is called. +Each is called. ## See also @@ -1253,7 +1253,7 @@ Each is called. or properties. The comparison is made using Ordinal, case sensitive on value; case in-sensitive on type. ]]> @@ -1302,9 +1302,9 @@ Each is called. @@ -1365,9 +1365,9 @@ Each is called. when returning the identity. The first found in the collection is returned. If there is no in the collection, the first identity assignable from is returned. If there is no , `null` is returned. If the collection is empty, an is thrown. - +## Remarks + By default, the framework prioritizes identities of type when returning the identity. The first found in the collection is returned. If there is no in the collection, the first identity assignable from is returned. If there is no , `null` is returned. If the collection is empty, an is thrown. + You can change the default behavior by setting the property to specify a delegate to be called to determine the identity. ]]> @@ -1423,9 +1423,9 @@ Each is called. method checks whether an identity that this claims principal possesses contains a claim of type where the value of the claim is equal to the value specified by the `role` parameter. - +## Remarks + The method checks whether an identity that this claims principal possesses contains a claim of type where the value of the claim is equal to the value specified by the `role` parameter. + > [!NOTE] > Each has its own definition of the claim type that represents a role. This claim type can be accessed and set through the property. @@ -1484,7 +1484,7 @@ Each is called. property. ]]> diff --git a/xml/System.Security.Cryptography.Pkcs/EnvelopedCms.xml b/xml/System.Security.Cryptography.Pkcs/EnvelopedCms.xml index a6d7372adf9..20bf9cb6f38 100644 --- a/xml/System.Security.Cryptography.Pkcs/EnvelopedCms.xml +++ b/xml/System.Security.Cryptography.Pkcs/EnvelopedCms.xml @@ -231,8 +231,8 @@ System.Security.Cryptography.Pkcs - - + + One of the enumeration values that specifies the subject identifier scheme to use for recipient certificates selected by a UI prompt. @@ -276,9 +276,9 @@ - - - + + + One of the enumeration values that specifies the subject identifier scheme to use for recipient certificates selected by a UI prompt. diff --git a/xml/System.Security.Cryptography/CngKey.xml b/xml/System.Security.Cryptography/CngKey.xml index fd40a765b43..56164862a82 100644 --- a/xml/System.Security.Cryptography/CngKey.xml +++ b/xml/System.Security.Cryptography/CngKey.xml @@ -57,10 +57,10 @@ Defines the core functionality for keys that are used with Cryptography Next Generation (CNG) objects. - [!NOTE] > CNG classes don't work on non-Windows platforms. @@ -69,30 +69,6 @@ - - - - - - - Constructor - - System.Core - 2.0.5.0 - 4.0.0.0 - - - System.Security.Cryptography.Cng - - - System.Security.Cryptography - - - - To be added. - To be added. - - @@ -269,11 +245,11 @@ Creates a object that can be used with the specified algorithm. An ephemeral key. - object that specifies a default and other advanced parameters for the key. - + object that specifies a default and other advanced parameters for the key. + ]]> @@ -346,11 +322,11 @@ Creates a named object that provides the specified algorithm. A persisted or ephemeral key that provides the specified algorithm. - object that specifies a default and other advanced parameters for the key. - + object that specifies a default and other advanced parameters for the key. + ]]> @@ -436,11 +412,11 @@ Creates a named object that provides the specified algorithm, using the supplied key creation parameters. A persisted or ephemeral key that provides the specified algorithm. - @@ -499,14 +475,14 @@ Removes the key that is associated with the object. - method on an ephemeral key, it closes the handle to the key. - - When you call the method on a named key, the object can no longer be used after the named key is deleted. - + method on an ephemeral key, it closes the handle to the key. + + When you call the method on a named key, the object can no longer be used after the named key is deleted. + ]]> An attempt was made to access a deleted key. @@ -566,14 +542,14 @@ Releases all resources used by the current instance of the class. - 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). - + 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. + ]]> @@ -638,11 +614,11 @@ if the named key exists in the default KSP; otherwise, . - . - + . + ]]> @@ -708,11 +684,11 @@ if the named key exists in the specified provider; otherwise, . - . - + . + ]]> @@ -784,11 +760,11 @@ if the named key exists in the specified provider; otherwise, . - , and to specify key open options. - + , and to specify key open options. + ]]> @@ -851,11 +827,11 @@ Exports the key material into a BLOB, in the specified format. A BLOB that contains the key material in the specified format. - ) only allows export of private keys in the , , and formats. This restriction is controlled by the underlying KSP. If you use a different KSP, other formats may apply. - + ) only allows export of private keys in the , , and formats. This restriction is controlled by the underlying KSP. If you use a different KSP, other formats may apply. + ]]> @@ -913,11 +889,11 @@ Gets the export policy that is used by the key. An object that specifies the export policy for the key. - @@ -978,27 +954,27 @@ Gets a property, given a name and a set of property options. An object that contains the raw value of the specified property. - class. provides wrappers for several, but not all, properties. The method is primarily used to access the value of a property that is not wrapped. - - This method is useful in the following cases: - -- A new version of the operating system supports a new Cryptography Next Generation (CNG) key property that does not have a wrapper. - -- You add a custom property to the key. - - The `options` parameter is specifically used to indicate the following: - -- Whether the property is built-in, or custom. - -- Whether the property should be persisted with the key. - - These options must match the value that the property was set with, or the property will not be found. - - is thrown if the property cannot be found. You should call the method first to avoid the exception instead of wrapping the method call in a `try/catch` block. - + class. provides wrappers for several, but not all, properties. The method is primarily used to access the value of a property that is not wrapped. + + This method is useful in the following cases: + +- A new version of the operating system supports a new Cryptography Next Generation (CNG) key property that does not have a wrapper. + +- You add a custom property to the key. + + The `options` parameter is specifically used to indicate the following: + +- Whether the property is built-in, or custom. + +- Whether the property should be persisted with the key. + + These options must match the value that the property was set with, or the property will not be found. + + is thrown if the property cannot be found. You should call the method first to avoid the exception instead of wrapping the method call in a `try/catch` block. + ]]> @@ -1052,13 +1028,13 @@ Gets a safe handle that represents a native key (NCRYPT_KEY_HANDLE). A safe handle that represents the key. - object. It will persist even if the current is disposed, and must be disposed of separately. - - You can release the current object and the handle in any order without any adverse effects. - + object. It will persist even if the current is disposed, and must be disposed of separately. + + You can release the current object and the handle in any order without any adverse effects. + ]]> @@ -1120,19 +1096,19 @@ if the specified property is found; otherwise, . - @@ -1200,14 +1176,14 @@ Creates a new key by importing the specified key material into the default key storage provider (KSP) and using the specified format. A new key. - . - + . + > [!IMPORTANT] -> On Windows operating systems before Windows 7 and Windows Server 2008 R2, some CNG key binary large object (BLOB) formats are not supported. - +> On Windows operating systems before Windows 7 and Windows Server 2008 R2, some CNG key binary large object (BLOB) formats are not supported. + ]]> @@ -1278,13 +1254,13 @@ Creates a new key by importing the specified key material into the specified key storage provider (KSP), using the specified format. A new key. - [!IMPORTANT] -> On Windows operating systems before Windows 7 and Windows Server 2008 R2, some CNG key binary large object (BLOB) formats are not supported. - +> On Windows operating systems before Windows 7 and Windows Server 2008 R2, some CNG key binary large object (BLOB) formats are not supported. + ]]> @@ -1348,19 +1324,19 @@ if the key is ephemeral; otherwise, . - method overload, the common language runtime (CLR) is managing the key and can determine whether it is ephemeral. - -- If the key was opened by the method overload, the CLR cannot determine whether it is ephemeral. Therefore, the key is assumed to be persisted. However, if this method is used to open a handle to a key that is created by the CLR, the CLR will be able to determine whether it is ephemeral. - - This property does not have a public setter; it is read-only. - + method overload, the common language runtime (CLR) is managing the key and can determine whether it is ephemeral. + +- If the key was opened by the method overload, the CLR cannot determine whether it is ephemeral. Therefore, the key is assumed to be persisted. However, if this method is used to open a handle to a key that is created by the CLR, the CLR will be able to determine whether it is ephemeral. + + This property does not have a public setter; it is read-only. + ]]> @@ -1642,15 +1618,15 @@ Creates an instance of an object that represents an existing named key. An existing key. - . Use the overload if you want to specify another KSP. - -- Key open options: . - + . Use the overload if you want to specify another KSP. + +- Key open options: . + ]]> @@ -1715,13 +1691,13 @@ Creates an instance of an object by using a handle to an existing key. An existing key. - class rely on this value to be correct. Therefore, make sure that you pass the correct flag value to the methods. - + class rely on this value to be correct. Therefore, make sure that you pass the correct flag value to the methods. + ]]> @@ -1788,11 +1764,11 @@ Creates an instance of an object that represents an existing named key, using the specified key storage provider (KSP). An existing key. - method overload, this overload lets you specify the provider. In addition, a default value of is created and bound to the key. - + method overload, this overload lets you specify the provider. In addition, a default value of is created and bound to the key. + ]]> @@ -1863,11 +1839,11 @@ Creates an instance of an object that represents an existing named key, using the specified key storage provider (KSP) and key open options. An existing key. - method overload, this overload lets you specify both the provider and the key open options. - + method overload, this overload lets you specify both the provider and the key open options. + ]]> @@ -1934,13 +1910,13 @@ Gets or sets the window handle (HWND) that should be used for user interface (UI) prompts caused by accessing the key. The parent window handle for the key. - @@ -2052,13 +2028,13 @@ Gets a native handle (an NCRYPT_PROV_HANDLE) to the key storage provider (KSP). A handle to the KSP. - object. It will persist even if the current is disposed, and must be disposed of separately. - - You can release the current object and the handle in any order without any adverse effects. - + object. It will persist even if the current is disposed, and must be disposed of separately. + + You can release the current object and the handle in any order without any adverse effects. + ]]>
@@ -2116,11 +2092,11 @@ The key property to set. Sets a named property on the key. - object. The options set on the object must exactly match the options in the call. Otherwise, the property will not be found. - + object. The options set on the object must exactly match the options in the call. Otherwise, the property will not be found. + ]]>
@@ -2175,11 +2151,11 @@ Gets parameters that control the user interface (UI) for accessing the key. An object that contains configuration parameters for displaying the UI. -
@@ -2243,11 +2219,11 @@ Gets the unique name for the key. An alternate name for the key. If the key is ephemeral, the value is . - property will return the file name of the key as this property. The name returned by the is implementation-dependent. - + property will return the file name of the key as this property. The name returned by the is implementation-dependent. + ]]>
diff --git a/xml/System.Security.Cryptography/CspParameters.xml b/xml/System.Security.Cryptography/CspParameters.xml index e4fb4fa46c4..88a80e34f3b 100644 --- a/xml/System.Security.Cryptography/CspParameters.xml +++ b/xml/System.Security.Cryptography/CspParameters.xml @@ -68,34 +68,34 @@ Contains parameters that are passed to the cryptographic service provider (CSP) that performs cryptographic computations. This class cannot be inherited. - class represents parameters that you can pass to managed cryptography classes that internally use Microsoft Cryptographic Service Providers (CSPs) from the unmanaged Microsoft Cryptography API (CAPI). Classes with names ending in "CryptoServiceProvider" are managed code wrappers for the corresponding CSP. - - Use the class to do the following: - -- Specify a particular CSP by passing the provider type to the or property. You can also specify a CSP using an overload of the constructor. - -- Create a key container where you can store cryptographic keys. Key containers provide the most secure way to persist cryptographic keys and keep them secret from malicious third parties. For more information about creating key containers, see [How to: Store Asymmetric Keys in a Key Container](/dotnet/standard/security/how-to-store-asymmetric-keys-in-a-key-container). - -- Specify whether to create an asymmetric signature key or an asymmetric exchange key using the property. - - - -## Examples - The following code example creates a key container using the class and saves the key in the container. - + class represents parameters that you can pass to managed cryptography classes that internally use Microsoft Cryptographic Service Providers (CSPs) from the unmanaged Microsoft Cryptography API (CAPI). Classes with names ending in "CryptoServiceProvider" are managed code wrappers for the corresponding CSP. + + Use the class to do the following: + +- Specify a particular CSP by passing the provider type to the or property. You can also specify a CSP using an overload of the constructor. + +- Create a key container where you can store cryptographic keys. Key containers provide the most secure way to persist cryptographic keys and keep them secret from malicious third parties. For more information about creating key containers, see [How to: Store Asymmetric Keys in a Key Container](/dotnet/standard/security/how-to-store-asymmetric-keys-in-a-key-container). + +- Specify whether to create an asymmetric signature key or an asymmetric exchange key using the property. + + + +## Examples + The following code example creates a key container using the class and saves the key in the container. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/capikey/CPP/capikey.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/CspParameters/Overview/capikey.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/capikey/VB/capikey.vb" id="Snippet1"::: - - The following code example uses the class to select a Smart Card Cryptographic Service Provider. It then signs and verifies data using the smart card. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/capikey/VB/capikey.vb" id="Snippet1"::: + + The following code example uses the class to select a Smart Card Cryptographic Service Provider. It then signs and verifies data using the smart card. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Cryptography.SmartCardCSP/CPP/Cryptography.SmartCardCSP.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/CspParameters/Overview/example.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.SmartCardCSP/VB/example.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.SmartCardCSP/VB/example.vb" id="Snippet1"::: + ]]> Cryptographic Services @@ -149,22 +149,22 @@ Initializes a new instance of the class. - initializes the field to a value of `24`, which specifies the PROV_RSA_AES provider. This default provider is compatible with the algorithm. - - For information about other provider types, see the field. - - - -## Examples - The following code example creates a key container using the class and saves the key in the container. - + initializes the field to a value of `24`, which specifies the PROV_RSA_AES provider. This default provider is compatible with the algorithm. + + For information about other provider types, see the field. + + + +## Examples + The following code example creates a key container using the class and saves the key in the container. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/capikey/CPP/capikey.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/CspParameters/Overview/capikey.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/capikey/VB/capikey.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/capikey/VB/capikey.vb" id="Snippet1"::: + ]]> Cryptographic Services @@ -212,15 +212,15 @@ A provider type code that specifies the kind of provider to create. Initializes a new instance of the class with the specified provider type code. - constructor to specify a provider type by passing a numeric value that represents that provider. The numeric values that represent the default provider types are defined in the WinCrypt.h header file: - -- To specify a provider compatible with the algorithm, pass a value of `1` to the `dwTypeIn` parameter. - -- To specify a provider compatible with the algorithm, pass a value of `13` to the `dwTypeIn` parameter. - + constructor to specify a provider type by passing a numeric value that represents that provider. The numeric values that represent the default provider types are defined in the WinCrypt.h header file: + +- To specify a provider compatible with the algorithm, pass a value of `1` to the `dwTypeIn` parameter. + +- To specify a provider compatible with the algorithm, pass a value of `13` to the `dwTypeIn` parameter. + For information about other provider type values, see the field. For more information about the default provider types and their behaviors, see the [Microsoft Cryptography API (CAPI) documentation](/windows/win32/seccrypto/cryptography-reference). ]]> @@ -273,28 +273,28 @@ A provider name. Initializes a new instance of the class with the specified provider type code and name. - constructor to specify a provider type and name. - - Specify a provider type by passing a numeric value that represents the desired provider type. The numeric values that represent the default provider types are defined in the WinCrypt.h header file: - -- To specify a provider compatible with the algorithm, pass a value of `1` to the `dwTypeIn` parameter. - -- To specify a provider compatible with the algorithm, pass a value of `13` to the `dwTypeIn` parameter. - + constructor to specify a provider type and name. + + Specify a provider type by passing a numeric value that represents the desired provider type. The numeric values that represent the default provider types are defined in the WinCrypt.h header file: + +- To specify a provider compatible with the algorithm, pass a value of `1` to the `dwTypeIn` parameter. + +- To specify a provider compatible with the algorithm, pass a value of `13` to the `dwTypeIn` parameter. + For information about other provider type values, see the field. For more information about the default provider types and their behaviors, see the [Microsoft Cryptography API (CAPI) documentation](/windows/win32/seccrypto/cryptography-reference). - - - -## Examples - The following code example uses the class to select a Smart Card Cryptographic Service Provider. It then signs and verifies data using the smart card. - + + + +## Examples + The following code example uses the class to select a Smart Card Cryptographic Service Provider. It then signs and verifies data using the smart card. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Cryptography.SmartCardCSP/CPP/Cryptography.SmartCardCSP.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/CspParameters/Overview/example.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.SmartCardCSP/VB/example.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.SmartCardCSP/VB/example.vb" id="Snippet1"::: + ]]> Cryptographic Services @@ -347,21 +347,21 @@ A container name. Initializes a new instance of the class with the specified provider type code and name, and the specified container name. - constructor to specify a provider type, a provider name, and a container name. - - You can use the container name to retrieve a key within that container. - - Specify a provider type by passing a numeric value that represents the desired provider type. The numeric values that represent the default provider types are defined in the WinCrypt.h header file: - -- To specify a provider compatible with the algorithm, pass a value of `1` to the `dwTypeIn` parameter. - -- To specify a provider compatible with the algorithm, pass a value of `13` to the `dwTypeIn` parameter. - + constructor to specify a provider type, a provider name, and a container name. + + You can use the container name to retrieve a key within that container. + + Specify a provider type by passing a numeric value that represents the desired provider type. The numeric values that represent the default provider types are defined in the WinCrypt.h header file: + +- To specify a provider compatible with the algorithm, pass a value of `1` to the `dwTypeIn` parameter. + +- To specify a provider compatible with the algorithm, pass a value of `13` to the `dwTypeIn` parameter. + For information about other provider type values, see the field. For more information about the default provider types and their behaviors, see the [Microsoft Cryptography API (CAPI) documentation](/windows/win32/seccrypto/cryptography-reference). - + ]]> Cryptographic Services @@ -390,11 +390,11 @@ System.Security.Cryptography - - - - - + + + + + The provider type code that specifies the kind of provider to create. @@ -404,19 +404,19 @@ A handle to the parent window for a smart card password dialog. Initializes a new instance of the class using a provider type, a provider name, a container name, access information, and a handle to an unmanaged smart card password dialog. - algorithm, pass a value of `1` to the `dwTypeIn` parameter. - -- To specify a provider compatible with the algorithm, pass a value of `13` to the `dwTypeIn` parameter. - + algorithm, pass a value of `1` to the `dwTypeIn` parameter. + +- To specify a provider compatible with the algorithm, pass a value of `13` to the `dwTypeIn` parameter. + For information about other provider type values, see the field. For more information about the default provider types and their behaviors, see the [Microsoft Cryptography API (CAPI) documentation](/windows/win32/seccrypto/cryptography-reference). - + ]]> @@ -444,11 +444,11 @@ System.Security.Cryptography - - - - - + + + + + The provider type code that specifies the kind of provider to create. @@ -458,19 +458,19 @@ A password associated with a smart card key. Initializes a new instance of the class using a provider type, a provider name, a container name, access information, and a password associated with a smart card key. - algorithm, pass a value of `1` to the `dwTypeIn` parameter. - -- To specify a provider compatible with the algorithm, pass a value of `13` to the `dwTypeIn` parameter. - + algorithm, pass a value of `1` to the `dwTypeIn` parameter. + +- To specify a provider compatible with the algorithm, pass a value of `13` to the `dwTypeIn` parameter. + For information about other provider type values, see the field. For more information about the default provider types and their behaviors, see the [Microsoft Cryptography API (CAPI) documentation](/windows/win32/seccrypto/cryptography-reference). - + ]]> @@ -504,11 +504,11 @@ Gets or sets a object that represents access rights and audit rules for a container. A object that represents access rights and audit rules for a container. - property to specify a object that manages the creation of discretionary access control lists (DACLS) and system access control lists (SACLS) for a container. - + property to specify a object that manages the creation of discretionary access control lists (DACLS) and system access control lists (SACLS) for a container. + ]]> @@ -601,22 +601,22 @@ Represents the key container name for . - field to specify a name for your key container. You can use the container name to retrieve the persisted key within that container. - - For more information about creating key containers, see [How to: Store Asymmetric Keys in a Key Container](/dotnet/standard/security/how-to-store-asymmetric-keys-in-a-key-container). - - - -## Examples - The following code example creates a key container using the class and saves the key in the container. - + field to specify a name for your key container. You can use the container name to retrieve the persisted key within that container. + + For more information about creating key containers, see [How to: Store Asymmetric Keys in a Key Container](/dotnet/standard/security/how-to-store-asymmetric-keys-in-a-key-container). + + + +## Examples + The following code example creates a key container using the class and saves the key in the container. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/capikey/CPP/capikey.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/CspParameters/Overview/capikey.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/capikey/VB/capikey.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/capikey/VB/capikey.vb" id="Snippet1"::: + ]]> Cryptographic Services @@ -663,26 +663,26 @@ Specifies whether an asymmetric key is created as a signature key or an exchange key. - field initializes the property when you initialize a object with a object. - - An exchange key is an asymmetric key pair used to encrypt session keys so that they can be safely stored and exchanged with other users. You can use the value (`1`) to specify an exchange key. This value corresponds to the `AT_KEYEXCHANGE` value used in the unmanaged Microsoft Cryptographic API (CAPI). - - A signature key is an asymmetric key pair used for authenticating digitally signed messages or files. You can use the value (`2`) to specify a signature key. This value corresponds to the `AT_SIGNATURE` value used in CAPI. - - By default, the field specifies an exchange key. - - - -## Examples - The following code example demonstrates how to use the enumeration to specify a key type for an object. - + field initializes the property when you initialize a object with a object. + + An exchange key is an asymmetric key pair used to encrypt session keys so that they can be safely stored and exchanged with other users. You can use the value (`1`) to specify an exchange key. This value corresponds to the `AT_KEYEXCHANGE` value used in the unmanaged Microsoft Cryptographic API (CAPI). + + A signature key is an asymmetric key pair used for authenticating digitally signed messages or files. You can use the value (`2`) to specify a signature key. This value corresponds to the `AT_SIGNATURE` value used in CAPI. + + By default, the field specifies an exchange key. + + + +## Examples + The following code example demonstrates how to use the enumeration to specify a key type for an object. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Cryptography.KeyNumber/cpp/sample.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/CspParameters/KeyNumber/sample.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.KeyNumber/VB/sample.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Cryptography.KeyNumber/VB/sample.vb" id="Snippet1"::: + ]]> Cryptographic Services @@ -735,11 +735,11 @@ Gets or sets a password associated with a smart card key. A password associated with a smart card key. - property to supply a password for a smart card key. When you specify a password using this property, a password dialog box will not be presented to the user. - + property to supply a password for a smart card key. When you specify a password using this property, a password dialog box will not be presented to the user. + ]]> @@ -785,13 +785,13 @@ Gets or sets a handle to the unmanaged parent window for a smart card password dialog box. A handle to the parent window for a smart card password dialog box. - property to specify a handle to the unmanaged parent window for a smart card password dialog box. When you specify a handle using this property, a smart card password dialog box will be presented to the user. - - You can avoid presenting a smart card password dialog box by explicitly specifying a password by using the property. - + property to specify a handle to the unmanaged parent window for a smart card password dialog box. When you specify a handle using this property, a smart card password dialog box will be presented to the user. + + You can avoid presenting a smart card password dialog box by explicitly specifying a password by using the property. + ]]> @@ -838,12 +838,12 @@ Represents the provider name for . - Cryptographic Services @@ -890,40 +890,40 @@ For details on provider names, see the [Microsoft Cryptography API (CAPI) docume Represents the provider type code for . - field to specify a provider type by passing a numeric value that represents that provider. The numeric values that represent the default provider types are defined in the WinCrypt.h header file: - -- To specify a provider compatible with the class, pass a value of `1`. - -- To specify a provider compatible with the class, pass a value of `13`. - - The following table lists the provider types and their corresponding numeric values defined in the WinCrypt.h header file. - -|Provider Type|Numeric Value| -|-------------------|-------------------| -|`PROV_RSA_FULL`|1| -|`PROV_RSA_SIG`|2| -|`PROV_DSS`|3| -|`PROV_FORTEZZA`|4| -|`PROV_MS_EXCHANGE`|5| -|`PROV_SSL`|6| -|`PROV_RSA_SCHANNEL`|12| -|`PROV_DSS_DH`|13| -|`PROV_EC_ECDSA_SIG`|14| -|`PROV_EC_ECNRA_SIG`|15| -|`PROV_EC_ECDSA_FULL`|16| -|`PROV_EC_ECNRA_FULL`|17| -|`PROV_DH_SCHANNEL`|18| -|`PROV_SPYRUS_LYNKS`|20| -|`PROV_RNG`|21| -|`PROV_INTEL_SEC`|22| -|`PROV_REPLACE_OWF`|23| -|`PROV_RSA_AES`|24| - + field to specify a provider type by passing a numeric value that represents that provider. The numeric values that represent the default provider types are defined in the WinCrypt.h header file: + +- To specify a provider compatible with the class, pass a value of `1`. + +- To specify a provider compatible with the class, pass a value of `13`. + + The following table lists the provider types and their corresponding numeric values defined in the WinCrypt.h header file. + +|Provider Type|Numeric Value| +|-------------------|-------------------| +|`PROV_RSA_FULL`|1| +|`PROV_RSA_SIG`|2| +|`PROV_DSS`|3| +|`PROV_FORTEZZA`|4| +|`PROV_MS_EXCHANGE`|5| +|`PROV_SSL`|6| +|`PROV_RSA_SCHANNEL`|12| +|`PROV_DSS_DH`|13| +|`PROV_EC_ECDSA_SIG`|14| +|`PROV_EC_ECNRA_SIG`|15| +|`PROV_EC_ECDSA_FULL`|16| +|`PROV_EC_ECNRA_FULL`|17| +|`PROV_DH_SCHANNEL`|18| +|`PROV_SPYRUS_LYNKS`|20| +|`PROV_RNG`|21| +|`PROV_INTEL_SEC`|22| +|`PROV_REPLACE_OWF`|23| +|`PROV_RSA_AES`|24| + For more information about the default provider types and their behaviors, see the [Microsoft Cryptography API (CAPI) documentation](/windows/win32/seccrypto/cryptography-reference). - + ]]> Cryptographic Services diff --git a/xml/System.Security.Permissions/KeyContainerPermissionAccessEntryCollection.xml b/xml/System.Security.Permissions/KeyContainerPermissionAccessEntryCollection.xml index 24a07393002..78afff164c5 100644 --- a/xml/System.Security.Permissions/KeyContainerPermissionAccessEntryCollection.xml +++ b/xml/System.Security.Permissions/KeyContainerPermissionAccessEntryCollection.xml @@ -51,14 +51,14 @@ Represents a collection of objects. This class cannot be inherited. - objects specify access rights for specific key containers. - + objects specify access rights for specific key containers. + ]]> @@ -124,11 +124,11 @@ Adds a object to the collection. The index at which the new element was inserted. - object is added to the end of the collection. - + object is added to the end of the collection. + ]]> @@ -167,11 +167,11 @@ Removes all the objects from the collection. - . - + . + ]]> @@ -254,10 +254,10 @@ is less than the lower bound of . - is multidimensional. - - -or- - + is multidimensional. + + -or- + The number of elements in the collection is greater than the available space from to the end of the destination . @@ -297,11 +297,11 @@ Gets the number of items in the collection. The number of objects in the collection. - property to determine the number of objects in the collection. The property is commonly used when iterating through the collection to determine the upper bound of the collection. - + property to determine the number of objects in the collection. The property is commonly used when iterating through the collection to determine the upper bound of the collection. + ]]> @@ -342,20 +342,20 @@ Returns a object that can be used to iterate through the objects in the collection. A object that can be used to iterate through the collection. - object that can be used to iterate through the collection to get each item. - - Use the property of the enumerator to get the item currently pointed to in the collection. - - Use the method of the enumerator to move to the next item in the collection. - - Use the method of the enumerator to move to the initial position. - + object that can be used to iterate through the collection to get each item. + + Use the property of the enumerator to get the item currently pointed to in the collection. + + Use the method of the enumerator to move to the next item in the collection. + + Use the method of the enumerator to move to the initial position. + > [!NOTE] -> After you create a object or use the method to move the enumerator to the first item in the collection, you must call the method. Otherwise, the item represented by the property is undefined. - +> After you create a object or use the method to move the enumerator to the first item in the collection, you must call the method. Otherwise, the item represented by the property is undefined. + ]]> @@ -397,11 +397,11 @@ Gets the index in the collection of the specified object, if it exists in the collection. The index of the specified object in the collection, or -1 if no match is found. - object in the collection. If the specified object is not found, an value of -1 is returned. - + object in the collection. If the specified object is not found, an value of -1 is returned. + ]]> @@ -442,11 +442,11 @@ in all cases. - property and always returns `false`. - + property and always returns `false`. + ]]> @@ -489,11 +489,11 @@ Gets the item at the specified index in the collection. The object at the specified index in the collection. - object from the at the specified index, using array notation. - + object from the at the specified index, using array notation. + ]]> @@ -538,11 +538,11 @@ The object to remove. Removes the specified object from the collection. - method. - + method. + ]]> @@ -584,13 +584,13 @@ Gets an object that can be used to synchronize access to the collection. An object that can be used to synchronize access to the collection. - object itself. - - For more information on the property, see the property of the interface. - + object itself. + + For more information on the property, see the property of the interface. + ]]> @@ -620,8 +620,8 @@ System.Void - - + + The one-dimensional array that is the destination of the elements copied from the current collection. @@ -633,10 +633,10 @@ is less than the lower bound of . - is multidimensional. - - -or- - + is multidimensional. + + -or- + The number of elements in the collection is greater than the available space from to the end of the destination . diff --git a/xml/System.Security.Principal/WindowsIdentity.xml b/xml/System.Security.Principal/WindowsIdentity.xml index 07445b14584..87338147ebe 100644 --- a/xml/System.Security.Principal/WindowsIdentity.xml +++ b/xml/System.Security.Principal/WindowsIdentity.xml @@ -80,23 +80,23 @@ Represents a Windows user. - method to create a object that represents the current user. - + method to create a object that represents the current user. + > [!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. - - - -## Examples - The following example shows the use of members of class. For an example showing how to obtain a Windows account token through a call to the unmanaged Win32 `LogonUser` function, and use that token to impersonate another user, see the class. - +> 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. + + + +## Examples + The following example shows the use of members of class. For an example showing how to obtain a Windows account token through a call to the unmanaged Win32 `LogonUser` function, and use that token to impersonate another user, see the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Principal.WindowsIdentity_AllMembers/CPP/windowsidentitymembers.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Principal/WindowsAccountType/Overview/windowsidentitymembers.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Principal.WindowsIdentity_AllMembers/VB/Form1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Principal.WindowsIdentity_AllMembers/VB/Form1.vb" id="Snippet1"::: + ]]> @@ -148,32 +148,32 @@ The account token for the user on whose behalf the code is running. Initializes a new instance of the class for the user represented by the specified Windows account token. - . - -|Property|Initial value| -|--------------|-------------------| -||`Negotiate`| -||`Normal`| -||`false`| - + . + +|Property|Initial value| +|--------------|-------------------| +||`Negotiate`| +||`Normal`| +||`false`| + > [!NOTE] -> You can retrieve the token represented by `userToken` by calling unmanaged code such as the Windows API `LogonUser` function. Always release `userToken` by calling the Windows API `CloseHandle` function. For more information on calling unmanaged code, see [Consuming Unmanaged DLL Functions](/dotnet/framework/interop/consuming-unmanaged-dll-functions). - +> You can retrieve the token represented by `userToken` by calling unmanaged code such as the Windows API `LogonUser` function. Always release `userToken` by calling the Windows API `CloseHandle` function. For more information on calling unmanaged code, see [Consuming Unmanaged DLL Functions](/dotnet/framework/interop/consuming-unmanaged-dll-functions). + ]]> - is 0. - - -or- - + is 0. + + -or- + is duplicated and invalid for impersonation. - The caller does not have the correct permissions. - - -or- - + The caller does not have the correct permissions. + + -or- + A Win32 error occurred. @@ -251,30 +251,30 @@ The UPN for the user on whose behalf the code is running. Initializes a new instance of the class for the user represented by the specified User Principal Name (UPN). - [!NOTE] > This constructor is intended for use only on computers joined to Windows Server 2003 or later domains. An exception is thrown for earlier domain types. This restriction is due to the fact that this constructor uses the [KERB_S4U_LOGON structure](https://go.microsoft.com/fwlink/?LinkId=143533), which was first introduced in Windows Server 2003. Also, this constructor requires read access to the [token-groups-global-and-universal (TGGAU) attribute](https://support.microsoft.com/en-us/help/331951/some-applications-and-apis-require-access-to-authorization-information) on the target user account. - + ]]> Windows returned the Windows NT status code STATUS_ACCESS_DENIED. There is insufficient memory available. - The caller does not have the correct permissions. - - -or- - - The computer is not attached to a Windows 2003 or later domain. - - -or- - - The computer is not running Windows 2003 or later. - - -or- - + The caller does not have the correct permissions. + + -or- + + The computer is not attached to a Windows 2003 or later domain. + + -or- + + The computer is not running Windows 2003 or later. + + -or- + The user is not a member of the domain the computer is attached to. @@ -318,42 +318,42 @@ (Informational use only.) The type of authentication used to identify the user. Initializes a new instance of the class for the user represented by the specified Windows account token and the specified authentication type. - . - -|Property|Initial value| -|--------------|-------------------| -||`Normal`| -||`false`| - - The value of the `type` parameter is used to set the parameter. If `type` is `null`, the security system sets to `Negotiate` on Windows Vista and later versions of the Windows operating system, and to `Kerberos` on earlier versions of the Windows operating system. The security system does not use this value; it is for informational use only. - + . + +|Property|Initial value| +|--------------|-------------------| +||`Normal`| +||`false`| + + The value of the `type` parameter is used to set the parameter. If `type` is `null`, the security system sets to `Negotiate` on Windows Vista and later versions of the Windows operating system, and to `Kerberos` on earlier versions of the Windows operating system. The security system does not use this value; it is for informational use only. + > [!NOTE] -> You can retrieve the token represented by `userToken` by calling unmanaged code such as the Windows API `LogonUser` function. Always release `userToken` by calling the Windows API `CloseHandle` function. For more information on calling unmanaged code, see [Consuming Unmanaged DLL Functions](/dotnet/framework/interop/consuming-unmanaged-dll-functions). - - - -## Examples - The following code shows the use of the constructor to create a new instance of the class for the user represented by the specified Windows account token and the specified authentication type. This code example is part of a larger example provided for the class. - +> You can retrieve the token represented by `userToken` by calling unmanaged code such as the Windows API `LogonUser` function. Always release `userToken` by calling the Windows API `CloseHandle` function. For more information on calling unmanaged code, see [Consuming Unmanaged DLL Functions](/dotnet/framework/interop/consuming-unmanaged-dll-functions). + + + +## Examples + The following code shows the use of the constructor to create a new instance of the class for the user represented by the specified Windows account token and the specified authentication type. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Principal.WindowsIdentity_AllMembers/CPP/windowsidentitymembers.cpp" id="Snippet4"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Principal/WindowsAccountType/Overview/windowsidentitymembers.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Principal.WindowsIdentity_AllMembers/VB/Form1.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Principal.WindowsIdentity_AllMembers/VB/Form1.vb" id="Snippet4"::: + ]]> - is 0. - - -or- - + is 0. + + -or- + is duplicated and invalid for impersonation. - The caller does not have the correct permissions. - - -or- - + The caller does not have the correct permissions. + + -or- + A Win32 error occurred.
@@ -404,19 +404,19 @@ An object that indicates the stream characteristics. Initializes a new instance of the class for the user represented by information in a stream. - A cannot be serialized across processes. - The caller does not have the correct permissions. - - -or- - + The caller does not have the correct permissions. + + -or- + A Win32 error occurred.
@@ -444,40 +444,40 @@ - - + + The UPN for the user on whose behalf the code is running. (Informational use only.) The type of authentication used to identify the user. Initializes a new instance of the class for the user represented by the specified User Principal Name (UPN) and the specified authentication type. - parameter. If `type` is `null`, the security system sets to `Negotiate` on Windows Vista and later versions of the Windows operating system, and to `Kerberos` on earlier versions of the Windows operating system. The security system does not use this value; it is for informational use only. - - The UPN identified in `sUserPrincipalName` is used to retrieve a token for that user through the Windows API `LsaLogonUser` function. In turn that token is used to identify the user. An exception might be returned due to the inability to log on using the supplied UPN. - + parameter. If `type` is `null`, the security system sets to `Negotiate` on Windows Vista and later versions of the Windows operating system, and to `Kerberos` on earlier versions of the Windows operating system. The security system does not use this value; it is for informational use only. + + The UPN identified in `sUserPrincipalName` is used to retrieve a token for that user through the Windows API `LsaLogonUser` function. In turn that token is used to identify the user. An exception might be returned due to the inability to log on using the supplied UPN. + > [!NOTE] > This constructor is intended for use only on computers joined to Windows Server 2003 or later domains. An exception is thrown for earlier domain types. This restriction is due to the fact that this constructor uses the [KERB_S4U_LOGON structure](https://go.microsoft.com/fwlink/?LinkId=143533), which was first introduced in Windows Server 2003. Also, this constructor requires read access to the [token-groups-global-and-universal (TGGAU) attribute](https://support.microsoft.com/en-us/help/331951/some-applications-and-apis-require-access-to-authorization-information) on the target user account. - + ]]> Windows returned the Windows NT status code STATUS_ACCESS_DENIED. There is insufficient memory available. - The caller does not have the correct permissions. - - -or- - - The computer is not attached to a Windows 2003 or later domain. - - -or- - - The computer is not running Windows 2003 or later. - - -or- - + The caller does not have the correct permissions. + + -or- + + The computer is not attached to a Windows 2003 or later domain. + + -or- + + The computer is not running Windows 2003 or later. + + -or- + The user is not a member of the domain the computer is attached to. @@ -512,9 +512,9 @@ - - - + + + The account token for the user on whose behalf the code is running. @@ -522,41 +522,41 @@ One of the enumeration values. Initializes a new instance of the class for the user represented by the specified Windows account token, the specified authentication type, and the specified Windows account type. - . - -|Property|Initial Value| -|--------------|-------------------| -||`false`| - - The value of the `type` parameter is used to set the parameter. If `type` is `null`, the security system sets to `Negotiate` on Windows Vista and later versions of the Windows operating system, and to `Kerberos` on earlier versions of the Windows operating system. The security system does not use this value; it is for informational use only. - + . + +|Property|Initial Value| +|--------------|-------------------| +||`false`| + + The value of the `type` parameter is used to set the parameter. If `type` is `null`, the security system sets to `Negotiate` on Windows Vista and later versions of the Windows operating system, and to `Kerberos` on earlier versions of the Windows operating system. The security system does not use this value; it is for informational use only. + > [!NOTE] -> You can retrieve the token represented by `userToken` by calling unmanaged code such as the Windows API `LogonUser` function. Always release `userToken` by calling the Windows API `CloseHandle` function. For more information on calling unmanaged code, see [Consuming Unmanaged DLL Functions](/dotnet/framework/interop/consuming-unmanaged-dll-functions). - - - -## Examples - The following code shows the use of the constructor to create a new instance of the class for the user represented by the specified Windows account token, the specified authentication type, and the specified Windows account type. This code example is part of a larger example provided for the class. - +> You can retrieve the token represented by `userToken` by calling unmanaged code such as the Windows API `LogonUser` function. Always release `userToken` by calling the Windows API `CloseHandle` function. For more information on calling unmanaged code, see [Consuming Unmanaged DLL Functions](/dotnet/framework/interop/consuming-unmanaged-dll-functions). + + + +## Examples + The following code shows the use of the constructor to create a new instance of the class for the user represented by the specified Windows account token, the specified authentication type, and the specified Windows account type. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Principal.WindowsIdentity_AllMembers/CPP/windowsidentitymembers.cpp" id="Snippet7"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Principal/WindowsAccountType/Overview/windowsidentitymembers.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Principal.WindowsIdentity_AllMembers/VB/Form1.vb" id="Snippet7"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Principal.WindowsIdentity_AllMembers/VB/Form1.vb" id="Snippet7"::: + ]]> - is 0. - - -or- - + is 0. + + -or- + is duplicated and invalid for impersonation. - The caller does not have the correct permissions. - - -or- - + The caller does not have the correct permissions. + + -or- + A Win32 error occurred. @@ -591,10 +591,10 @@ - - - - + + + + The account token for the user on whose behalf the code is running. @@ -604,34 +604,34 @@ to indicate that the user is authenticated; otherwise, . Initializes a new instance of the class for the user represented by the specified Windows account token, the specified authentication type, the specified Windows account type, and the specified authentication status. - parameter. If `type` is `null`, the security system sets to `Negotiate` on Windows Vista and later versions of the Windows operating system, and to `Kerberos` on earlier versions of the Windows operating system. The security system does not use this value; it is for informational use only. - - You can retrieve the token represented by `userToken` by calling unmanaged code such as the Windows API `LogonUser` function. Always release `userToken` by calling the Windows API `CloseHandle` function. For more information on calling unmanaged code, see [Consuming Unmanaged DLL Functions](/dotnet/framework/interop/consuming-unmanaged-dll-functions). - - - -## Examples - The following code shows the use of the constructor to create a new instance of the class for the user represented by the specified Windows account token, the specified authentication type, the specified Windows account type, and the specified authentication status. This code example is part of a larger example provided for the class. - + parameter. If `type` is `null`, the security system sets to `Negotiate` on Windows Vista and later versions of the Windows operating system, and to `Kerberos` on earlier versions of the Windows operating system. The security system does not use this value; it is for informational use only. + + You can retrieve the token represented by `userToken` by calling unmanaged code such as the Windows API `LogonUser` function. Always release `userToken` by calling the Windows API `CloseHandle` function. For more information on calling unmanaged code, see [Consuming Unmanaged DLL Functions](/dotnet/framework/interop/consuming-unmanaged-dll-functions). + + + +## Examples + The following code shows the use of the constructor to create a new instance of the class for the user represented by the specified Windows account token, the specified authentication type, the specified Windows account type, and the specified authentication status. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Principal.WindowsIdentity_AllMembers/CPP/windowsidentitymembers.cpp" id="Snippet17"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Principal/WindowsAccountType/Overview/windowsidentitymembers.cs" id="Snippet17"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Principal.WindowsIdentity_AllMembers/VB/Form1.vb" id="Snippet17"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Principal.WindowsIdentity_AllMembers/VB/Form1.vb" id="Snippet17"::: + ]]> - is 0. - - -or- - + is 0. + + -or- + is duplicated and invalid for impersonation. - The caller does not have the correct permissions. - - -or- - + The caller does not have the correct permissions. + + -or- + A Win32 error occurred. @@ -728,27 +728,27 @@ Gets the type of authentication used to identify the user. The type of authentication used to identify the user. - Windows returned the Windows NT status code STATUS_ACCESS_DENIED. There is insufficient memory available. - The caller does not have the correct permissions. - - -or- - - The computer is not attached to a Windows 2003 or later domain. - - -or- - - The computer is not running Windows 2003 or later. - - -or- - + The caller does not have the correct permissions. + + -or- + + The computer is not attached to a Windows 2003 or later domain. + + -or- + + The computer is not running Windows 2003 or later. + + -or- + The user is not a member of the domain the computer is attached to.
@@ -939,14 +939,14 @@ Releases all resources used by the . - 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). - + 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. + ]]> @@ -996,19 +996,19 @@ to release both managed and unmanaged resources; to release only unmanaged resources. Releases the unmanaged resources used by the and optionally releases the managed resources. - method, if it has been overridden. `Dispose()` invokes this method with the `disposing` parameter set to `true`. `Finalize` invokes this method with `disposing` set to `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. - + + 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. + ]]> - can be called multiple times by other objects. When overriding be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). - + can be called multiple times by other objects. When overriding be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). + For more information about and , see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged).
@@ -1037,7 +1037,7 @@ [!NOTE] > This member is removed in the .NET Framework version 2.0 and subsequent versions. @@ -1088,22 +1088,22 @@ Application code does not call this method; it is automatically invoked during g Returns a object that you can use as a sentinel value in your code to represent an anonymous user. The property value does not represent the built-in anonymous identity used by the Windows operating system. An object that represents an anonymous user. - object that enables you to treat operations as anonymous. The property value does not correspond to a Windows anonymous user and cannot be used for impersonation. Also, note that the identity returned by this property is not static; each call to returns a different anonymous identity. - - You can use the property to detect the return value from . However, detects both the Windows anonymous identity and the anonymous identity returned by this method. To use the latter identity, cache the return value instead of relying on the property. - - - -## Examples - The following code shows the use of the method to return a object that represents an anonymous Windows user. This code example is part of a larger example provided for the class. - + object that enables you to treat operations as anonymous. The property value does not correspond to a Windows anonymous user and cannot be used for impersonation. Also, note that the identity returned by this property is not static; each call to returns a different anonymous identity. + + You can use the property to detect the return value from . However, detects both the Windows anonymous identity and the anonymous identity returned by this method. To use the latter identity, cache the return value instead of relying on the property. + + + +## Examples + The following code shows the use of the method to return a object that represents an anonymous Windows user. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Principal.WindowsIdentity_AllMembers/CPP/windowsidentitymembers.cpp" id="Snippet15"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Principal/WindowsAccountType/Overview/windowsidentitymembers.cs" id="Snippet15"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Principal.WindowsIdentity_AllMembers/VB/Form1.vb" id="Snippet15"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Principal.WindowsIdentity_AllMembers/VB/Form1.vb" id="Snippet15"::: + ]]>
@@ -1156,15 +1156,15 @@ Application code does not call this method; it is automatically invoked during g Returns a object that represents the current Windows user. An object that represents the current user. - method to return a object that represents the current Windows user. This code example is part of a larger example provided for the class. - + method to return a object that represents the current Windows user. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Principal.WindowsIdentity_AllMembers/CPP/windowsidentitymembers.cpp" id="Snippet13"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Principal/WindowsAccountType/Overview/windowsidentitymembers.cs" id="Snippet13"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Principal.WindowsIdentity_AllMembers/VB/Form1.vb" id="Snippet13"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Principal.WindowsIdentity_AllMembers/VB/Form1.vb" id="Snippet13"::: + ]]> The caller does not have the correct permissions. @@ -1217,11 +1217,11 @@ Application code does not call this method; it is automatically invoked during g Returns a object that represents the Windows identity for either the thread or the process, depending on the value of the parameter. An object that represents a Windows user. - object has no value. If `ifImpersonating` is `false` and the thread is impersonating, the for the thread is returned. If `ifImpersonating` is `false` and the thread is not impersonating, the for the process is returned. - + object has no value. If `ifImpersonating` is `false` and the thread is impersonating, the for the thread is returned. If `ifImpersonating` is `false` and the thread is not impersonating, the for the process is returned. + ]]>
@@ -1267,11 +1267,11 @@ Application code does not call this method; it is automatically invoked during g Returns a object that represents the current Windows user, using the specified desired token access level. An object that represents the current user. -
@@ -1322,14 +1322,14 @@ Application code does not call this method; it is automatically invoked during g Gets the groups the current Windows user belongs to. An object representing the groups the current Windows user belongs to. - property to display the identity references for the groups the current user belongs to. This code example is part of a larger example provided for the class. - + property to display the identity references for the groups the current user belongs to. This code example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/System.Security.Principal/WindowsAccountType/Overview/windowsidentitymembers.cs" id="Snippet20"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Principal.WindowsIdentity_AllMembers/VB/Form1.vb" id="Snippet20"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Principal.WindowsIdentity_AllMembers/VB/Form1.vb" id="Snippet20"::: + ]]>
@@ -1375,23 +1375,23 @@ Application code does not call this method; it is automatically invoked during g Impersonates the user represented by the object. An object that represents the Windows user prior to impersonation; this can be used to revert to the original user's context. - [!WARNING] -> Avoid using this method with the async/await pattern. In some cases it may lead to reliability issues due to impersonation not being reverted even if the resulting `WindowsImpersonationContext` is disposed. Use `RunImpersonated` instead. - - - -## Examples - The following example demonstrates how to obtain a Windows account token by calling the unmanaged Win32 `LogonUser` function, and how to use that token to impersonate another user and then revert to the original identity. - +> Avoid using this method with the async/await pattern. In some cases it may lead to reliability issues due to impersonation not being reverted even if the resulting `WindowsImpersonationContext` is disposed. Use `RunImpersonated` instead. + + + +## Examples + The following example demonstrates how to obtain a Windows account token by calling the unmanaged Win32 `LogonUser` function, and how to use that token to impersonate another user and then revert to the original identity. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/WindowsIdentity Impersonation/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Principal/WindowsIdentity/Impersonate/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/WindowsIdentity Impersonation/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/WindowsIdentity Impersonation/VB/source.vb" id="Snippet1"::: + ]]> An anonymous identity attempted to perform an impersonation. @@ -1428,34 +1428,34 @@ Application code does not call this method; it is automatically invoked during g System.Security.Principal.WindowsImpersonationContext - + The handle of a Windows account token. This token is usually retrieved through a call to unmanaged code, such as a call to the Windows API function. Impersonates the user represented by the specified user token. An object that represents the Windows user prior to impersonation; this object can be used to revert to the original user's context. - [!NOTE] -> Calling the method with a `userToken` value of is equivalent to calling the Win32 `RevertToSelf` function. If another user is currently being impersonated, control reverts to the original user. - - For more information about calls to unmanaged code, see [Consuming Unmanaged DLL Functions](/dotnet/framework/interop/consuming-unmanaged-dll-functions). - +> Calling the method with a `userToken` value of is equivalent to calling the Win32 `RevertToSelf` function. If another user is currently being impersonated, control reverts to the original user. + + For more information about calls to unmanaged code, see [Consuming Unmanaged DLL Functions](/dotnet/framework/interop/consuming-unmanaged-dll-functions). + > [!WARNING] -> Avoid using this method with the async/await pattern. In some cases it may lead to reliability issues due to impersonation not being reverted even if the resulting `WindowsImpersonationContext` is disposed. Use `RunImpersonated` instead. - - - -## Examples - The following example demonstrates how to obtain a Windows account token by calling the unmanaged Win32 `LogonUser` function, and how to use that token to impersonate another user and then revert to the original identity. - +> Avoid using this method with the async/await pattern. In some cases it may lead to reliability issues due to impersonation not being reverted even if the resulting `WindowsImpersonationContext` is disposed. Use `RunImpersonated` instead. + + + +## Examples + The following example demonstrates how to obtain a Windows account token by calling the unmanaged Win32 `LogonUser` function, and how to use that token to impersonate another user and then revert to the original identity. + :::code language="csharp" source="~/snippets/csharp/System.Security.Principal/WindowsIdentity/Impersonate/source1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/windowsidentity impersonation2/vb/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/windowsidentity impersonation2/vb/source.vb" id="Snippet1"::: + ]]> Windows returned the Windows NT status code STATUS_ACCESS_DENIED. @@ -1507,19 +1507,19 @@ Application code does not call this method; it is automatically invoked during g Gets the impersonation level for the user. One of the enumeration values that specifies the impersonation level. - property to display the impersonation level for the current user. This code example is part of a larger example provided for the class. - + property to display the impersonation level for the current user. This code example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/System.Security.Principal/WindowsAccountType/Overview/windowsidentitymembers.cs" id="Snippet21"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Principal.WindowsIdentity_AllMembers/VB/Form1.vb" id="Snippet21"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Principal.WindowsIdentity_AllMembers/VB/Form1.vb" id="Snippet21"::: + ]]> @@ -1563,22 +1563,22 @@ Application code does not call this method; it is automatically invoked during g if the user account is an anonymous account; otherwise, . - property detects both the Windows anonymous identity and the anonymous identity that is returned by the method. - - Anonymous accounts are typically only encountered only from within ASP.NET-based applications when anonymous access is allowed by Internet Information Services (IIS). - - - -## Examples - The following code shows the use of the property to detect whether the user account is identified as an anonymous account by the system. This code example is part of a larger example provided for the class. - + property detects both the Windows anonymous identity and the anonymous identity that is returned by the method. + + Anonymous accounts are typically only encountered only from within ASP.NET-based applications when anonymous access is allowed by Internet Information Services (IIS). + + + +## Examples + The following code shows the use of the property to detect whether the user account is identified as an anonymous account by the system. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Principal.WindowsIdentity_AllMembers/CPP/windowsidentitymembers.cpp" id="Snippet9"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Principal/WindowsAccountType/Overview/windowsidentitymembers.cs" id="Snippet9"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Principal.WindowsIdentity_AllMembers/VB/Form1.vb" id="Snippet9"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Principal.WindowsIdentity_AllMembers/VB/Form1.vb" id="Snippet9"::: + ]]>
@@ -1662,15 +1662,15 @@ Application code does not call this method; it is automatically invoked during g if the user account is a account; otherwise, . - property to return a value indicating whether the user account is identified as a account by the system. This code example is part of a larger example provided for the class. - + property to return a value indicating whether the user account is identified as a account by the system. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Principal.WindowsIdentity_AllMembers/CPP/windowsidentitymembers.cpp" id="Snippet12"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Principal/WindowsAccountType/Overview/windowsidentitymembers.cs" id="Snippet12"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Principal.WindowsIdentity_AllMembers/VB/Form1.vb" id="Snippet12"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Principal.WindowsIdentity_AllMembers/VB/Form1.vb" id="Snippet12"::: + ]]>
@@ -1714,15 +1714,15 @@ Application code does not call this method; it is automatically invoked during g if the user account is a account; otherwise, . - property to return a value indicating whether the user account is identified as a account by the system. This code example is part of a larger example provided for the class. - + property to return a value indicating whether the user account is identified as a account by the system. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Principal.WindowsIdentity_AllMembers/CPP/windowsidentitymembers.cpp" id="Snippet11"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Principal/WindowsAccountType/Overview/windowsidentitymembers.cs" id="Snippet11"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Principal.WindowsIdentity_AllMembers/VB/Form1.vb" id="Snippet11"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Principal.WindowsIdentity_AllMembers/VB/Form1.vb" id="Snippet11"::: + ]]>
@@ -1770,20 +1770,20 @@ Application code does not call this method; it is automatically invoked during g Gets the user's Windows logon name. The Windows logon name of the user on whose behalf the code is being run. - property to get the user's Windows logon name. This code example is part of a larger example provided for the class. - + property to get the user's Windows logon name. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Principal.WindowsIdentity_AllMembers/CPP/windowsidentitymembers.cpp" id="Snippet8"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Principal/WindowsAccountType/Overview/windowsidentitymembers.cs" id="Snippet8"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Principal.WindowsIdentity_AllMembers/VB/Form1.vb" id="Snippet8"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Principal.WindowsIdentity_AllMembers/VB/Form1.vb" id="Snippet8"::: + ]]>
@@ -1838,19 +1838,19 @@ Application code does not call this method; it is automatically invoked during g Gets the security identifier (SID) for the token owner. An object for the token owner. - property to display the security identifier for the token owner. This code example is part of a larger example provided for the class - + property to display the security identifier for the token owner. This code example is part of a larger example provided for the class + :::code language="csharp" source="~/snippets/csharp/System.Security.Principal/WindowsAccountType/Overview/windowsidentitymembers.cs" id="Snippet19"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Principal.WindowsIdentity_AllMembers/VB/Form1.vb" id="Snippet19"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Principal.WindowsIdentity_AllMembers/VB/Form1.vb" id="Snippet19"::: + ]]>
@@ -1896,93 +1896,93 @@ Application code does not call this method; it is automatically invoked during g The System.Action to run. Runs the specified action as the impersonated Windows identity. Instead of using an impersonated method call and running your function in , you can use and provide your function directly as a parameter. - [!NOTE] -> This method may be used reliably with the async/await pattern, unlike `Impersonate`. In an async method, the generic overload of this method may be used with an async delegate argument so that the resulting task may be awaited. - - - -## Examples - The following example demonstrates the use of the class to impersonate a user. - +> This method may be used reliably with the async/await pattern, unlike `Impersonate`. In an async method, the generic overload of this method may be used with an async delegate argument so that the resulting task may be awaited. + + + +## Examples + The following example demonstrates the use of the class to impersonate a user. + > [!WARNING] -> This sample asks the user to enter a password on the console screen. The password will be visible on the screen, because the console window does not support masked input natively. - -```csharp -// The following example demonstrates the use of the WindowsIdentity class to impersonate a user. -// IMPORTANT NOTE: -// This sample asks the user to enter a password on the console screen. -// The password will be visible on the screen, because the console window -// does not support masked input natively. - -using System; -using System.Runtime.InteropServices; -using System.Security; -using System.Security.Principal; -using Microsoft.Win32.SafeHandles; - -public class ImpersonationDemo -{ - [DllImport("advapi32.dll", SetLastError = true, CharSet = CharSet.Unicode)] - public static extern bool LogonUser(String lpszUsername, String lpszDomain, String lpszPassword, - int dwLogonType, int dwLogonProvider, out SafeAccessTokenHandle phToken); - - public static void Main() - { - // Get the user token for the specified user, domain, and password using the - // unmanaged LogonUser method. - // The local machine name can be used for the domain name to impersonate a user on this machine. - Console.Write("Enter the name of the domain on which to log on: "); - string domainName = Console.ReadLine(); - - Console.Write("Enter the login of a user on {0} that you wish to impersonate: ", domainName); - string userName = Console.ReadLine(); - - Console.Write("Enter the password for {0}: ", userName); - - const int LOGON32_PROVIDER_DEFAULT = 0; - //This parameter causes LogonUser to create a primary token. - const int LOGON32_LOGON_INTERACTIVE = 2; - - // Call LogonUser to obtain a handle to an access token. - SafeAccessTokenHandle safeAccessTokenHandle; - bool returnValue = LogonUser(userName, domainName, Console.ReadLine(), - LOGON32_LOGON_INTERACTIVE, LOGON32_PROVIDER_DEFAULT, - out safeAccessTokenHandle); - - if (false == returnValue) - { - int ret = Marshal.GetLastWin32Error(); - Console.WriteLine("LogonUser failed with error code : {0}", ret); - throw new System.ComponentModel.Win32Exception(ret); - } - - Console.WriteLine("Did LogonUser Succeed? " + (returnValue ? "Yes" : "No")); - // Check the identity. - Console.WriteLine("Before impersonation: " + WindowsIdentity.GetCurrent().Name); - - // Note: if you want to run as unimpersonated, pass - // 'SafeAccessTokenHandle.InvalidHandle' instead of variable 'safeAccessTokenHandle' - WindowsIdentity.RunImpersonated( - safeAccessTokenHandle, - // User action - () => - { - // Check the identity. - Console.WriteLine("During impersonation: " + WindowsIdentity.GetCurrent().Name); - } - ); - - // Check the identity again. - Console.WriteLine("After impersonation: " + WindowsIdentity.GetCurrent().Name); - } -} - -``` - +> This sample asks the user to enter a password on the console screen. The password will be visible on the screen, because the console window does not support masked input natively. + +```csharp +// The following example demonstrates the use of the WindowsIdentity class to impersonate a user. +// IMPORTANT NOTE: +// This sample asks the user to enter a password on the console screen. +// The password will be visible on the screen, because the console window +// does not support masked input natively. + +using System; +using System.Runtime.InteropServices; +using System.Security; +using System.Security.Principal; +using Microsoft.Win32.SafeHandles; + +public class ImpersonationDemo +{ + [DllImport("advapi32.dll", SetLastError = true, CharSet = CharSet.Unicode)] + public static extern bool LogonUser(String lpszUsername, String lpszDomain, String lpszPassword, + int dwLogonType, int dwLogonProvider, out SafeAccessTokenHandle phToken); + + public static void Main() + { + // Get the user token for the specified user, domain, and password using the + // unmanaged LogonUser method. + // The local machine name can be used for the domain name to impersonate a user on this machine. + Console.Write("Enter the name of the domain on which to log on: "); + string domainName = Console.ReadLine(); + + Console.Write("Enter the login of a user on {0} that you wish to impersonate: ", domainName); + string userName = Console.ReadLine(); + + Console.Write("Enter the password for {0}: ", userName); + + const int LOGON32_PROVIDER_DEFAULT = 0; + //This parameter causes LogonUser to create a primary token. + const int LOGON32_LOGON_INTERACTIVE = 2; + + // Call LogonUser to obtain a handle to an access token. + SafeAccessTokenHandle safeAccessTokenHandle; + bool returnValue = LogonUser(userName, domainName, Console.ReadLine(), + LOGON32_LOGON_INTERACTIVE, LOGON32_PROVIDER_DEFAULT, + out safeAccessTokenHandle); + + if (false == returnValue) + { + int ret = Marshal.GetLastWin32Error(); + Console.WriteLine("LogonUser failed with error code : {0}", ret); + throw new System.ComponentModel.Win32Exception(ret); + } + + Console.WriteLine("Did LogonUser Succeed? " + (returnValue ? "Yes" : "No")); + // Check the identity. + Console.WriteLine("Before impersonation: " + WindowsIdentity.GetCurrent().Name); + + // Note: if you want to run as unimpersonated, pass + // 'SafeAccessTokenHandle.InvalidHandle' instead of variable 'safeAccessTokenHandle' + WindowsIdentity.RunImpersonated( + safeAccessTokenHandle, + // User action + () => + { + // Check the identity. + Console.WriteLine("During impersonation: " + WindowsIdentity.GetCurrent().Name); + } + ); + + // Check the identity again. + Console.WriteLine("After impersonation: " + WindowsIdentity.GetCurrent().Name); + } +} + +``` + ]]>
@@ -2040,93 +2040,93 @@ public class ImpersonationDemo Runs the specified function as the impersonated Windows identity. Instead of using an impersonated method call and running your function in , you can use and provide your function directly as a parameter. The result of the function. - [!NOTE] -> This method may be used reliably with the async/await pattern, unlike `Impersonate`. In an async method, this method may be used with an async delegate argument so that the resulting task may be awaited. - - - -## Examples - The following example demonstrates the use of the class to impersonate a user. - +> This method may be used reliably with the async/await pattern, unlike `Impersonate`. In an async method, this method may be used with an async delegate argument so that the resulting task may be awaited. + + + +## Examples + The following example demonstrates the use of the class to impersonate a user. + > [!WARNING] -> This sample asks the user to enter a password on the console screen. The password will be visible on the screen, because the console window does not support masked input natively. - -```csharp -// The following example demonstrates the use of the WindowsIdentity class to impersonate a user. -// IMPORTANT NOTE: -// This sample asks the user to enter a password on the console screen. -// The password will be visible on the screen, because the console window -// does not support masked input natively. - -using System; -using System.Runtime.InteropServices; -using System.Security; -using System.Security.Principal; -using Microsoft.Win32.SafeHandles; - -public class ImpersonationDemo -{ - [DllImport("advapi32.dll", SetLastError = true, CharSet = CharSet.Unicode)] - public static extern bool LogonUser(String lpszUsername, String lpszDomain, String lpszPassword, - int dwLogonType, int dwLogonProvider, out SafeAccessTokenHandle phToken); - - public static void Main() - { - // Get the user token for the specified user, domain, and password using the - // unmanaged LogonUser method. - // The local machine name can be used for the domain name to impersonate a user on this machine. - Console.Write("Enter the name of the domain on which to log on: "); - string domainName = Console.ReadLine(); - - Console.Write("Enter the login of a user on {0} that you wish to impersonate: ", domainName); - string userName = Console.ReadLine(); - - Console.Write("Enter the password for {0}: ", userName); - - const int LOGON32_PROVIDER_DEFAULT = 0; - //This parameter causes LogonUser to create a primary token. - const int LOGON32_LOGON_INTERACTIVE = 2; - - // Call LogonUser to obtain a handle to an access token. - SafeAccessTokenHandle safeAccessTokenHandle; - bool returnValue = LogonUser(userName, domainName, Console.ReadLine(), - LOGON32_LOGON_INTERACTIVE, LOGON32_PROVIDER_DEFAULT, - out safeAccessTokenHandle); - - if (false == returnValue) - { - int ret = Marshal.GetLastWin32Error(); - Console.WriteLine("LogonUser failed with error code : {0}", ret); - throw new System.ComponentModel.Win32Exception(ret); - } - - Console.WriteLine("Did LogonUser Succeed? " + (returnValue ? "Yes" : "No")); - // Check the identity. - Console.WriteLine("Before impersonation: " + WindowsIdentity.GetCurrent().Name); - - // Note: if you want to run as unimpersonated, pass - // 'SafeAccessTokenHandle.InvalidHandle' instead of variable 'safeAccessTokenHandle' - WindowsIdentity.RunImpersonated( - safeAccessTokenHandle, - // User action - () => - { - // Check the identity. - Console.WriteLine("During impersonation: " + WindowsIdentity.GetCurrent().Name); - } - ); - - // Check the identity again. - Console.WriteLine("After impersonation: " + WindowsIdentity.GetCurrent().Name); - } -} - -``` - +> This sample asks the user to enter a password on the console screen. The password will be visible on the screen, because the console window does not support masked input natively. + +```csharp +// The following example demonstrates the use of the WindowsIdentity class to impersonate a user. +// IMPORTANT NOTE: +// This sample asks the user to enter a password on the console screen. +// The password will be visible on the screen, because the console window +// does not support masked input natively. + +using System; +using System.Runtime.InteropServices; +using System.Security; +using System.Security.Principal; +using Microsoft.Win32.SafeHandles; + +public class ImpersonationDemo +{ + [DllImport("advapi32.dll", SetLastError = true, CharSet = CharSet.Unicode)] + public static extern bool LogonUser(String lpszUsername, String lpszDomain, String lpszPassword, + int dwLogonType, int dwLogonProvider, out SafeAccessTokenHandle phToken); + + public static void Main() + { + // Get the user token for the specified user, domain, and password using the + // unmanaged LogonUser method. + // The local machine name can be used for the domain name to impersonate a user on this machine. + Console.Write("Enter the name of the domain on which to log on: "); + string domainName = Console.ReadLine(); + + Console.Write("Enter the login of a user on {0} that you wish to impersonate: ", domainName); + string userName = Console.ReadLine(); + + Console.Write("Enter the password for {0}: ", userName); + + const int LOGON32_PROVIDER_DEFAULT = 0; + //This parameter causes LogonUser to create a primary token. + const int LOGON32_LOGON_INTERACTIVE = 2; + + // Call LogonUser to obtain a handle to an access token. + SafeAccessTokenHandle safeAccessTokenHandle; + bool returnValue = LogonUser(userName, domainName, Console.ReadLine(), + LOGON32_LOGON_INTERACTIVE, LOGON32_PROVIDER_DEFAULT, + out safeAccessTokenHandle); + + if (false == returnValue) + { + int ret = Marshal.GetLastWin32Error(); + Console.WriteLine("LogonUser failed with error code : {0}", ret); + throw new System.ComponentModel.Win32Exception(ret); + } + + Console.WriteLine("Did LogonUser Succeed? " + (returnValue ? "Yes" : "No")); + // Check the identity. + Console.WriteLine("Before impersonation: " + WindowsIdentity.GetCurrent().Name); + + // Note: if you want to run as unimpersonated, pass + // 'SafeAccessTokenHandle.InvalidHandle' instead of variable 'safeAccessTokenHandle' + WindowsIdentity.RunImpersonated( + safeAccessTokenHandle, + // User action + () => + { + // Check the identity. + Console.WriteLine("During impersonation: " + WindowsIdentity.GetCurrent().Name); + } + ); + + // Check the identity again. + Console.WriteLine("After impersonation: " + WindowsIdentity.GetCurrent().Name); + } +} + +``` + ]]>
@@ -2294,13 +2294,13 @@ public class ImpersonationDemo An object containing the source and destination of the serialized stream associated with the . Sets the object with the logical context information needed to recreate an instance of this execution context. - with the logical call context information. During deserialization, the execution context object is reconstituted from the transmitted over the stream. - - For more information, see . - + with the logical call context information. During deserialization, the execution context object is reconstituted from the transmitted over the stream. + + For more information, see . + ]]>
@@ -2342,23 +2342,23 @@ public class ImpersonationDemo Gets the Windows account token for the user. The handle of the access token associated with the current execution thread. - property. The token is released by the method, which you can call in code. is also automatically called by the garbage collector. - + property. The token is released by the method, which you can call in code. is also automatically called by the garbage collector. + > [!NOTE] -> The account token that is returned by the property is a duplicate of the Windows token that is used to create the object and is automatically released by the .NET Framework. This is different from the account token (the `userToken` parameter for the constructor), which is used to create the object. `userToken` is a Windows account token that is created by a call to `LogonUser` and must be closed to avoid a memory leak. - - - -## Examples - The following code shows the use of the property to get the Windows account token for the user. This code example is part of a larger example provided for the class. - +> The account token that is returned by the property is a duplicate of the Windows token that is used to create the object and is automatically released by the .NET Framework. This is different from the account token (the `userToken` parameter for the constructor), which is used to create the object. `userToken` is a Windows account token that is created by a call to `LogonUser` and must be closed to avoid a memory leak. + + + +## Examples + The following code shows the use of the property to get the Windows account token for the user. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Principal.WindowsIdentity_AllMembers/CPP/windowsidentitymembers.cpp" id="Snippet14"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Principal/WindowsAccountType/Overview/windowsidentitymembers.cs" id="Snippet14"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Principal.WindowsIdentity_AllMembers/VB/Form1.vb" id="Snippet14"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Principal.WindowsIdentity_AllMembers/VB/Form1.vb" id="Snippet14"::: + ]]>
@@ -2413,14 +2413,14 @@ public class ImpersonationDemo Gets the security identifier (SID) for the user. An object for the user. - [!NOTE] -> The object returned by the method is not the same as the Windows anonymous user. This property gets `null` for an anonymous user represented by the object returned by the method; it does not get the SID representing an anonymous Windows user. - +> The object returned by the method is not the same as the Windows anonymous user. This property gets `null` for an anonymous user represented by the object returned by the method; it does not get the SID representing an anonymous Windows user. + ]]>
diff --git a/xml/System.Security.Principal/WindowsImpersonationContext.xml b/xml/System.Security.Principal/WindowsImpersonationContext.xml index e6623d893a2..733f3a74fbd 100644 --- a/xml/System.Security.Principal/WindowsImpersonationContext.xml +++ b/xml/System.Security.Principal/WindowsImpersonationContext.xml @@ -34,23 +34,23 @@ Represents the Windows user prior to an impersonation operation. - [!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. - - - -## Examples - The following example demonstrates how to impersonate a user and then revert to the original identity. - +> 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. + + + +## Examples + The following example demonstrates how to impersonate a user and then revert to the original identity. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/WindowsIdentity Impersonation/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Principal/WindowsIdentity/Impersonate/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/WindowsIdentity Impersonation/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/WindowsIdentity Impersonation/VB/source.vb" id="Snippet1"::: + ]]> @@ -98,14 +98,14 @@ Releases all resources used by the . - 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. - + 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. + ]]> @@ -137,26 +137,26 @@ System.Void - + to release both managed and unmanaged resources; to release only unmanaged resources. Releases the unmanaged resources used by the and optionally releases the managed resources. - method, if it has been overridden. `Dispose()` invokes this method with the `disposing` parameter set to `true`. `Finalize` invokes this method with `disposing` set to `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. - + + 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. + ]]> - can be called multiple times by other objects. When overriding be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). - + can be called multiple times by other objects. When overriding be careful not to reference objects that have been previously disposed of in an earlier call to . For more information about how to implement , see [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). + For more information about and , see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). @@ -182,7 +182,7 @@ [!NOTE] @@ -222,15 +222,15 @@ Application code does not call this method; it is automatically invoked during g Reverts the user context to the Windows user represented by this object. - An attempt is made to use this method for any purpose other than to revert identity to self. diff --git a/xml/System.Security/HostProtectionException.xml b/xml/System.Security/HostProtectionException.xml index 7c35b08de86..6f0c35fa3f9 100644 --- a/xml/System.Security/HostProtectionException.xml +++ b/xml/System.Security/HostProtectionException.xml @@ -48,17 +48,17 @@ The exception that is thrown when a denied host resource is detected. - attribute is used to determine if a type or member can be loaded, based on the host's protection preferences established when the common language runtime is started. If a type or member with an active is called, a link demand occurs for that protection attribute. If the caller does not meet the demand for host protection, a is thrown. - + A attribute is used to determine if a type or member can be loaded, based on the host's protection preferences established when the common language runtime is started. If a type or member with an active is called, a link demand occurs for that protection attribute. If the caller does not meet the demand for host protection, a is thrown. + > [!NOTE] -> A is not a permission, even though it is the target of a link demand. Because a is thrown for a link demand, it cannot be handled, and therefore it cannot be trapped and processed in code. - +> A is not a permission, even though it is the target of a link demand. Because a is thrown for a link demand, it cannot be handled, and therefore it cannot be trapped and processed in code. + ]]> @@ -101,16 +101,16 @@ Initializes a new instance of the class with default values. - class. - -|Property|Value| -|--------------|-----------| -||| -||| - + class. + +|Property|Value| +|--------------|-----------| +||| +||| + ]]> @@ -147,11 +147,11 @@ The message that describes the error. Initializes a new instance of the class with a specified error message. - @@ -204,11 +204,11 @@ Contextual information about the source or destination. Initializes a new instance of the class using the provided serialization information and streaming context. - @@ -249,11 +249,11 @@ The exception that is the cause of the current exception. If the innerException parameter is not , the current exception is raised in a block that handles the inner exception. Initializes a new instance of the class with a specified error message and a reference to the inner exception that is the cause of this exception. - property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. - + property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. + ]]>
@@ -294,11 +294,11 @@ A bitwise combination of the enumeration values that specify the demanded host resources. Initializes a new instance of the class with a specified error message, the protected host resources, and the host resources that caused the exception to be thrown. - attribute that indicates that the method exposes shared state. When the method is called, the performs a link demand for shared state. If the host has set shared state as a prohibited category, then a is raised with a `demandedResources` property value of . - + attribute that indicates that the method exposes shared state. When the method is called, the performs a link demand for shared state. If the host has set shared state as a prohibited category, then a is raised with a `demandedResources` property value of . + ]]>
@@ -335,11 +335,11 @@ Gets or sets the demanded host protection resources that caused the exception to be thrown. A bitwise combination of the values identifying the protection resources causing the exception to be thrown. The default is . - attribute that indicates that the method exposes shared state. When the method is called, the performs a link demand for shared state. If the host has set shared state as a prohibited category, then a is raised, and the value of the property is . - + attribute that indicates that the method exposes shared state. When the method is called, the performs a link demand for shared state. If the host has set shared state as a prohibited category, then a is raised, and the value of the property is . + ]]>
@@ -383,19 +383,19 @@ System.Void - - + + The serialized object data about the exception being thrown. The contextual information about the source or destination. Sets the specified object with information about the host protection exception. - method sets a object with all the exception object data targeted for serialization. During deserialization, the exception is reconstructed from the transmitted over the stream. - + method sets a object with all the exception object data targeted for serialization. During deserialization, the exception is reconstructed from the transmitted over the stream. + ]]> @@ -434,11 +434,11 @@ Gets or sets the host protection resources that are inaccessible to partially trusted code. A bitwise combination of the values identifying the inaccessible host protection categories. The default is . - @@ -476,11 +476,11 @@ Returns a string representation of the current host protection exception. A string representation of the current . -
diff --git a/xml/System.Security/SecurityCriticalAttribute.xml b/xml/System.Security/SecurityCriticalAttribute.xml index b1be3c5fe36..91457b1db4b 100644 --- a/xml/System.Security/SecurityCriticalAttribute.xml +++ b/xml/System.Security/SecurityCriticalAttribute.xml @@ -56,19 +56,19 @@ Specifies that code or an assembly performs security-critical operations. - [!IMPORTANT] > Partially trusted code is no longer supported. This attribute has no effect in .NET Core. - Security-critical operations are actions that affect code access security, such as elevation of privilege through suppression of code access security checks by using the method, calling unsafe managed code, and so forth. Either the attribute or the attribute must be applied to code for the code to perform security-critical operations. - + Security-critical operations are actions that affect code access security, such as elevation of privilege through suppression of code access security checks by using the method, calling unsafe managed code, and so forth. Either the attribute or the attribute must be applied to code for the code to perform security-critical operations. + > [!NOTE] -> The is equivalent to a link demand for full trust. A type or member marked with the can be called only by fully trusted code; it does not have to demand specific permissions. It cannot be called by partially trusted code. - - Applying the at the assembly level identifies the assembly as a security-critical assembly. The entire assembly can be identified as critical by setting the scope parameter . - +> The is equivalent to a link demand for full trust. A type or member marked with the can be called only by fully trusted code; it does not have to demand specific permissions. It cannot be called by partially trusted code. + + Applying the at the assembly level identifies the assembly as a security-critical assembly. The entire assembly can be identified as critical by setting the scope parameter . + ]]> @@ -160,17 +160,17 @@ 9.0.0.0 - + One of the enumeration values that specifies the scope of the attribute. Initializes a new instance of the class with the specified scope. - diff --git a/xml/System.Security/SecurityException.xml b/xml/System.Security/SecurityException.xml index f8173e96be7..57d5f023c41 100644 --- a/xml/System.Security/SecurityException.xml +++ b/xml/System.Security/SecurityException.xml @@ -72,18 +72,18 @@ The exception that is thrown when a security error is detected. - exception is thrown when a caller does not have the permissions required to access a resource. The following example instantiates a object that includes a object to allow access to UI objects and the Clipboard and a object to prevent registry access. The call to the method means that these permissions will apply regardless of the permissions assigned to the caller. As a result, the attempt to create a registry key throws a . - + exception is thrown when a caller does not have the permissions required to access a resource. The following example instantiates a object that includes a object to allow access to UI objects and the Clipboard and a object to prevent registry access. The call to the method means that these permissions will apply regardless of the permissions assigned to the caller. As a result, the attempt to create a registry key throws a . + :::code language="csharp" source="~/snippets/csharp/System.Security/SecurityException/Overview/se_ex1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.securityexception.class/vb/se_ex1.vb" id="Snippet1"::: - - uses the HRESULT COR_E_SECURITY, which has the value 0x8013150A. - - For a list of the initial property values for an instance of the class, see a specific constructor. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.securityexception.class/vb/se_ex1.vb" id="Snippet1"::: + + uses the HRESULT COR_E_SECURITY, which has the value 0x8013150A. + + For a list of the initial property values for an instance of the class, see a specific constructor. + ]]> @@ -101,11 +101,11 @@ Initializes a new instance of the class. - constructor, see the example provided for the constructor. - + constructor, see the example provided for the constructor. + ]]> @@ -148,21 +148,21 @@ Initializes a new instance of the class with default properties. - class. - -|Property|Value| -|--------------|-----------| -||A null reference (`Nothing` in Visual Basic).| -||The localized error message string.| - - - -## Examples - For an example of the use of a constructor, see the example provided for the constructor. - + class. + +|Property|Value| +|--------------|-----------| +||A null reference (`Nothing` in Visual Basic).| +||The localized error message string.| + + + +## Examples + For an example of the use of a constructor, see the example provided for the constructor. + ]]> @@ -210,21 +210,21 @@ The error message that explains the reason for the exception. Initializes a new instance of the class with a specified error message. - class. - -|Property|Value| -|--------------|-----------| -||A null reference (`Nothing` in Visual Basic).| -||The localized error message string.| - - - -## Examples - For an example of the use of a constructor, see the example provided for the constructor. - + class. + +|Property|Value| +|--------------|-----------| +||A null reference (`Nothing` in Visual Basic).| +||The localized error message string.| + + + +## Examples + For an example of the use of a constructor, see the example provided for the constructor. + ]]> @@ -279,46 +279,46 @@ - - + + The object that holds the serialized object data. The contextual information about the source or destination. Initializes a new instance of the class with serialized data. - - -- - -- - -- - -- - -- - -- - -- - -- - -- - - - -## Examples - For an example of the use of a constructor, see the example provided for the constructor. - + + +- + +- + +- + +- + +- + +- + +- + +- + +- + + + +## Examples + For an example of the use of a constructor, see the example provided for the constructor. + ]]> @@ -370,23 +370,23 @@ The exception that is the cause of the current exception. If the parameter is not , the current exception is raised in a block that handles the inner exception. Initializes a new instance of the class with a specified error message and a reference to the inner exception that is the cause of this exception. - property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. - - The following table shows the initial property values for an instance of the class. - -|Property|Value| -|--------------|-----------| -||The inner exception reference.| -||The localized error message string.| - - - -## Examples - For an example of the use of a constructor, see the example provided for the constructor. - + property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. + + The following table shows the initial property values for an instance of the class. + +|Property|Value| +|--------------|-----------| +||The inner exception reference.| +||The localized error message string.| + + + +## Examples + For an example of the use of a constructor, see the example provided for the constructor. + ]]> @@ -432,29 +432,29 @@ - - + + The error message that explains the reason for the exception. The type of the permission that caused the exception to be thrown. Initializes a new instance of the class with a specified error message and the permission type that caused the exception to be thrown. - |The localized error message string specified by `message`.| -||The of the permission that failed, specified by `type`.| - - - -## Examples - For an example of the use of a constructor, see the example provided for the constructor. - + |The localized error message string specified by `message`.| +||The of the permission that failed, specified by `type`.| + + + +## Examples + For an example of the use of a constructor, see the example provided for the constructor. + ]]> @@ -498,9 +498,9 @@ - - - + + + The error message that explains the reason for the exception. @@ -508,22 +508,22 @@ The state of the permission that caused the exception to be thrown. Initializes a new instance of the class with a specified error message, the permission type that caused the exception to be thrown, and the permission state. - |The localized error message string specified by `message`.| -||The of the permission that failed, specified by `type`.| -||The demanded security permission, permission set, or permission set collection that failed.| - - - -## Examples - For an example of the use of a constructor, see the example provided for the constructor. - + |The localized error message string specified by `message`.| +||The of the permission that failed, specified by `type`.| +||The demanded security permission, permission set, or permission set collection that failed.| + + + +## Examples + For an example of the use of a constructor, see the example provided for the constructor. + ]]> @@ -554,12 +554,12 @@ - - - - - - + + + + + + The error message that explains the reason for the exception. @@ -570,34 +570,34 @@ An that identifies the permission that failed. Initializes a new instance of the class for an exception caused by a Deny on the stack. - |The localized error message string specified by `message`.| -||The first permission in the permission set or permission set collection specified by `permThatFailed`.| -||An empty string.| -||The security permission, permission set, or permission set collection specified by `demanded`.| -||An empty string.| -||The denied security permission, permission set, or permission set collection specified by `deny`.| -||The permission, permission set, or permission set collection specified by `permitOnly`.| -||`null`.| -||The specified by `method`.| -||.| -||An empty string.| - - - -## Examples - The following code example shows the use of the constructor. - + |The localized error message string specified by `message`.| +||The first permission in the permission set or permission set collection specified by `permThatFailed`.| +||An empty string.| +||The security permission, permission set, or permission set collection specified by `demanded`.| +||An empty string.| +||The denied security permission, permission set, or permission set collection specified by `deny`.| +||The permission, permission set, or permission set collection specified by `permitOnly`.| +||`null`.| +||The specified by `method`.| +||.| +||An empty string.| + + + +## Examples + The following code example shows the use of the constructor. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.SecurityException/CPP/form1.cpp" id="Snippet16"::: :::code language="csharp" source="~/snippets/csharp/System.Security/SecurityException/.ctor/form1.cs" id="Snippet16"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.SecurityException/VB/form1.vb" id="Snippet16"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.SecurityException/VB/form1.vb" id="Snippet16"::: + ]]> @@ -628,15 +628,15 @@ - - - - - - - - - + + + + + + + + + The error message that explains the reason for the exception. @@ -650,27 +650,27 @@ The for the assembly that caused the exception. Initializes a new instance of the class for an exception caused by an insufficient grant set. - |The localized error message string specified by `message`.| -||The first permission in the permission set or permission set collection specified by `permThatFailed`.| -||The specified by `grant`.| -||The demanded security permission, permission set, or permission set collection that failed, specified by `demanded`.| -||The specified by `refused`.| -||An empty string.| -||An empty string.| -||The specified by `assemblyName`.| -||The specified by `method`.| -||The value from the specified by `evidence`.| -||The URL from the specified by `evidence`.| - + |The localized error message string specified by `message`.| +||The first permission in the permission set or permission set collection specified by `permThatFailed`.| +||The specified by `grant`.| +||The demanded security permission, permission set, or permission set collection that failed, specified by `demanded`.| +||The specified by `refused`.| +||An empty string.| +||An empty string.| +||The specified by `assemblyName`.| +||The specified by `method`.| +||The value from the specified by `evidence`.| +||The URL from the specified by `evidence`.| + ]]> @@ -708,21 +708,21 @@ Gets or sets the security action that caused the exception. One of the values. - property contains the security action that caused the security check failure. Many of the security actions can cause a security exception to be thrown. For example, a demand on a permission set checks that all callers on the call stack have the necessary permissions in the permission set. If any caller on the call stack lacks a required permission, the security check fails. Alternatively, a method in the call chain can modify the outcome of the stack walk by placing a stack walk modifier, such as or , on the stack to limit the allowed permissions. For example, a method on the call stack might deny all of its callers a set of permissions named PSET1, such that any demand for a permission that is part of PSET1 fails for those callers. The property contains the security action that caused the exception to be thrown. - - is an enumeration in the namespace that provides the security action value for the property. Typically this property contains one of the values shown in the following table. - -|Security action|Description| -|---------------------|-----------------| -||A full stack walk failed due to a demand made against the assembly identified by the property.| -||A link demand against the assembly identified by the property failed.| -||An assembly identified by the property failed to meet an inheritance demand.| -||A demanded permission did not match any permission in the permission set. The method that placed the on the call stack is identified by the property.| -||A demanded permission matched a permission in the deny permission set on the call stack. The method that placed the on the call stack is identified by the property.| - + property contains the security action that caused the security check failure. Many of the security actions can cause a security exception to be thrown. For example, a demand on a permission set checks that all callers on the call stack have the necessary permissions in the permission set. If any caller on the call stack lacks a required permission, the security check fails. Alternatively, a method in the call chain can modify the outcome of the stack walk by placing a stack walk modifier, such as or , on the stack to limit the allowed permissions. For example, a method on the call stack might deny all of its callers a set of permissions named PSET1, such that any demand for a permission that is part of PSET1 fails for those callers. The property contains the security action that caused the exception to be thrown. + + is an enumeration in the namespace that provides the security action value for the property. Typically this property contains one of the values shown in the following table. + +|Security action|Description| +|---------------------|-----------------| +||A full stack walk failed due to a demand made against the assembly identified by the property.| +||A link demand against the assembly identified by the property failed.| +||An assembly identified by the property failed to meet an inheritance demand.| +||A demanded permission did not match any permission in the permission set. The method that placed the on the call stack is identified by the property.| +||A demanded permission matched a permission in the deny permission set on the call stack. The method that placed the on the call stack is identified by the property.| + ]]> @@ -779,20 +779,20 @@ Gets or sets the demanded security permission, permission set, or permission set collection that failed. A permission, permission set, or permission set collection object. - property to display the demanded security permission, permission set, or permission set collection that failed. This code example is part of a larger example provided for the class. - + property to display the demanded security permission, permission set, or permission set collection that failed. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.SecurityException/CPP/form1.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Security/SecurityException/.ctor/form1.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.SecurityException/VB/form1.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.SecurityException/VB/form1.vb" id="Snippet3"::: + ]]> @@ -849,11 +849,11 @@ Gets or sets the denied security permission, permission set, or permission set collection that caused a demand to fail. A permission, permission set, or permission set collection object. - because it can contain a permission, a permission set, or a permission set collection. To test the run-time type of this property, you can use the method or a specific language operator, such as the [is operator](/dotnet/csharp/language-reference/keywords/is) in C# or the [TypeOf operator](/dotnet/visual-basic/language-reference/operators/typeof-operator) in Visual Basic. - + because it can contain a permission, a permission set, or a permission set collection. To test the run-time type of this property, you can use the method or a specific language operator, such as the [is operator](/dotnet/csharp/language-reference/keywords/is) in C# or the [TypeOf operator](/dotnet/visual-basic/language-reference/operators/typeof-operator) in Visual Basic. + ]]> @@ -906,23 +906,23 @@ Gets or sets information about the failed assembly. An that identifies the failed assembly. - object that identifies the assembly that caused the security check to fail. - + object that identifies the assembly that caused the security check to fail. + > [!NOTE] -> This property is not populated when a security exception occurs in a or stack frame, because the assembly issuing the or security action is not the assembly that failed the stack walk. In these cases, the security exception is created with a constructor that does not require an assembly name, granted set information, or refused set information. - - - -## Examples - The following code example shows the use of the property to display the information about the failed assembly. - +> This property is not populated when a security exception occurs in a or stack frame, because the assembly issuing the or security action is not the assembly that failed the stack walk. In these cases, the security exception is created with a constructor that does not require an assembly name, granted set information, or refused set information. + + + +## Examples + The following code example shows the use of the property to display the information about the failed assembly. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.SecurityException/CPP/form1.cpp" id="Snippet12"::: :::code language="csharp" source="~/snippets/csharp/System.Security/SecurityException/.ctor/form1.cs" id="Snippet12"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.SecurityException/VB/form1.vb" id="Snippet12"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.SecurityException/VB/form1.vb" id="Snippet12"::: + ]]>
@@ -963,11 +963,11 @@ Gets or sets the first permission in a permission set or permission set collection that failed the demand. An object representing the first permission that failed. - represents only the first permission that caused the exception. Additional permissions in the set or collection can also cause a demand failure. - + represents only the first permission that caused the exception. Additional permissions in the set or collection can also cause a demand failure. + ]]>
@@ -1025,28 +1025,28 @@ System.Void - - + + The that holds the serialized object data about the exception being thrown. The that contains contextual information about the source or destination. Sets the with information about the . - with all the exception object data targeted for serialization. During deserialization, the exception is reconstituted from the `SerializationInfo` transmitted over the stream. - - - -## Examples - The following code shows the use of the method to display the permission state contained in the object. - + with all the exception object data targeted for serialization. During deserialization, the exception is reconstituted from the `SerializationInfo` transmitted over the stream. + + + +## Examples + The following code shows the use of the method to display the permission state contained in the object. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.SecurityException/CPP/form1.cpp" id="Snippet9"::: :::code language="csharp" source="~/snippets/csharp/System.Security/SecurityException/.ctor/form1.cs" id="Snippet9"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.SecurityException/VB/form1.vb" id="Snippet9"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.SecurityException/VB/form1.vb" id="Snippet9"::: + ]]> The parameter is . @@ -1103,11 +1103,11 @@ Gets or sets the granted permission set of the assembly that caused the . The XML representation of the granted set of the assembly. - . - + . + ]]> @@ -1164,22 +1164,22 @@ Gets or sets the information about the method associated with the exception. A object describing the method. - or security action on the call stack, in the case of a failure due to a or . - -- `null`, in the case of a failure that is impossible to attribute to a specific method. - - The object provides the method name, class name, and assembly name information that uniquely identifies the method. - + This property contains one of the following: + +- Information about the method that the failed assembly was executing when the security check that triggered the exception occurred. + +- Information about the method that placed either a or security action on the call stack, in the case of a failure due to a or . + +- `null`, in the case of a failure that is impossible to attribute to a specific method. + + The object provides the method name, class name, and assembly name information that uniquely identifies the method. + ]]>
@@ -1338,13 +1338,13 @@ Gets or sets the permission, permission set, or permission set collection that is part of the permit-only stack frame that caused a security check to fail. A permission, permission set, or permission set collection object. - property represents the permitted permission, permission set, or permission set collection contained in the stack frame that caused the security exception. For instance, when a security exception occurs because of a failure, the permitted permission appears in this property and the demanded is contained in the property. - - This property is of type because permissions, permission sets, or permission set collections can all be demanded and is their common base class. To test the run-time type of this property, you can use the method or a specific language operator, such as the [is operator](/dotnet/csharp/language-reference/keywords/is) in C# or the [TypeOf operator](/dotnet/visual-basic/language-reference/operators/typeof-operator) in Visual Basic. - + property represents the permitted permission, permission set, or permission set collection contained in the stack frame that caused the security exception. For instance, when a security exception occurs because of a failure, the permitted permission appears in this property and the demanded is contained in the property. + + This property is of type because permissions, permission sets, or permission set collections can all be demanded and is their common base class. To test the run-time type of this property, you can use the method or a specific language operator, such as the [is operator](/dotnet/csharp/language-reference/keywords/is) in C# or the [TypeOf operator](/dotnet/visual-basic/language-reference/operators/typeof-operator) in Visual Basic. + ]]>
@@ -1398,11 +1398,11 @@ Gets or sets the refused permission set of the assembly that caused the . The XML representation of the refused permission set of the assembly. - . - + . + ]]>
@@ -1460,11 +1460,11 @@ Returns a representation of the current . A string representation of the current . - method returns the full description of the . - + method returns the full description of the . + ]]>
diff --git a/xml/System.Security/VerificationException.xml b/xml/System.Security/VerificationException.xml index f8780dc1c51..5983b438d5b 100644 --- a/xml/System.Security/VerificationException.xml +++ b/xml/System.Security/VerificationException.xml @@ -127,11 +127,11 @@ Initializes a new instance of the class with default properties. - uses the HRESULT COR_E_VERIFICATION. - + uses the HRESULT COR_E_VERIFICATION. + ]]> @@ -231,19 +231,19 @@ - - + + The object that holds the serialized object data. The contextual information about the source or destination. Initializes a new instance of the class with serialized data. - @@ -293,18 +293,18 @@ The exception that is the cause of the current exception. If the parameter is not , the current exception is raised in a block that handles the inner exception. Initializes a new instance of the class with a specified error message and a reference to the inner exception that is the cause of this exception. - property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||The inner exception reference.| -||The error message string.| - + property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||The inner exception reference.| +||The error message string.| + ]]> diff --git a/xml/System.ServiceModel.Channels/AddressHeader.xml b/xml/System.ServiceModel.Channels/AddressHeader.xml index a5e589e2ea3..4ad8846e2f2 100644 --- a/xml/System.ServiceModel.Channels/AddressHeader.xml +++ b/xml/System.ServiceModel.Channels/AddressHeader.xml @@ -39,21 +39,21 @@ Represents a header that encapsulates an address information item used to identify or interact with an endpoint. - is characterized by a name and namespace and has a value that contains optional information used to identify or interact with an endpoint. The name can be accessed by the property and the namespace by the property. - - - -## Examples - The following example shows how to create address headers, access their properties, add them to a service endpoint and host the service using the endpoint. - + is characterized by a name and namespace and has a value that contains optional information used to identify or interact with an endpoint. The name can be accessed by the property and the namespace by the property. + + + +## Examples + The following example shows how to create address headers, access their properties, add them to a service endpoint and host the service using the endpoint. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/sl_addressheader/cs/page.xaml.cs" id="Snippet0"::: :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/sl_addressheader/cs/program.cs" id="Snippet0"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/sl_addressheader/vb/page.xaml.vb" id="Snippet0"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/sl_addressheader/vb/program.vb" id="Snippet0"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/sl_addressheader/vb/program.vb" id="Snippet0"::: + ]]> @@ -93,11 +93,11 @@ Initializes a new instance of the class. - to create new objects. - + to create new objects. + ]]> @@ -111,11 +111,11 @@ Creates a new instance of the class. - object. - + object. + ]]> @@ -141,23 +141,23 @@ System.ServiceModel.Channels.AddressHeader - + The information item for the address header. Creates a new instance of the class with a specified value. The that contains the information item specified by the parameter. - @@ -183,8 +183,8 @@ System.ServiceModel.Channels.AddressHeader - - + + The information item for the address header. @@ -192,16 +192,16 @@ Creates a new instance of the class using a specified formatter to serialize the information item from a specified object. The that contains the information item specified by the value parameter. - The is . @@ -248,16 +248,16 @@ Creates a new instance of the class with a specified value, name and namespace. The with the specified and that contains the information item specified by . - The is or .Length == 0. @@ -306,16 +306,16 @@ Creates a new instance of the class with a specified name and namespace that uses a specified formatter to serialize the information item from a specified object. The with the specified and that contains the information item specified by . - @@ -360,18 +360,18 @@ if the information item in a specified is equivalent to the information item contained in the current address header; otherwise, . In particular, returns if is . - @@ -410,13 +410,13 @@ Returns an XML reader that can serialize the current address header object. An instance of that can serialize the current address header object. -
@@ -455,20 +455,20 @@ Provides a unique hash code for an address header. A unique hash code for the current address header. - is suitable for use in hashing algorithms and data structures like a hash table. - - - -## Examples - The following example shows how to call this method. - - - + is suitable for use in hashing algorithms and data structures like a hash table. + + + +## Examples + The following example shows how to call this method. + + + ]]>
@@ -482,11 +482,11 @@ Deserializes the information item from the current address header object. - overload if you want to use a customized XML formatter; otherwise use the overload. - + overload if you want to use a customized XML formatter; otherwise use the overload. + ]]> @@ -529,23 +529,23 @@ Deserializes the information item from the current address header to an object of a specified type. An instance of a class of type with its fields and properties set to the values supplied by the current address header object. - overload if you want to use a customized XML formatter. - - - -## Examples - The following example shows how to call this method. - + overload if you want to use a customized XML formatter. + + + +## Examples + The following example shows how to call this method. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/sl_addressheader/cs/page.xaml.cs" id="Snippet10"::: :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/sl_addressheader/cs/program.cs" id="Snippet10"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/sl_addressheader/vb/page.xaml.vb" id="Snippet10"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/sl_addressheader/vb/program.vb" id="Snippet10"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/sl_addressheader/vb/program.vb" id="Snippet10"::: + ]]>
@@ -591,20 +591,20 @@ Deserializes the information item from the current address header to an object of a specified type that uses a specified formatter to serialize this information. An instance of a class of type with its fields and properties set to the values supplied by the current address header object. - overload. - - - -## Examples - The following example shows how to call this method. - - - + overload. + + + +## Examples + The following example shows how to call this method. + + + ]]> The is . @@ -643,16 +643,16 @@ When implemented, gets the name of the address header. The name of the address header. -
@@ -690,16 +690,16 @@ When implemented, gets the namespace of the address header. The namespace of the address header. -
@@ -814,13 +814,13 @@ Wraps the address header as a message header. The that wraps the current address header. -
@@ -834,11 +834,11 @@ Writes the address header to a stream or file. - and overloads provide interfaces to use in writing an address header to a stream or file. Both call the abstract method, so users must provide an implementation of this method to use these overloads. - + and overloads provide interfaces to use in writing an address header to a stream or file. Both call the abstract method, so users must provide an implementation of this method to use these overloads. + ]]> @@ -879,20 +879,20 @@ The used to write the address header to a stream or file. Writes the address header to a stream or file using a specified . - method, so users must provide an implementation of that method to use this method. - - - -## Examples - The following example shows how to call this method. - - - + method, so users must provide an implementation of that method to use this method. + + + +## Examples + The following example shows how to call this method. + + + ]]> The is . @@ -934,20 +934,20 @@ The used to write the address header to a stream or file. Writes the address header to a stream or file using a specified . - as a and then the calls the abstract - - method. Users must provide an implementation for that abstract method to use this overload. - - - -## Examples - The following example shows how to call this method. - - - + as a and then the calls the abstract + + method. Users must provide an implementation for that abstract method to use this overload. + + + +## Examples + The following example shows how to call this method. + + + ]]> The is . @@ -989,13 +989,13 @@ The used to write the address header contents to a stream or file. Writes the address header contents to a stream or file. - The is . @@ -1037,13 +1037,13 @@ The used to write the address header to a stream or file. Starts to write the address header contents to a stream or file. - The is . diff --git a/xml/System.ServiceModel.Channels/BinaryMessageEncodingBindingElement.xml b/xml/System.ServiceModel.Channels/BinaryMessageEncodingBindingElement.xml index a56bbeb4696..776bbbbf013 100644 --- a/xml/System.ServiceModel.Channels/BinaryMessageEncodingBindingElement.xml +++ b/xml/System.ServiceModel.Channels/BinaryMessageEncodingBindingElement.xml @@ -51,25 +51,25 @@ The binding element that specifies the .NET Binary Format for XML used to encode messages. - is the binding element that specifies that the .NET Binary Format for XML should be used for encoding messages. It has options to specify the character encoding and the SOAP and WS-Addressing version to be used. Binary encoding is the most efficient but least interoperable of the encoding options. - - For more information about the binding element that specifies messages are encoded using a textual representation of XML, see . - - For more information about the binding element that specifies messages are encoded using the MTOM message encoding, see . - - To implement a custom message encoder, use the class. - - - -## Examples + is the binding element that specifies that the .NET Binary Format for XML should be used for encoding messages. It has options to specify the character encoding and the SOAP and WS-Addressing version to be used. Binary encoding is the most efficient but least interoperable of the encoding options. + + For more information about the binding element that specifies messages are encoded using a textual representation of XML, see . + + For more information about the binding element that specifies messages are encoded using the MTOM message encoding, see . + + To implement a custom message encoder, use the class. + + + +## Examples :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_ue_binarymessageencodingbindingelement/cs/program.cs" id="Snippet0"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_ue_binarymessageencodingbindingelement/vb/module1.vb" id="Snippet0"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_ue_binarymessageencodingbindingelement/vb/module1.vb" id="Snippet0"::: + ]]> @@ -103,12 +103,12 @@ Initializes a new instance of the class. - @@ -154,12 +154,12 @@ Builds the channel factory stack on the client that creates a specified type of channel for a specified context. An of type for the specified context. -
@@ -192,7 +192,7 @@ - + The type of channel the channel listener accepts. @@ -200,12 +200,12 @@ Builds the channel listener on the service that accepts a specified type of channel for a specified context. An of type for the specified context. - @@ -238,7 +238,7 @@ - + The type of channel the channel listener accepts. @@ -247,12 +247,12 @@ if the specified channel listener stack can be built on the service; otherwise, . - @@ -291,19 +291,19 @@ Creates a new object initialized from the current one. A object with property values equal to those of the current element. -
@@ -382,17 +382,17 @@ Creates a factory for binary message encoders that employ the SOAP and WS-Addressing versions and the character encoding specified by the current encoding binding element. The that this binding element creates. - objects that the factory produces can read and write messages using the binary message encoding. - - - -## Examples + objects that the factory produces can read and write messages using the binary message encoding. + + + +## Examples :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_ue_binarymessageencodingbindingelement/cs/program.cs" id="Snippet11"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_ue_binarymessageencodingbindingelement/vb/module1.vb" id="Snippet11"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_ue_binarymessageencodingbindingelement/vb/module1.vb" id="Snippet11"::: + ]]>
@@ -442,17 +442,17 @@ Returns a typed object requested, if present, from the appropriate layer in the binding element stack. The typed object requested if it is present or if it is not. -
@@ -496,17 +496,17 @@ Gets or sets the maximum number of XML readers that are allocated to a pool and are ready for use to process incoming messages. The maximum number of readers to be kept in the pool. The default value is 64 readers. - The value set is less than or equal to zero. @@ -555,17 +555,17 @@ Gets or sets the maximum amount of memory available within a session for optimizing transmission procedures. The maximum size, in bytes, of a session. The default value is 2048 bytes. - gets and sets the maximum amount of memory that is allocated to store these strings. - - - -## Examples + gets and sets the maximum amount of memory that is allocated to store these strings. + + + +## Examples :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_ue_binarymessageencodingbindingelement/cs/program.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_ue_binarymessageencodingbindingelement/vb/module1.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_ue_binarymessageencodingbindingelement/vb/module1.vb" id="Snippet3"::: + ]]> The value is less than or equal to zero. @@ -610,17 +610,17 @@ Gets or sets the maximum number of XML writers that are allocated to a pool and are ready for use to process outgoing messages. The maximum number of writers to be kept in the pool. The default value is 16 writers. - The value is less than or equal to zero. @@ -665,17 +665,17 @@ Gets or sets the SOAP message and WS-Addressing versions that are used or expected. The that is used or expected. - The value set is . @@ -725,27 +725,27 @@ Gets or sets constraints on the complexity of XML messages that can be processed by endpoints configured with this binding element. The that specifies the complexity constraints on SOAP messages exchanged. The default values for these constraints are provided in the following remarks section. - = 32 - -- = 8192 - -- = 16384 - -- = 4096 - -- = 16384 - + = 32 + +- = 8192 + +- = 16384 + +- = 4096 + +- = 16384 + This property has a public setter since .NET Framework 4.0. - -## Examples + +## Examples :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_ue_binarymessageencodingbindingelement/cs/program.cs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_ue_binarymessageencodingbindingelement/vb/module1.vb" id="Snippet6"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_ue_binarymessageencodingbindingelement/vb/module1.vb" id="Snippet6"::: + ]]>
@@ -781,11 +781,11 @@ This property has a public setter since .NET Framework 4.0. if the SOAP message structure version should be serialized; otherwise, . -
diff --git a/xml/System.ServiceModel.Channels/Binding.xml b/xml/System.ServiceModel.Channels/Binding.xml index 7fb92107067..8aafddd9ef6 100644 --- a/xml/System.ServiceModel.Channels/Binding.xml +++ b/xml/System.ServiceModel.Channels/Binding.xml @@ -43,45 +43,45 @@ Contains the binding elements that specify the protocols, transports, and message encoders used for communication between clients and services. - |No| -|Reliability||No| -|Security|Symmetric, Asymmetric, Transport-Level|No| -|Shape Change||No| -|Transport Upgrades|SSL stream, Windows stream, Peer Resolver|No| -|Encoding|Text, Binary, MTOM, Custom|Yes| -|Transport|TCP, Named Pipes, HTTP, HTTPS, MSMQ, Custom|Yes| - - Each binding element provides the specification for building a channel factory on the client and a channel listener on the service. When the channel factory stack is constructed, for example, there is one channel factory in the stack for each binding element in the binding. The same sort of mapping applies to the channel listeners in the stack on the service. Consistency on the client and service is critical for establishing the channel-based connection between these endpoints. Each factory and listener, in turn, processes the sending and accepting of the corresponding channels in the channel stack that connects them, and these channels can then send and receive the messages used to communicate. - - Each instance of a has a and that together uniquely identify it in the metadata of the service. If no name or namespace is specified, WCF adds a default values for you. The default name is `null` and the default namespace is `http://tempuri.org/`. This user name for the binding is distinct from the specification of the protocol name, which is specified by the property. If you want to add more HTTP bindings, for example, you can name them whatever you want and set all of their schemes to "http". There is no inherent application or machine dispatch based on the . So you avoid the common problem of being unable to register additional handlers for well-known protocols. You can also easily work with multiple versions of a binding side-by-side by giving each version a different name. - - The class implements the interface to mitigate Denial of Service (DOS) attacks that rely on tying up resources for extended intervals of time. The implementation specifies the communication timeouts values for opening and closing connections and for the reading and writing operations associated with receiving and sending messages. The properties used to get and set these timeouts and their default values operations are summarized in the following table. - -|Timeout Property|Default Value| -|----------------------|-------------------| -||1 minute| -||1 minute| -||1 minute| -||10 minutes| - - When you create a binding by inheriting from , you must override . - - In addition, you can define your own binding elements and insert them between any of the defined layers in the preceding table. For more information, see the class. - - - -## Examples - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uebinding/cs/service.cs" id="Snippet11"::: - + |No| +|Reliability||No| +|Security|Symmetric, Asymmetric, Transport-Level|No| +|Shape Change||No| +|Transport Upgrades|SSL stream, Windows stream, Peer Resolver|No| +|Encoding|Text, Binary, MTOM, Custom|Yes| +|Transport|TCP, Named Pipes, HTTP, HTTPS, MSMQ, Custom|Yes| + + Each binding element provides the specification for building a channel factory on the client and a channel listener on the service. When the channel factory stack is constructed, for example, there is one channel factory in the stack for each binding element in the binding. The same sort of mapping applies to the channel listeners in the stack on the service. Consistency on the client and service is critical for establishing the channel-based connection between these endpoints. Each factory and listener, in turn, processes the sending and accepting of the corresponding channels in the channel stack that connects them, and these channels can then send and receive the messages used to communicate. + + Each instance of a has a and that together uniquely identify it in the metadata of the service. If no name or namespace is specified, WCF adds a default values for you. The default name is `null` and the default namespace is `http://tempuri.org/`. This user name for the binding is distinct from the specification of the protocol name, which is specified by the property. If you want to add more HTTP bindings, for example, you can name them whatever you want and set all of their schemes to "http". There is no inherent application or machine dispatch based on the . So you avoid the common problem of being unable to register additional handlers for well-known protocols. You can also easily work with multiple versions of a binding side-by-side by giving each version a different name. + + The class implements the interface to mitigate Denial of Service (DOS) attacks that rely on tying up resources for extended intervals of time. The implementation specifies the communication timeouts values for opening and closing connections and for the reading and writing operations associated with receiving and sending messages. The properties used to get and set these timeouts and their default values operations are summarized in the following table. + +|Timeout Property|Default Value| +|----------------------|-------------------| +||1 minute| +||1 minute| +||1 minute| +||10 minutes| + + When you create a binding by inheriting from , you must override . + + In addition, you can define your own binding elements and insert them between any of the defined layers in the preceding table. For more information, see the class. + + + +## Examples + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uebinding/cs/service.cs" id="Snippet11"::: + ]]> @@ -125,17 +125,17 @@ Initializes a new instance of the class with a default name and namespace. - @@ -175,11 +175,11 @@ The of the binding. Initializes a new instance of the class from a specified binding of the service. - and together uniquely identify an instance of a in the metadata of the service. - + and together uniquely identify an instance of a in the metadata of the service. + ]]> @@ -330,7 +330,7 @@ - + [System.ParamArray] @@ -376,7 +376,7 @@ - + The type of channel the channel listener accepts. @@ -415,9 +415,9 @@ - - - + + + [System.ParamArray] @@ -471,9 +471,9 @@ - - - + + + The type of channel the channel listener accepts. @@ -514,9 +514,8 @@ - - - + + [System.ParamArray] @@ -528,7 +527,6 @@ The type of channel the channel listener accepts. The that provides the base address on which the service listens. - The that provides the base address on which the service listens. The object array that specifies requirements for the channel factory that is built. Builds the channel listener on the service that accepts a specified type of channel and that satisfies the features specified. An of type that satisfies the features specified. @@ -564,14 +562,12 @@ - - - + + The type of channel the channel listener accepts. The that provides the base address on which the service listens. - The that provides the base address on which the service listens. The that specifies requirements for the channel listener that is built. Builds the channel listener on the service that accepts a specified type of channel and that satisfies the features specified. An of type that satisfies the features specified. @@ -607,10 +603,10 @@ - - - - + + + + [System.ParamArray] @@ -659,10 +655,10 @@ - - - - + + + + The type of channel the channel listener accepts. @@ -685,11 +681,11 @@ Returns a value that indicates whether the current binding can build a channel factory stack on the client that satisfies some specific criteria. - and catch the exception generated if it cannot be built. - + and catch the exception generated if it cannot be built. + ]]> @@ -743,11 +739,11 @@ if the specified channel factory stack can be build on the client; otherwise, . - and catch the exception generated if it cannot be built. - + and catch the exception generated if it cannot be built. + ]]> @@ -794,11 +790,11 @@ if the specified channel factory stack can be build on the client; otherwise, . - and catch the exception generated if it cannot be built. - + and catch the exception generated if it cannot be built. + ]]> @@ -840,7 +836,7 @@ - + [System.ParamArray] @@ -856,11 +852,11 @@ if the specified channel listener stack can be build on the service; otherwise, . - and catch the exception generated if it cannot be built. - + and catch the exception generated if it cannot be built. + ]]> @@ -893,7 +889,7 @@ - + The type of channel for which the listener is being tested. @@ -902,11 +898,11 @@ if the specified channel listener stack can be build on the service; otherwise, . - and catch the exception generated if it cannot be built. - + and catch the exception generated if it cannot be built. + ]]> @@ -954,11 +950,11 @@ Gets or sets the interval of time provided for a connection to close before the transport raises an exception. The that specifies how long the close operation has to complete before timing out. The default value is 1 minute. - The value is less than zero or too large. @@ -998,11 +994,11 @@ When overridden in a derived class, creates a collection that contains the binding elements that are part of the current binding. A object of type that contains the binding elements from the current binding object in the correct order. - object uses. - + object uses. + ]]> @@ -1052,11 +1048,11 @@ Returns a typed object requested, if present, from the appropriate layer in the binding stack. The typed object requested if it is present or if it is not. - @@ -1129,13 +1125,13 @@ Gets or sets the name of the binding. The name of the binding. The default name is . - has a and that together uniquely identify the user name for the binding in the metadata of the service. - - This user name for the binding is distinct from the specification of the protocol name, which is specified by the property. If you want to add more HTTP bindings, for example, you can name them whatever you want and set all of their schemes to "http". There is no inherent application or machine dispatch based on the . So you avoid the common problem of being unable to register additional handlers for well-known protocols. You can also easily work with multiple versions of a binding side-by-side by giving each version a different name. - + has a and that together uniquely identify the user name for the binding in the metadata of the service. + + This user name for the binding is distinct from the specification of the protocol name, which is specified by the property. If you want to add more HTTP bindings, for example, you can name them whatever you want and set all of their schemes to "http". There is no inherent application or machine dispatch based on the . So you avoid the common problem of being unable to register additional handlers for well-known protocols. You can also easily work with multiple versions of a binding side-by-side by giving each version a different name. + ]]> The value set cannot be or an empty string. @@ -1180,13 +1176,13 @@ Gets or sets the XML namespace of the binding. The XML namespace of the binding. The default value is "http://tempuri.org/". - has a and that together uniquely identify the user name for the binding in the metadata of the service. - - This user name for the binding is distinct from the specification of the protocol name, which is specified by the property. If you want to add more HTTP bindings, for example, you can name them whatever you want and set all of their schemes to "http". There is no inherent application or machine dispatch based on the . So you avoid the common problem of being unable to register additional handlers for well-known protocols. You can also easily work with multiple versions of a binding side-by-side by giving each version a different name. - + has a and that together uniquely identify the user name for the binding in the metadata of the service. + + This user name for the binding is distinct from the specification of the protocol name, which is specified by the property. If you want to add more HTTP bindings, for example, you can name them whatever you want and set all of their schemes to "http". There is no inherent application or machine dispatch based on the . So you avoid the common problem of being unable to register additional handlers for well-known protocols. You can also easily work with multiple versions of a binding side-by-side by giving each version a different name. + ]]> The value set cannot be . @@ -1235,11 +1231,11 @@ Gets or sets the interval of time provided for a connection to open before the transport raises an exception. The that specifies how long the open operation has to complete before timing out. The default value is 1 minute. - The value is less than zero or too large. @@ -1288,21 +1284,21 @@ Gets or sets the interval of time that a connection can remain inactive, during which no application messages are received, before it is dropped. The that specifies how long the application has to receive a message before timing out. The default value is 10 minutes. - . This inactivity timer fires if no messages, either application or infrastructure, are received within the timeout period. An infrastructure message is a message that is generated for the purpose of one of the protocols in the channel stack, such as a keep alive or an acknowledgment, rather than containing application data. - -- The second inactivity timer is on the service and uses the setting of the binding. This inactivity timer fires if no application messages are received within the timeout period. This specifies, for example, the maximum time a client may take to send at least one message to the server before the server will close the channel used by a session. This behavior ensures that clients cannot hold on to server resources for arbitrary long periods. - - Since the connection is dropped if either inactivity timer fires, increasing once it is greater than has no effect. The default for both of these timeouts is 10 minutes, so you always have to increase both of them to make a difference when using a reliable session. - - If transaction flow is enabled on the binding or the channel, the operation may take longer to execute than the specified timeout. In these circumstances the operation fails due to the expired timeout and the transaction aborts appropriately. - - When security is used with sessions, the value set on the binding is also used as the session timeout. - + . This inactivity timer fires if no messages, either application or infrastructure, are received within the timeout period. An infrastructure message is a message that is generated for the purpose of one of the protocols in the channel stack, such as a keep alive or an acknowledgment, rather than containing application data. + +- The second inactivity timer is on the service and uses the setting of the binding. This inactivity timer fires if no application messages are received within the timeout period. This specifies, for example, the maximum time a client may take to send at least one message to the server before the server will close the channel used by a session. This behavior ensures that clients cannot hold on to server resources for arbitrary long periods. + + Since the connection is dropped if either inactivity timer fires, increasing once it is greater than has no effect. The default for both of these timeouts is 10 minutes, so you always have to increase both of them to make a difference when using a reliable session. + + If transaction flow is enabled on the binding or the channel, the operation may take longer to execute than the specified timeout. In these circumstances the operation fails due to the expired timeout and the transaction aborts appropriately. + + When security is used with sessions, the value set on the binding is also used as the session timeout. + ]]> The value is less than zero or too large. @@ -1341,11 +1337,11 @@ When implemented in a derived class, sets the URI scheme that specifies the transport used by the channel and listener factories that are built by the bindings. The URI scheme that is used by the channels or listeners that are created by the factories built by the current binding. - property. Each instance of a has a and that together uniquely identify the user name for the binding in the metadata of the service. If you want to add more HTTP bindings, for example, you can name them whatever you want and set all of their schemes to "http". There is no inherent application or machine dispatch based on the . So you avoid the common problem of being unable to register additional handlers for well-known protocols. You can also easily work with multiple versions of a binding side-by-side by giving each version a different name. - + property. Each instance of a has a and that together uniquely identify the user name for the binding in the metadata of the service. If you want to add more HTTP bindings, for example, you can name them whatever you want and set all of their schemes to "http". There is no inherent application or machine dispatch based on the . So you avoid the common problem of being unable to register additional handlers for well-known protocols. You can also easily work with multiple versions of a binding side-by-side by giving each version a different name. + ]]>
@@ -1393,11 +1389,11 @@ Gets or sets the interval of time provided for a write operation to complete before the transport raises an exception. The that specifies how long the write operation has to complete before timing out. The default value is 1 minute. - The value is less than zero or too large. diff --git a/xml/System.ServiceModel.Channels/BindingContext.xml b/xml/System.ServiceModel.Channels/BindingContext.xml index 0c53d9aa39d..a7add2fd11d 100644 --- a/xml/System.ServiceModel.Channels/BindingContext.xml +++ b/xml/System.ServiceModel.Channels/BindingContext.xml @@ -39,11 +39,11 @@ Provides information about the addresses, bindings, binding elements and binding parameters required to build the channel listeners and channel factories. - @@ -93,17 +93,17 @@ The for the channel. Initializes a new instance of the class for a specified binding and collection of binding parameters. - is set to by this constructor, the relative address is set to , and the base address is set to `null`. - - - -## Examples + is set to by this constructor, the relative address is set to , and the base address is set to `null`. + + + +## Examples :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_ue_bindingcontext/cs/program.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_ue_bindingcontext/vb/program.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_ue_bindingcontext/vb/program.vb" id="Snippet1"::: + ]]> @@ -127,11 +127,11 @@ System.ServiceModel.Primitives - - - - - + + + + + The for the channel. @@ -141,12 +141,12 @@ The that indicates whether the transport must ensure that the URI provided for the service to listen on is unique. Initializes a new instance of the class for a specified binding, collection of binding parameters, and address for the endpoint at which the service listens. - @@ -193,12 +193,12 @@ Gets the binding for the channel built in the current context. The for the channel built in the current context. - @@ -242,17 +242,17 @@ Gets the collection of binding parameters for the channel built in the current context. The for the channel built in the current context. -
@@ -295,12 +295,12 @@ Builds the inner channel factory for channels of a specified type below the current channel factory. The of type that represents the inner channel factory of the current channel factory. -
@@ -338,12 +338,12 @@ Builds an inner channel listener that listens for a specified type of channel. The of type that represents the inner channel listener of the current channel factory. -
@@ -387,12 +387,12 @@ if the inner channel factory can produce the specified ; otherwise, . -
@@ -431,12 +431,12 @@ if the inner channel listener can be built to listen for the specified; otherwise, . -
@@ -475,17 +475,17 @@ Returns a copy of the current channel build context. A object that is a copy of the current channel build context. -
@@ -532,17 +532,17 @@ Returns a typed object requested, if present, from the appropriate layer in the binding stack. The typed object requested if it is present or if it is not. - on the next binding element stored in the binding context. - - - -## Examples + on the next binding element stored in the binding context. + + + +## Examples :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_ue_bindingcontext/cs/program.cs" id="Snippet14"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_ue_bindingcontext/vb/program.vb" id="Snippet14"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_ue_bindingcontext/vb/program.vb" id="Snippet14"::: + ]]>
@@ -581,17 +581,17 @@ Gets or sets the URI that provides the base address at which the service endpoint listens. The at which the service endpoint listens. - to the . This absolute address can be set using the property. - - - -## Examples + to the . This absolute address can be set using the property. + + + +## Examples :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_ue_bindingcontext/cs/program.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_ue_bindingcontext/vb/program.vb" id="Snippet5"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_ue_bindingcontext/vb/program.vb" id="Snippet5"::: + ]]>
@@ -630,12 +630,12 @@ Gets or sets a value that indicates whether the transport must ensure that the URI provided for the service to listen on is unique. The that indicates whether the transport must ensure that the URI provided for the service to listen on is unique. -
@@ -674,17 +674,17 @@ Gets or sets the URI that provides the relative address at which the service endpoint listens. The relative address at which the service endpoint listens. - to the . This absolute address can be set using the property. - - - -## Examples + to the . This absolute address can be set using the property. + + + +## Examples :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_ue_bindingcontext/cs/program.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_ue_bindingcontext/vb/program.vb" id="Snippet7"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_ue_bindingcontext/vb/program.vb" id="Snippet7"::: + ]]>
@@ -728,17 +728,17 @@ Gets the binding elements that are used by other binding elements to construct the channel stack. The that contains the binding elements that are used by other binding elements to construct the channel stack. -
diff --git a/xml/System.ServiceModel.Channels/BindingElement.xml b/xml/System.ServiceModel.Channels/BindingElement.xml index 6c874a9c25e..8987d83827d 100644 --- a/xml/System.ServiceModel.Channels/BindingElement.xml +++ b/xml/System.ServiceModel.Channels/BindingElement.xml @@ -39,30 +39,30 @@ The elements of the bindings that build the channel factories and channel listeners for various types of channels that are used to process outgoing and incoming messages. - class inherits from the class. - - Creating a binding and binding element for your transport is optional if you are just using the channel model. It is possible to do everything you need through the channel factory and listener as long as they are made public. - - The Windows Communication Foundation (WCF) service model uses a factory pattern where the binding is used to create the channel stack. If you want to use the WCF service model, then using a transport binding element is required. Placing this binding element into a binding is a good practice because it removes the requirement for users to create their own custom binding for your transport. It is best to create both a binding and binding element, and hide the channel factory and listener inside the assembly. - - On the sending side, a binding is used to build a , which in turn builds a channel stack and returns a reference to the top channel in the stack. The application can then use this channel to send messages. - - Similarly, on the receiving side a binding is used to build a , which listens for incoming messages. The provides messages to the listening application by creating channel stacks and handing the application a reference to the top channel. The application then uses this channel to receive incoming messages. - + class inherits from the class. + + Creating a binding and binding element for your transport is optional if you are just using the channel model. It is possible to do everything you need through the channel factory and listener as long as they are made public. + + The Windows Communication Foundation (WCF) service model uses a factory pattern where the binding is used to create the channel stack. If you want to use the WCF service model, then using a transport binding element is required. Placing this binding element into a binding is a good practice because it removes the requirement for users to create their own custom binding for your transport. It is best to create both a binding and binding element, and hide the channel factory and listener inside the assembly. + + On the sending side, a binding is used to build a , which in turn builds a channel stack and returns a reference to the top channel in the stack. The application can then use this channel to send messages. + + Similarly, on the receiving side a binding is used to build a , which listens for incoming messages. The provides messages to the listening application by creating channel stacks and handing the application a reference to the top channel. The application then uses this channel to receive incoming messages. + > [!NOTE] -> If you are adding message headers that must be encrypted you must return a instance with your requirements from the method when asked for . - - - -## Examples - The following example shows how to add a transport binding element to a custom binding and then build a channel listener that can accept incoming messages. - +> If you are adding message headers that must be encrypted you must return a instance with your requirements from the method when asked for . + + + +## Examples + The following example shows how to add a transport binding element to a custom binding and then build a channel listener that can accept incoming messages. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uechannels/cs/servicesnippets.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_uechannels/vb/servicesnippets.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_uechannels/vb/servicesnippets.vb" id="Snippet1"::: + ]]> @@ -196,11 +196,11 @@ Initializes a channel factory for producing channels of a specified type from the binding context. The of type initialized from the . - @@ -235,7 +235,7 @@ - + The type of channel the listener is built to accept. @@ -243,11 +243,11 @@ Initializes a channel listener to accept channels of a specified type from the binding context. The of type initialized from the . - @@ -296,16 +296,16 @@ if the of type can be built by the binding element; otherwise, . - and catch the exception generated if it cannot be built. - - - -## Examples - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uechannels/cs/clientsnippets.cs" id="Snippet18"::: - + and catch the exception generated if it cannot be built. + + + +## Examples + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uechannels/cs/clientsnippets.cs" id="Snippet18"::: + ]]> @@ -340,7 +340,7 @@ - + The type of channel the listener accepts. @@ -349,16 +349,16 @@ if the of type can be built by the binding element; otherwise, . - and catch the exception generated if it cannot be built. - - - -## Examples - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uechannels/cs/servicesnippets.cs" id="Snippet19"::: - + and catch the exception generated if it cannot be built. + + + +## Examples + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uechannels/cs/servicesnippets.cs" id="Snippet19"::: + ]]> @@ -399,13 +399,13 @@ When overridden in a derived class, returns a copy of the binding element object. A object that is a deep clone of the original. - method to return a deep clone of your binding element. Returning a clone enables the runtime to support the case in which multiple custom bindings share a custom binding element. If a clone is not returned, the run-time behavior is undefined. - - A deep clone of an object creates a copy of the object and a copy of everything directly or indirectly referenced by that object. (This is also called copying the entire object graph.) A shallow clone of an object, by contrast, is a copy of the object only. If the object contains references to other objects, the shallow copy does not create copies of the referred objects; instead, it copies only the references to the original objects. - + method to return a deep clone of your binding element. Returning a clone enables the runtime to support the case in which multiple custom bindings share a custom binding element. If a clone is not returned, the run-time behavior is undefined. + + A deep clone of an object creates a copy of the object and a copy of everything directly or indirectly referenced by that object. (This is also called copying the entire object graph.) A shallow clone of an object, by contrast, is a copy of the object only. If the object contains references to other objects, the shallow copy does not create copies of the referred objects; instead, it copies only the references to the original objects. + ]]> @@ -455,19 +455,19 @@ When overridden in a derived class, returns a typed object requested, if present, from the appropriate layer in the binding stack. The typed object requested if it is present or if it is not present. - [!NOTE] -> If you are adding message headers that must be encrypted you must return a instance with your requirements from this method when asked for . - - - -## Examples - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uechannels/cs/servicesnippets.cs" id="Snippet20"::: - +> If you are adding message headers that must be encrypted you must return a instance with your requirements from this method when asked for . + + + +## Examples + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uechannels/cs/servicesnippets.cs" id="Snippet20"::: + ]]> diff --git a/xml/System.ServiceModel.Channels/CustomBinding.xml b/xml/System.ServiceModel.Channels/CustomBinding.xml index 5b3905cc1c0..9bcdef63601 100644 --- a/xml/System.ServiceModel.Channels/CustomBinding.xml +++ b/xml/System.ServiceModel.Channels/CustomBinding.xml @@ -45,90 +45,90 @@ Defines a binding from a list of binding elements. - from a collection of binding elements that are "stacked" in a specific order: - -- At the top is an optional that allows flowing transactions. - -- Next is an optional that provides a session and ordering mechanism as defined in the WS-ReliableMessaging specification. This notion of a session can cross SOAP and transport intermediaries. - -- Next is an optional security binding element that provides security features like authorization, authentication, protection, and confidentiality. The following security binding elements are provided by Windows Communication Foundation (WCF): - - - - - - - - - - - - - -- Next are the optional message-patterns specified by binding elements: - -- - -- Next are the optional transport upgrades/helpers binding elements: - - - - - - - - - - -- Next is a required message encoding binding element. You can use your own transport or use one of the following message encoding bindings: - - - - - - - - - - -- At the bottom is a required transport element. You can use your own transport or use one of transport binding elements provided by Windows Communication Foundation (WCF): - - - - - - - - - - - - - - - - - - - - - - - The following table summarizes the options for each layer. - -|Layer|Options|Required| -|-----------|-------------|--------------| -|Transaction Flow||No| -|Reliability||No| -|Security|Symmetric, Asymmetric, Transport-Level|No| -|Shape Change||No| -|Transport Upgrades|SSL stream, Windows stream, Peer Resolver|No| -|Encoding|Text, Binary, MTOM, Custom|Yes| -|Transport|TCP, Named Pipes, HTTP, HTTPS, flavors of MSMQ, Custom|Yes| - - In addition, you can define your own binding elements and insert them between any of the preceding defined layers. - - For a discussion on how to use a custom binding to modify a system-provided binding, see [How to: Customize a System-Provided Binding](/dotnet/framework/wcf/extending/how-to-customize-a-system-provided-binding). - + from a collection of binding elements that are "stacked" in a specific order: + +- At the top is an optional that allows flowing transactions. + +- Next is an optional that provides a session and ordering mechanism as defined in the WS-ReliableMessaging specification. This notion of a session can cross SOAP and transport intermediaries. + +- Next is an optional security binding element that provides security features like authorization, authentication, protection, and confidentiality. The following security binding elements are provided by Windows Communication Foundation (WCF): + + - + + - + + - + + - + +- Next are the optional message-patterns specified by binding elements: + +- + +- Next are the optional transport upgrades/helpers binding elements: + + - + + - + + - + +- Next is a required message encoding binding element. You can use your own transport or use one of the following message encoding bindings: + + - + + - + + - + +- At the bottom is a required transport element. You can use your own transport or use one of transport binding elements provided by Windows Communication Foundation (WCF): + + - + + - + + - + + - + + - + + - + + - + + The following table summarizes the options for each layer. + +|Layer|Options|Required| +|-----------|-------------|--------------| +|Transaction Flow||No| +|Reliability||No| +|Security|Symmetric, Asymmetric, Transport-Level|No| +|Shape Change||No| +|Transport Upgrades|SSL stream, Windows stream, Peer Resolver|No| +|Encoding|Text, Binary, MTOM, Custom|Yes| +|Transport|TCP, Named Pipes, HTTP, HTTPS, flavors of MSMQ, Custom|Yes| + + In addition, you can define your own binding elements and insert them between any of the preceding defined layers. + + For a discussion on how to use a custom binding to modify a system-provided binding, see [How to: Customize a System-Provided Binding](/dotnet/framework/wcf/extending/how-to-customize-a-system-provided-binding). + > [!NOTE] -> When calling a WCF service built with .NET Framework 4.0 or later from a WCF client application built with .NET Framework 3.5 or earlier, the configuration file generated by svcutil.exe or adding a service reference from Visual Studio will contain the validity attribute in the binding configuration. This attribute is not recognized by the .NET Framework 3.5 runtime and the application will thrown an with the message "Unrecognized attribute validity". To workaround this problem, remove the validity attribute from the binding configuration. - - - -## Examples - The following example shows how to create a object using a and an - +> When calling a WCF service built with .NET Framework 4.0 or later from a WCF client application built with .NET Framework 3.5 or earlier, the configuration file generated by svcutil.exe or adding a service reference from Visual Studio will contain the validity attribute in the binding configuration. This attribute is not recognized by the .NET Framework 3.5 runtime and the application will thrown an with the message "Unrecognized attribute validity". To workaround this problem, remove the validity attribute from the binding configuration. + + + +## Examples + The following example shows how to create a object using a and an + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_imperative/cs/service.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_imperative/vb/service.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_imperative/vb/service.vb" id="Snippet1"::: + ]]> @@ -172,13 +172,13 @@ Initializes a new instance of the class. - @@ -216,12 +216,12 @@ An of type that contains the binding elements of the channel stack in top-down order. Initializes a new instance of the class with the binding elements from a complete channel stack. - @@ -305,12 +305,12 @@ The of type used to initialize the custom binding. Initializes a new instance of the class from an array of binding elements. - @@ -335,20 +335,11 @@ - A value of the attribute that identifies the element whose settings are used to initialize the binding. - A value of the attribute that identifies the element whose settings are used to initialize the binding. Initializes a new instance of the class. - - - + To be added. The binding element identified by the is . @@ -396,12 +387,12 @@ The of type used to initialize the custom binding. Initializes a new instance of the class from an array of binding elements with a specified name and namespace. - @@ -518,11 +509,11 @@ Gets the URI scheme for transport used by the custom binding. The URI scheme for transport used by the custom binding; or an empty string if there is no transport ( is ). -
diff --git a/xml/System.ServiceModel.Channels/FaultConverter.xml b/xml/System.ServiceModel.Channels/FaultConverter.xml index 17e784cea22..88de6cc166b 100644 --- a/xml/System.ServiceModel.Channels/FaultConverter.xml +++ b/xml/System.ServiceModel.Channels/FaultConverter.xml @@ -115,11 +115,11 @@ Gets the default fault converter. An instance of . -
@@ -166,19 +166,19 @@ if fault was successfully converted; otherwise, . The default is . - ` to support converting fault messages to SOAP exceptions, override this method to create an exception by doing the following steps: - -- Inspect the fault message. - -- If recognized, do the appropriate conversion. - -- If not recognized, convert it by a call to `GetProperty` on the inner channel. - - Transport channels should delegate to to get the default SOAP/WS-Addressing fault converter. - + ` to support converting fault messages to SOAP exceptions, override this method to create an exception by doing the following steps: + +- Inspect the fault message. + +- If recognized, do the appropriate conversion. + +- If not recognized, convert it by a call to `GetProperty` on the inner channel. + + Transport channels should delegate to to get the default SOAP/WS-Addressing fault converter. + ]]>
@@ -223,11 +223,11 @@ if fault message was successfully created; otherwise, . The default is . - ` and override this method to do the following. If a layer can convert the exception it does; otherwise it calls `GetProperty` on its inner channel. Transport channels should delegate to to get the default SOAP/WS-Addressing fault converter. - + ` and override this method to do the following. If a layer can convert the exception it does; otherwise it calls `GetProperty` on its inner channel. Transport channels should delegate to to get the default SOAP/WS-Addressing fault converter. + ]]>
@@ -274,11 +274,11 @@ if fault was successfully converted; otherwise, . The default is . - is an abstract class that you must implement. The current method wraps several parameter error tests around a call to that method. - + is an abstract class that you must implement. The current method wraps several parameter error tests around a call to that method. + ]]> @@ -288,7 +288,7 @@ returned but is . --or- +-or- returned but is not .
@@ -314,8 +314,8 @@ System.Boolean - - + + The SOAP exception. @@ -324,11 +324,11 @@ if fault message was successfully created; otherwise, . The default is . - is an abstract class that you must implement. The current method wraps several error tests around a call to that method. - + is an abstract class that you must implement. The current method wraps several error tests around a call to that method. + ]]> diff --git a/xml/System.ServiceModel.Channels/Message.xml b/xml/System.ServiceModel.Channels/Message.xml index 8347e1e1170..76e7c3aa44b 100644 --- a/xml/System.ServiceModel.Channels/Message.xml +++ b/xml/System.ServiceModel.Channels/Message.xml @@ -43,45 +43,45 @@ Represents the unit of communication between endpoints in a distributed environment. - class provides a means of communicating arbitrary information between a sender and a receiver on a network. It can be used to relay information, suggest or demand a course of action, or request data. - - The structure of a object represents a SOAP envelope. It consists of two distinct parts: the message's body and an optional collection of headers, represented by the class. The message content is application-defined data sent from a sender to a receiver. The message headers enable system and application extensibility to meet the changing requirements, because you can define code to manipulate and respond to specific headers. You can also define your own headers. Message headers are serialized or deserialized along with the contents of the message. - - Messages are received and sent in particular formats. Support is provided for two formats: the standard text-based XML format and a binary-based XML format. The object can be used to represent both SOAP 1.1 and SOAP 1.2 envelopes. Note that an instance of is fixed upon creation and is bound to a specific SOAP version. The property represents the SOAP version of the message. - - A object can be serialized to an external store by using the method. Properties of the message can also be serialized, but they have to be individually identified and serialized separately. Deserializing a message to create an in-memory object can be done using . Properties must also be deserialized individually and manually added to the property collection for the specific instance. - - The size of a object is fixed to the size of data it is transmitting. Every body is modeled as an instance of , with no predefined limit on the size of the stream that the instance is wrapping. However, specific channel providers can have a limit on the size of messages that they process. - - A can be annotated with useful information generated by an entity that has examined and processed the message. This functionality is provided by the and properties. The collection represents the set of SOAP headers on the message. - - The property represents the set of processing-level annotations on the message. Because information in headers is transmitted on the wire, an entity that examines a header must support the underlying version(s) of the protocols used by the header. However, properties provide a more version-independent way of annotating a message. - - To create a instance, use one of the methods. - - It is recommended that a consumer of a message always call when the consumer is finished accessing the contents of the message. This action frees finite system resources (for example, sockets, named pipes) that are tied to the lifetime of the message. - - Special note for Managed C++ users deriving from this class: - -- Put your cleanup code in (On)(Begin)Close (and/or OnAbort), not in a destructor. - -- Avoid destructors: they cause the compiler to auto-generate . - -- Avoid non-reference members: they can cause the compiler to auto-generate . - -- Avoid finalizers; but if you include one, suppress the build warning and call and the finalizer itself from (On)(Begin)Close (and/or OnAbort) to emulate what would have been the auto-generated behavior. - - - -## Examples - The following code example shows a client that uses the channel factory to send a message and read the reply. - + class provides a means of communicating arbitrary information between a sender and a receiver on a network. It can be used to relay information, suggest or demand a course of action, or request data. + + The structure of a object represents a SOAP envelope. It consists of two distinct parts: the message's body and an optional collection of headers, represented by the class. The message content is application-defined data sent from a sender to a receiver. The message headers enable system and application extensibility to meet the changing requirements, because you can define code to manipulate and respond to specific headers. You can also define your own headers. Message headers are serialized or deserialized along with the contents of the message. + + Messages are received and sent in particular formats. Support is provided for two formats: the standard text-based XML format and a binary-based XML format. The object can be used to represent both SOAP 1.1 and SOAP 1.2 envelopes. Note that an instance of is fixed upon creation and is bound to a specific SOAP version. The property represents the SOAP version of the message. + + A object can be serialized to an external store by using the method. Properties of the message can also be serialized, but they have to be individually identified and serialized separately. Deserializing a message to create an in-memory object can be done using . Properties must also be deserialized individually and manually added to the property collection for the specific instance. + + The size of a object is fixed to the size of data it is transmitting. Every body is modeled as an instance of , with no predefined limit on the size of the stream that the instance is wrapping. However, specific channel providers can have a limit on the size of messages that they process. + + A can be annotated with useful information generated by an entity that has examined and processed the message. This functionality is provided by the and properties. The collection represents the set of SOAP headers on the message. + + The property represents the set of processing-level annotations on the message. Because information in headers is transmitted on the wire, an entity that examines a header must support the underlying version(s) of the protocols used by the header. However, properties provide a more version-independent way of annotating a message. + + To create a instance, use one of the methods. + + It is recommended that a consumer of a message always call when the consumer is finished accessing the contents of the message. This action frees finite system resources (for example, sockets, named pipes) that are tied to the lifetime of the message. + + Special note for Managed C++ users deriving from this class: + +- Put your cleanup code in (On)(Begin)Close (and/or OnAbort), not in a destructor. + +- Avoid destructors: they cause the compiler to auto-generate . + +- Avoid non-reference members: they can cause the compiler to auto-generate . + +- Avoid finalizers; but if you include one, suppress the build warning and call and the finalizer itself from (On)(Begin)Close (and/or OnAbort) to emulate what would have been the auto-generated behavior. + + + +## Examples + The following code example shows a client that uses the channel factory to send a message and read the reply. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/message/cs/client.cs" id="Snippet0"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/message/vb/client.vb" id="Snippet0"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/message/vb/client.vb" id="Snippet0"::: + ]]> @@ -225,21 +225,21 @@ Closes the and releases any resources. - does have a finalizer, which causes to be called for you when the message is garbage-collected. This is non-optimal, as the .NET Framework's Garbage Collection (GC) mechanism does not necessarily run when you run out of system resources other than memory. For this reason, you should always call this method when finished with the contents of the message. The method is a synonym for (which also implements). The message also disposes the object that was used to construct the body when it is disposed. - - An is thrown if you call any method or access any properties of the message once it is closed. Calling any method or accessing any properties of other objects related to the message once it is closed, (such as message header collection, message property values, or instances returned for the body or for a header) has undefined behavior. - - - -## Examples - The following code example shows how to create a message, send it to a service and receive a response message. The response message content is displayed and then the message is closed. - + does have a finalizer, which causes to be called for you when the message is garbage-collected. This is non-optimal, as the .NET Framework's Garbage Collection (GC) mechanism does not necessarily run when you run out of system resources other than memory. For this reason, you should always call this method when finished with the contents of the message. The method is a synonym for (which also implements). The message also disposes the object that was used to construct the body when it is disposed. + + An is thrown if you call any method or access any properties of the message once it is closed. Calling any method or accessing any properties of other objects related to the message once it is closed, (such as message header collection, message property values, or instances returned for the body or for a header) has undefined behavior. + + + +## Examples + The following code example shows how to create a message, send it to a service and receive a response message. The response message content is displayed and then the message is closed. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/message/cs/client.cs" id="Snippet0"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/message/vb/client.vb" id="Snippet0"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/message/vb/client.vb" id="Snippet0"::: + ]]> @@ -281,14 +281,14 @@ Stores an entire into a memory buffer for future access. A newly created object. - instance can only be accessed or written once. If you want to access a instance more than once, you should use the class to completely store an entire instance into memory. A instance is constructed by calling of a instance. - + instance can only be accessed or written once. If you want to access a instance more than once, you should use the class to completely store an entire instance into memory. A instance is constructed by calling of a instance. + > [!NOTE] -> If is equal to , this method only stores the body of the message, not the entire message into the memory buffer. - +> If is equal to , this method only stores the body of the message, not the entire message into the memory buffer. + ]]> @@ -306,21 +306,21 @@ Creates a message. - method, the method does not work with JSON messages. - - - -## Examples - The following code example shows a client that uses the channel factory to send a message and read the reply. - + method, the method does not work with JSON messages. + + + +## Examples + The following code example shows a client that uses the channel factory to send a message and read the reply. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/message/cs/client.cs" id="Snippet0"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/message/vb/client.vb" id="Snippet0"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/message/vb/client.vb" id="Snippet0"::: + ]]> @@ -364,11 +364,11 @@ Creates a message that contains a version and an action. A object for the message created. - @@ -396,9 +396,9 @@ System.ServiceModel.Channels.Message - - - + + + A object that specifies the SOAP version to use for the message. @@ -407,11 +407,11 @@ Creates a message that contains a SOAP fault, a version and an action. A object for the message created. - @@ -459,13 +459,13 @@ Creates a message with the specified version, action and body. A object for the message created. - method, the method does not work with JSON messages. - + method, the method does not work with JSON messages. + ]]> @@ -513,11 +513,11 @@ Creates a message with a body that consists of an array of bytes. A object for the message created. - @@ -565,11 +565,11 @@ Creates a message with the specified version, action and body. A object for the message created. - @@ -617,11 +617,11 @@ Creates a message using the specified reader, action and version. A object for the message created. - @@ -669,19 +669,19 @@ Creates a message using the specified reader, action and version. A object for the message created. - takes ownership of `envelopeReader`. - - This method reads the envelope, buffers all the headers into the header collection, and reads up to but not including the `Body` start tag, and returns the message. If the method call throws an exception, it closes the reader. - - The body of the returned message can then be either read or written. - - The message body can be read using the methods on the returned message. The returned object encapsulates all the child elements within the `Body` element. The message body can be written using or . Once written, it cannot be read. - - Closing the message closes the underlying envelope reader. - + takes ownership of `envelopeReader`. + + This method reads the envelope, buffers all the headers into the header collection, and reads up to but not including the `Body` start tag, and returns the message. If the method call throws an exception, it closes the reader. + + The body of the returned message can then be either read or written. + + The message body can be read using the methods on the returned message. The returned object encapsulates all the child elements within the `Body` element. The message body can be written using or . Once written, it cannot be read. + + Closing the message closes the underlying envelope reader. + ]]> @@ -729,19 +729,19 @@ Creates a message using the specified reader, action and version. A object for the message created. - takes ownership of `envelopeReader`. - - This method reads the envelope, buffers all the headers into the header collection, and reads up to but not including the `Body` start tag, and returns the message. If the method call throws an exception, it closes the reader. - - The body of the returned message can then be either read or written. - - The message body can be read using the methods on the returned message. The returned object encapsulates all the child elements within the `Body` element. The message body can be written using or . Once written, it cannot be read. - - Closing the message closes the underlying envelope reader. - + takes ownership of `envelopeReader`. + + This method reads the envelope, buffers all the headers into the header collection, and reads up to but not including the `Body` start tag, and returns the message. If the method call throws an exception, it closes the reader. + + The body of the returned message can then be either read or written. + + The message body can be read using the methods on the returned message. The returned object encapsulates all the child elements within the `Body` element. The message body can be written using or . Once written, it cannot be read. + + Closing the message closes the underlying envelope reader. + ]]> @@ -791,13 +791,13 @@ Creates a message using the specified version, action, message body and serializer. A object for the message created. - method, the method does not work with JSON messages. - + method, the method does not work with JSON messages. + ]]> @@ -827,26 +827,24 @@ System.ServiceModel.Channels.Message - + - - - + + A object that specifies the SOAP version to use for the message. A object that represents a SOAP fault. - A object that represents a SOAP fault. The reason of the SOAP fault. A description of how the message should be processed. Creates a message that contains a SOAP fault, the reason for the fault, a version and an action. A object for the message created. - @@ -876,28 +874,26 @@ System.ServiceModel.Channels.Message - + - - - - + + + A object that specifies the SOAP version to use for the message. A object that represents a SOAP fault. - A object that represents a SOAP fault. The reason of the SOAP fault. The details of the SOAP fault. A description of how the message should be processed. Creates a message that contains a SOAP fault, a reason and the detail for the fault, a version and an action. A object for the message created. - @@ -969,21 +965,21 @@ Retrieves the body of this instance. - methods on the returned message. The returned object encapsulates all the child elements within the `Body` element. Because the body of a message is a stream, it can only be written once, or read once. - - Use the overload when working with JSON messages; the overload does not work. - - - -## Examples - The following code example shows a client that uses the channel factory to send a message and read the reply. - + methods on the returned message. The returned object encapsulates all the child elements within the `Body` element. Because the body of a message is a stream, it can only be written once, or read once. + + Use the overload when working with JSON messages; the overload does not work. + + + +## Examples + The following code example shows a client that uses the channel factory to send a message and read the reply. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/message/cs/client.cs" id="Snippet0"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/message/vb/client.vb" id="Snippet0"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/message/vb/client.vb" id="Snippet0"::: + ]]> @@ -1026,13 +1022,13 @@ Retrieves the body of this instance. An object of type that contains the body of this message. - instance has a body that corresponds to the SOAP body. It can be accessed as an by calling . It is initially positioned directly after the `` element, and it returns `EOF` on reaching the `` element. Alternatively, if you expect the body to contain a serialized object, you can call instead. You should be aware that a message body can only be accessed once and a message can only be written once. If you want to access the `Body` multiple times, use to create a instance. - - Use the overload when working with JSON messages; the overload does not work. - + instance has a body that corresponds to the SOAP body. It can be accessed as an by calling . It is initially positioned directly after the `` element, and it returns `EOF` on reaching the `` element. Alternatively, if you expect the body to contain a serialized object, you can call instead. You should be aware that a message body can only be accessed once and a message can only be written once. If you want to access the `Body` multiple times, use to create a instance. + + Use the overload when working with JSON messages; the overload does not work. + ]]> @@ -1078,13 +1074,13 @@ Retrieves the body of this using the specified serializer. An object of type that contains the body of this message. - instance has a body that corresponds to the SOAP body. It can be accessed as an by calling . It is initially positioned directly after the `` element, and it returns `EOF` on reaching the `` element. Alternatively, if you expect the body to contain a serialized object, you can call instead. You should be aware that a message body can only be accessed once and a message can only be written once. If you want to access the body multiple times, use to create a instance. - - Use the overload when working with JSON messages; the overload does not work. - + instance has a body that corresponds to the SOAP body. It can be accessed as an by calling . It is initially positioned directly after the `` element, and it returns `EOF` on reaching the `` element. Alternatively, if you expect the body to contain a serialized object, you can call instead. You should be aware that a message body can only be accessed once and a message can only be written once. If you want to access the body multiple times, use to create a instance. + + Use the overload when working with JSON messages; the overload does not work. + ]]> @@ -1125,20 +1121,20 @@ - The local name of the XML node. - + The local name of the XML node. + The name of the element that corresponds to this member. This string must be a valid XML element name. - The namespace to which this XML element belongs. - + The namespace to which this XML element belongs. + The namespace URI of the element that corresponds to this member. The system does not validate any URIs other than transport addresses. Retrieves the attributes of the message body. The attributes of the message body. - instance has a body that corresponds to the SOAP body. It can be accessed as an by calling . It is initially positioned directly after the `` element, and it returns `EOF` on reaching the `` element. Alternatively, if you expect the body to contain a serialized object, you can call instead. You should be aware that a message body can only be accessed once and a message can only be written once. If you want to access the body multiple times, use to create a instance. - + instance has a body that corresponds to the SOAP body. It can be accessed as an by calling . It is initially positioned directly after the `` element, and it returns `EOF` on reaching the `` element. Alternatively, if you expect the body to contain a serialized object, you can call instead. You should be aware that a message body can only be accessed once and a message can only be written once. If you want to access the body multiple times, use to create a instance. + ]]> @@ -1181,11 +1177,11 @@ Gets the XML dictionary reader that accesses the body content of this message. A object that accesses the body content of this message. - instance has a body that corresponds to the SOAP body. It can be accessed as an by calling . It is initially positioned directly after the `` element. Alternatively, if you expect the body to contain a serialized object, you can call instead. You should be aware that a message body can only be accessed once and a message can only be written once. If you want to access the body multiple times, use to create a instance. - + instance has a body that corresponds to the SOAP body. It can be accessed as an by calling . It is initially positioned directly after the `` element. Alternatively, if you expect the body to contain a serialized object, you can call instead. You should be aware that a message body can only be accessed once and a message can only be written once. If you want to access the body multiple times, use to create a instance. + ]]> The message is closed. @@ -1225,32 +1221,32 @@ When overridden in a derived class, gets the headers of the message. A object that represents the headers of the message. - can have zero or more headers that are used as an extension mechanism to pass information in messages that is application-specific. You can use to add message headers to a message by calling the method. - - Windows Communication Foundation (WCF) provides a number of predefined message headers, as shown in the following table. - -|Header Name|Contains the header name.| -|-----------------|-------------------------------| -|To|Contains the role that the message is targeting.| -|Action|Provides a description of how the message should be processed.| -|FaultTo|Contains the address of the node to which faults should be sent.| -|From|Contains the address of the node that sent the message.| -|Request|Indicates whether the message is a request.| -|MessageID|Contains the unique ID of the message.| -|RelatesTo|Contains the IDs of messages that are related to this message.| -|ReplyTo|Contains the address of the node to which a reply should be sent for a request.| - - - -## Examples - The following code example shows a client that uses the channel factory to send a message and read the reply. - + can have zero or more headers that are used as an extension mechanism to pass information in messages that is application-specific. You can use to add message headers to a message by calling the method. + + Windows Communication Foundation (WCF) provides a number of predefined message headers, as shown in the following table. + +|Header Name|Contains the header name.| +|-----------------|-------------------------------| +|To|Contains the role that the message is targeting.| +|Action|Provides a description of how the message should be processed.| +|FaultTo|Contains the address of the node to which faults should be sent.| +|From|Contains the address of the node that sent the message.| +|Request|Indicates whether the message is a request.| +|MessageID|Contains the unique ID of the message.| +|RelatesTo|Contains the IDs of messages that are related to this message.| +|ReplyTo|Contains the address of the node to which a reply should be sent for a request.| + + + +## Examples + The following code example shows a client that uses the channel factory to send a message and read the reply. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/message/cs/client.cs" id="Snippet0"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/message/vb/client.vb" id="Snippet0"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/message/vb/client.vb" id="Snippet0"::: + ]]> The message has been disposed of. @@ -1679,11 +1675,11 @@ - The local name of the XML node. - + The local name of the XML node. + The name of the element that corresponds to this member. This string must be a valid XML element name. - The namespace to which this XML element belongs. - + The namespace to which this XML element belongs. + The namespace URI of the element that corresponds to this member. The system does not validate any URIs other than transport addresses. Called when the attributes of the message body is retrieved. The attributes of the message body. @@ -1949,11 +1945,11 @@ When overridden in a derived class, gets a set of processing-level annotations to the message. A that contains a set of processing-level annotations to the message. - The message has been disposed of. @@ -1998,11 +1994,11 @@ Gets the current state of this . A that contains the current state of this . - object is a stream, it can only be read or written once. This is enforced by maintaining the current state of the object. A object can be read, written, or copied when in the state. Other states are , and , which means that the respective action has been performed already once. - + object is a stream, it can only be read or written once. This is enforced by maintaining the current state of the object. A object can be read, written, or copied when in the state. Other states are , and , which means that the respective action has been performed already once. + ]]> @@ -2049,14 +2045,14 @@ Closes all the resources used by this message. This method cannot be inherited. - . This method leaves the in an unusable state. After calling this method, you must release all references to the so the garbage collector can reclaim the memory that the resided in. - + . This method leaves the in an unusable state. After calling this method, you must release all references to the so the garbage collector can reclaim the memory that the resided in. + > [!NOTE] -> Always call this method before you release your last reference to the . Otherwise, the resources it is using are not freed until the garbage collector calls the object's `Finalize` method. - +> Always call this method before you release your last reference to the . Otherwise, the resources it is using are not freed until the garbage collector calls the object's `Finalize` method. + ]]> @@ -2130,16 +2126,16 @@ When overridden in a derived class, gets the SOAP version of the message. A object that represents the SOAP version. - and that correspond to SOAP 1.1 and SOAP 1.2 respectively. - - Knowing the underlying SOAP version is important because the structure of is firmly correlated with that of a SOAP message. - + and that correspond to SOAP 1.1 and SOAP 1.2 respectively. + + Knowing the underlying SOAP version is important because the structure of is firmly correlated with that of a SOAP message. + > [!IMPORTANT] -> Inheritors must note that when overridden in a derived class, this method returns a object for the SOAP version of the message. - +> Inheritors must note that when overridden in a derived class, this method returns a object for the SOAP version of the message. + ]]> The message has been disposed of. @@ -2154,11 +2150,11 @@ Serializes the body element to XML. - @@ -2199,11 +2195,11 @@ An object to be used to write the body element. Writes the body element using the specified . - @@ -2246,11 +2242,11 @@ The object to be used to write the body of the message. Serializes the message body using the specified . - @@ -2309,11 +2305,11 @@ Serializes the entire message. - for the message. - + for the message. + ]]> @@ -2354,11 +2350,11 @@ An object to be used to write the message. Serializes the entire message using the specified . - instance exists for the message. - + instance exists for the message. + ]]> @@ -2403,11 +2399,11 @@ The object to be used to write the entire message. Serializes the entire message using the specified . - for the message. - + for the message. + ]]> diff --git a/xml/System.ServiceModel.Channels/MessageFault.xml b/xml/System.ServiceModel.Channels/MessageFault.xml index db1a8c1c0bd..2b84e169c55 100644 --- a/xml/System.ServiceModel.Channels/MessageFault.xml +++ b/xml/System.ServiceModel.Channels/MessageFault.xml @@ -39,23 +39,23 @@ Represents an in-memory representation of a SOAP fault that can be passed to to create a message that contains a fault. - class any time you need an in-memory SOAP fault that can be modified and used to create a SOAP message that contains the fault information. - - Typically, the class is used when implementing the interface. In this case, Windows Communication Foundation (WCF) passes the object and you use it for your specific needs (for example, you can customize the or to log fault information). However, can be used anywhere custom SOAP fault message handling is required. - - - -## Examples - The following code example shows the most common use of . Both the and pass in a object that can be modified and returned to the system (in the case of ) or used to perform some custom fault-related behavior (in the case of ). - - In this example, the method converts all objects into a object that contains a object of type `GreetingFault` and returns that customized to WCF. - + class any time you need an in-memory SOAP fault that can be modified and used to create a SOAP message that contains the fault information. + + Typically, the class is used when implementing the interface. In this case, Windows Communication Foundation (WCF) passes the object and you use it for your specific needs (for example, you can customize the or to log fault information). However, can be used anywhere custom SOAP fault message handling is required. + + + +## Examples + The following code example shows the most common use of . Both the and pass in a object that can be modified and returned to the system (in the case of ) or used to perform some custom fault-related behavior (in the case of ). + + In this example, the method converts all objects into a object that contains a object of type `GreetingFault` and returns that customized to WCF. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/ierrorhandler/cs/ierrorhandler.cs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/ierrorhandler/vb/ierrorhandler.vb" id="Snippet6"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/ierrorhandler/vb/ierrorhandler.vb" id="Snippet6"::: + ]]> @@ -245,8 +245,8 @@ System.ServiceModel.Channels.MessageFault - - + + The fault code for the fault message. @@ -277,8 +277,8 @@ System.ServiceModel.Channels.MessageFault - - + + The fault code for the fault message. @@ -309,9 +309,9 @@ System.ServiceModel.Channels.MessageFault - - - + + + The fault code for the fault message. @@ -349,18 +349,16 @@ System.ServiceModel.Channels.MessageFault - - - + + + - The fault code for the fault message. The reason for the fault. The fault detail object. The serializer to use when serializing the detail object. - The serializer to use when serializing the detail object. Returns a new object that uses the specified , , detail object, and objects. A object with initial values from the passed in parameters. To be added. @@ -387,19 +385,17 @@ System.ServiceModel.Channels.MessageFault - - - + + + - - + The fault code for the fault message. The reason for the fault. The fault detail object. The serializer to use when serializing the detail object. - The serializer to use when serializing the detail object. The value of the actor. Returns a new object that uses the specified , , detail object, , and actor. A object with initial values from the passed in parameters. @@ -427,20 +423,18 @@ System.ServiceModel.Channels.MessageFault - - - + + + - - - + + The fault code for the fault message. The reason for the fault. The fault detail object. The serializer to use when serializing the detail object. - The serializer to use when serializing the detail object. The value of the actor. The value of the node. Returns a new object that uses the specified , , detail object, , actor, and node values. @@ -749,11 +743,11 @@ The version of the SOAP envelope to write. Invoked prior to writing the detail contents. - method to participate in the detail writing process. The default behavior is to call followed by . - + method to participate in the detail writing process. The default behavior is to call followed by . + ]]> @@ -794,11 +788,11 @@ The used to write the detail element. When overridden in a non-abstract derived class, writes the contents of the detail element. - method is called subsequent to and prior to writing the end element. - + method is called subsequent to and prior to writing the end element. + ]]> @@ -944,8 +938,8 @@ System.Void - - + + The used to write the message fault. @@ -975,8 +969,8 @@ System.Void - - + + The used to write the message fault. diff --git a/xml/System.ServiceModel.Channels/ReliableSessionBindingElement.xml b/xml/System.ServiceModel.Channels/ReliableSessionBindingElement.xml index 5b7cb64a5b0..26c4f8eefec 100644 --- a/xml/System.ServiceModel.Channels/ReliableSessionBindingElement.xml +++ b/xml/System.ServiceModel.Channels/ReliableSessionBindingElement.xml @@ -36,41 +36,41 @@ Represents the binding element that can produce the sending and receiving channels required for a reliable session between endpoints. - provides an optional layer in the stack that can establish a reliable session between endpoints and configure the behavior of this session. - - The is provided on the standard bindings in the following table. - -|Binding|Default| -|-------------|-------------| -||Off| -||Off| -||On (required)| - - - -## Examples - The can be added to any custom binding. This is done using the following configuration elements. - -``` - - - - - - - -``` - - The following sample code demonstrates how to use in code. - + provides an optional layer in the stack that can establish a reliable session between endpoints and configure the behavior of this session. + + The is provided on the standard bindings in the following table. + +|Binding|Default| +|-------------|-------------| +||Off| +||Off| +||On (required)| + + + +## Examples + The can be added to any custom binding. This is done using the following configuration elements. + +``` + + + + + + + +``` + + The following sample code demonstrates how to use in code. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_imperative/cs/service.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_imperative/vb/service.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_imperative/vb/service.vb" id="Snippet1"::: + ]]> @@ -177,13 +177,13 @@ Gets or sets the interval of time that a destination waits before sending an acknowledgment to the message source on reliable channels that are created by the factory. The that specifies the interval of time that a service waits until sending an acknowledgment to the message source. The default value is 2 seconds. - but not , then this setting is not used. - - The value that is set with the property is a recommendation to the infrastructure and not a hard limit. - + but not , then this setting is not used. + + The value that is set with the property is a recommendation to the infrastructure and not a hard limit. + ]]> The value set is less than or equal to zero. @@ -224,17 +224,17 @@ Returns a factory that creates a channel of a specified type that supports a reliable session. A of type initialized from the . - produced by the factory is of type `TChannel`. The types of `TChannel` supported on the client is dependent of the types of underlying channels that connect to the service. The following table indicates what reliable session channel types are supported as a function of the underlying channels. - -|Support for Reliable Session `TChannel` Types by Underlying Channel Types|IRequestChannel|IRequestSessionChannel|IDuplexChannel|IDuplexSessionChannel| -|-------------------------------------------------------------------------------|---------------------|----------------------------|--------------------|---------------------------| -|IOutputSessionChannel|Yes|Yes|Yes|Yes| -|IRequestSessionChannel|Yes|Yes|No|No| -|IDuplexSessionChannel|No|No|Yes|Yes| - + produced by the factory is of type `TChannel`. The types of `TChannel` supported on the client is dependent of the types of underlying channels that connect to the service. The following table indicates what reliable session channel types are supported as a function of the underlying channels. + +|Support for Reliable Session `TChannel` Types by Underlying Channel Types|IRequestChannel|IRequestSessionChannel|IDuplexChannel|IDuplexSessionChannel| +|-------------------------------------------------------------------------------|---------------------|----------------------------|--------------------|---------------------------| +|IOutputSessionChannel|Yes|Yes|Yes|Yes| +|IRequestSessionChannel|Yes|Yes|No|No| +|IDuplexSessionChannel|No|No|Yes|Yes| + ]]> @@ -269,7 +269,7 @@ - + The that the listener is built to accept. @@ -277,17 +277,17 @@ Returns a listener that accepts a channel of a specified type that supports a reliable session. The of type initialized from the . - accepted by the listener is of type `TChannel`. The types of `TChannel` supported on the server that hosts the service is dependent of the types of underlying channels used to connect to the client. The following table indicates what reliable session channel types are supported as a function of the underlying channels. - -|Support for Reliable Session `TChannel` Types by Underlying Channel Types|IReplyChannel|IReplySessionChannel|IDuplexChannel|IDuplexSessionChannel| -|-------------------------------------------------------------------------------|-------------------|--------------------------|--------------------|---------------------------| -|IInputSessionChannel|Yes|Yes|Yes|Yes| -|IReplySessionChannel|Yes|Yes|No|No| -|IDuplexSessionChannel|No|No|Yes|Yes| - + accepted by the listener is of type `TChannel`. The types of `TChannel` supported on the server that hosts the service is dependent of the types of underlying channels used to connect to the client. The following table indicates what reliable session channel types are supported as a function of the underlying channels. + +|Support for Reliable Session `TChannel` Types by Underlying Channel Types|IReplyChannel|IReplySessionChannel|IDuplexChannel|IDuplexSessionChannel| +|-------------------------------------------------------------------------------|-------------------|--------------------------|--------------------|---------------------------| +|IInputSessionChannel|Yes|Yes|Yes|Yes| +|IReplySessionChannel|Yes|Yes|No|No| +|IDuplexSessionChannel|No|No|Yes|Yes| + ]]> @@ -330,11 +330,11 @@ if the of type can be built; otherwise, . - . - + . + ]]> @@ -367,7 +367,7 @@ - + The that the channel listener, if build, accepts. @@ -376,13 +376,13 @@ if the that can produce an of type can be built by the binding element; otherwise, . - . - + . + ]]> @@ -459,11 +459,11 @@ if the reliable session has flow control enabled; otherwise, . The default is . - @@ -546,13 +546,13 @@ Gets or sets an interval of time that a service remains inactive before closing. The that specifies the interval of time that a service remains inactive before closing. The default value is 10 minutes. - time interval passes with no activity, the session is aborted by the infrastructure and the channel faults. The reliable session is torn down unilaterally. - - If the sending application has no messages to send then the reliable session is normally not faulted because of inactivity; instead a keep-alive mechanism keeps the session active indefinitely. Note that the dispatcher can independently abort the reliable session if no application messages are sent or received. Thus, the inactivity timeout typically expires if network conditions are such that no messages are received or if there is a failure on the sender. - + time interval passes with no activity, the session is aborted by the infrastructure and the channel faults. The reliable session is torn down unilaterally. + + If the sending application has no messages to send then the reliable session is normally not faulted because of inactivity; instead a keep-alive mechanism keeps the session active indefinitely. Note that the dispatcher can independently abort the reliable session if no application messages are sent or received. Thus, the inactivity timeout typically expires if network conditions are such that no messages are received or if there is a failure on the sender. + ]]> The value set is less than or equal to zero or greater than either Int32.MaxValue or TimeSpan.MaxValue. @@ -595,13 +595,13 @@ Gets or sets the largest number of channels that can be pending during the reliable session. The largest number of channels that can be pending. The default value is 4. - The value set is less than or equal to zero or greater than 16384. @@ -644,15 +644,15 @@ Gets or sets the maximum number of times that a message attempts to be transferred during the reliable session. The maximum number of times that a message attempts to be re-sent. The minimum value is 1; the maximum is Int32.MaxValue; and the default value is 8. - number of times. Not receiving an acknowledgment before this limit is reached is considered a fatal communication failure and causes the channel faulted event to be raised. - - The infrastructure uses an exponential back-off algorithm to determine when to retransmit, based on a computed average round-trip time. The initial retry time is computed based on the measured roundtrip time of establishing the session. The retransmission algorithm doubles the delay with every attempt, which results in approximately 8.5 minutes passing between the first transmission attempt and the last retransmission attempt. The time for the first retransmission attempt is adjusted according to the calculated round-trip time and the resulting stretch of time that those attempts take varies accordingly. This allows the retransmission time to dynamically adapt to varying network conditions. - + number of times. Not receiving an acknowledgment before this limit is reached is considered a fatal communication failure and causes the channel faulted event to be raised. + + The infrastructure uses an exponential back-off algorithm to determine when to retransmit, based on a computed average round-trip time. The initial retry time is computed based on the measured roundtrip time of establishing the session. The retransmission algorithm doubles the delay with every attempt, which results in approximately 8.5 minutes passing between the first transmission attempt and the last retransmission attempt. The time for the first retransmission attempt is adjusted according to the calculated round-trip time and the resulting stretch of time that those attempts take varies accordingly. This allows the retransmission time to dynamically adapt to varying network conditions. + ]]> The value set is less than or equal to zero. @@ -695,15 +695,15 @@ Gets or sets the largest number of messages that can exist in either the send buffer or the receive buffer. The largest number of messages that can be buffered. The minimum value is 1; the maximum value is 4096; and the default value is 32. - property can be set on both the sender and the receiver. This value is included in the binding policy of the WSDL, so if you use the [ServiceModel Metadata Utility Tool (Svcutil.exe)](/dotnet/framework/wcf/servicemodel-metadata-utility-tool-svcutil-exe) to construct your client, it has the same value. Otherwise this value is whatever you set it to be on the client. - - When this limit is reached on the sender, additional calls to send are blocked. When this limit is reached on the receiver, new messages that arrive on the underlying channel are not accepted. - - A reliable session uses a windowing protocol to help improve network utilization. The amount of buffering required is directly derived from the size of the transmission window. When tuning this value, note that the optimal transmission window is related to the bandwidth and the latency in a straight-forward way. The ideal maximum window size is the bandwidth times the latency. Anything smaller yields less than 100% network utilization; anything larger is just wasted space. - + property can be set on both the sender and the receiver. This value is included in the binding policy of the WSDL, so if you use the [ServiceModel Metadata Utility Tool (Svcutil.exe)](/dotnet/framework/wcf/servicemodel-metadata-utility-tool-svcutil-exe) to construct your client, it has the same value. Otherwise this value is whatever you set it to be on the client. + + When this limit is reached on the sender, additional calls to send are blocked. When this limit is reached on the receiver, new messages that arrive on the underlying channel are not accepted. + + A reliable session uses a windowing protocol to help improve network utilization. The amount of buffering required is directly derived from the size of the transmission window. When tuning this value, note that the optimal transmission window is related to the bandwidth and the latency in a straight-forward way. The ideal maximum window size is the bandwidth times the latency. Anything smaller yields less than 100% network utilization; anything larger is just wasted space. + ]]> The value set is less than or equal to one or greater than 4096. @@ -751,11 +751,11 @@ if messages must be delivered in the order in which they are sent; otherwise, . The default is . - to . - + to . + ]]> @@ -797,11 +797,11 @@ Gets or sets the version of WS-ReliableMessaging specified by the binding element. An instance derived from that represents the version of the WS-ReliableMessaging protocol used by the configuration element. - diff --git a/xml/System.ServiceModel.Channels/SecurityBindingElement.xml b/xml/System.ServiceModel.Channels/SecurityBindingElement.xml index 0e88f6e513e..b28fd2b95f7 100644 --- a/xml/System.ServiceModel.Channels/SecurityBindingElement.xml +++ b/xml/System.ServiceModel.Channels/SecurityBindingElement.xml @@ -42,32 +42,32 @@ An abstract class that, when implemented, represents a binding element that supports channel SOAP message security. - , , and . These implementations model the bindings defined in the WS-Security Policy specification. - - A custom binding contains a collection of binding elements arranged in a specific order: the element that represents the top of the binding stack is added first, the next element down in the binding stack is added second, and so on. - - To add this class to a binding, do the following: - -1. Create a . - -2. Create a custom binding element that is above this binding element in the binding stack, such as the optional and . - -3. Add these elements in the order previously described to the using the method. - -4. Create an instance of a security binding element derived from , such as , , or . - -5. Add the derived security binding element to the collection. - -6. Add any additional custom binding elements to the collection, such as . - - For more information about using a , see [SecurityBindingElement Authentication Modes](/dotnet/framework/wcf/feature-details/securitybindingelement-authentication-modes) and [How to: Create a Custom Binding Using the SecurityBindingElement](/dotnet/framework/wcf/feature-details/how-to-create-a-custom-binding-using-the-securitybindingelement). - + , , and . These implementations model the bindings defined in the WS-Security Policy specification. + + A custom binding contains a collection of binding elements arranged in a specific order: the element that represents the top of the binding stack is added first, the next element down in the binding stack is added second, and so on. + + To add this class to a binding, do the following: + +1. Create a . + +2. Create a custom binding element that is above this binding element in the binding stack, such as the optional and . + +3. Add these elements in the order previously described to the using the method. + +4. Create an instance of a security binding element derived from , such as , , or . + +5. Add the derived security binding element to the collection. + +6. Add any additional custom binding elements to the collection, such as . + + For more information about using a , see [SecurityBindingElement Authentication Modes](/dotnet/framework/wcf/feature-details/securitybindingelement-authentication-modes) and [How to: Create a Custom Binding Using the SecurityBindingElement](/dotnet/framework/wcf/feature-details/how-to-create-a-custom-binding-using-the-securitybindingelement). + > [!NOTE] -> Once a object is created, you should treat its properties as immutable. Calling `set` on some properties may have unpredictable effects: the binding may behave as if the property retained its old value, with a runtime failure being the only indication of an issue. Two properties known to behave this way are and . There may be other properties of which this is also true. - +> Once a object is created, you should treat its properties as immutable. Calling `set` on some properties may have unpredictable effects: the binding may behave as if the property retained its old value, with a runtime failure being the only indication of an issue. Two properties known to behave this way are and . There may be other properties of which this is also true. + ]]> SecurityBindingElement Authentication Modes @@ -154,13 +154,13 @@ Creates a channel factory based on the settings and the binding context passed in. The channel factory created is a SOAP message security channel factory, which internally has a reference to the channel factory that corresponds to the binding context, (which includes the transport channel factory). A channel factory based on the settings and the binding context passed in. - . That method, when implemented in a derived class, creates a channel factory, which is used to create a channel that processes outgoing messages for this binding. - + . That method, when implemented in a derived class, creates a channel factory, which is used to create a channel that processes outgoing messages for this binding. + ]]> @@ -212,11 +212,11 @@ When implemented, creates a channel factory of a specified type. A channel factory of a specified type. - , which does error checking, calls this method. When this method is implemented in a derived class, it creates a channel factory, which is used to create a channel that processes outgoing messages for this binding. - + , which does error checking, calls this method. When this method is implemented in a derived class, it creates a channel factory, which is used to create a channel that processes outgoing messages for this binding. + ]]> @@ -260,13 +260,13 @@ Creates a channel listener based on the settings and the binding context passed in. A channel listener based on the settings and the binding context passed in. - . That method, when implemented in a derived class, creates a channel listener, which is used to create a channel that processes incoming messages for this binding. - + . That method, when implemented in a derived class, creates a channel listener, which is used to create a channel that processes incoming messages for this binding. + ]]> @@ -310,11 +310,11 @@ When implemented, creates a channel listener of a specified type. A channel listener of a specified type. - , which does error checking, calls this method. When this method is implemented in a derived class, it creates a channel listener, which is used to create a channel that processes outgoing messages for this binding. - + , which does error checking, calls this method. When this method is implemented in a derived class, it creates a channel listener, which is used to create a channel that processes outgoing messages for this binding. + ]]> @@ -367,11 +367,11 @@ if a channel factory of the specified type can be built; otherwise, . - @@ -415,11 +415,11 @@ if a channel listener of the specified type can be built; otherwise, . - @@ -450,21 +450,21 @@ Creates a symmetric security binding element that is configured for anonymous client authentication and certificate-based server authentication. A that holds the new binding. - set to and set to `true`. - - - -## Examples - The following code shows how to call this method. - + set to and set to `true`. + + + +## Examples + The following code shows how to call this method. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/c_custombindingsauthmode/cs/source.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/c_custombindingsauthmode/vb/source.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/c_custombindingsauthmode/vb/source.vb" id="Snippet3"::: + ]]> @@ -477,14 +477,14 @@ Creates a security binding element that expects clients to do certificate-based authentication using SOAP message security. This binding element expects the transport to provide server authentication as well as message protection (for example, HTTPS). - [!NOTE] -> Once a object is created by calling this method, the property should be treated as immutable. Inconsistent binding behavior may occur if this value is modified. - +> Once a object is created by calling this method, the property should be treated as immutable. Inconsistent binding behavior may occur if this value is modified. + ]]> @@ -522,19 +522,19 @@ Creates a security binding element that expects clients to do certificate-based authentication using SOAP message security. A object. - property of the class. - - The created binding has set to `true`. - - The object returned from has its property set to `false`. - - The object returned from has its property set to `false`. - + property of the class. + + The created binding has set to `true`. + + The object returned from has its property set to `false`. + + The object returned from has its property set to `false`. + ]]> @@ -575,17 +575,17 @@ Creates a security binding element that expects clients to do certificate-based authentication using SOAP message security. A object. - . - - The created binding has set to `true`. - - The object returned from has its property set to `false`. - - The object returned from has its property set to `false`. - + . + + The created binding has set to `true`. + + The object returned from has its property set to `false`. + + The object returned from has its property set to `false`. + ]]> @@ -616,13 +616,13 @@ Creates a binding element using a certificate to sign messages. This binding element can be used only for one-way message exchanges and is capable only of signing the message. A object. - object returned from has its property set to `false`. - - This binding element requires the client to configure a certificate for authentication purposes. - + object returned from has its property set to `false`. + + This binding element requires the client to configure a certificate for authentication purposes. + ]]> @@ -654,14 +654,14 @@ Creates a symmetric security binding element that is configured to require client authentication using a symmetric-key based issued token. A object. - [!NOTE] -> Once a object is created by calling this method, the property should be treated as immutable. Inconsistent binding behavior may occur if this value is modified. - +> Once a object is created by calling this method, the property should be treated as immutable. Inconsistent binding behavior may occur if this value is modified. + ]]> @@ -696,16 +696,16 @@ Creates a symmetric security binding element that is configured to require client authentication based on an issued token and server authentication based on the server certificate. A object. - set to `true` and set to . - + set to `true` and set to . + > [!NOTE] -> Once a object is created by calling this method, the property should be treated as immutable. Inconsistent binding behavior may occur if this value is modified. - +> Once a object is created by calling this method, the property should be treated as immutable. Inconsistent binding behavior may occur if this value is modified. + ]]> @@ -720,13 +720,13 @@ Creates a symmetric security binding element that is configured to require client authentication based on an issued token and server authentication based on the server certificate. - parameter. One of them includes a parameter that specifies whether cancellation is required. - + parameter. One of them includes a parameter that specifies whether cancellation is required. + ]]> @@ -764,13 +764,13 @@ Creates a symmetric security binding element that is configured to require client authentication based on an issued token and server authentication based on the server certificate. A object. - set to `true` and set to . - + set to `true` and set to . + ]]> @@ -807,11 +807,11 @@ Creates a symmetric security binding element that is configured to require client authentication based on an issued token and server authentication based on the server certificate. A object. - set to `true` and set to . - + set to `true` and set to . + ]]> @@ -853,18 +853,18 @@ Creates a security binding element configured to require SOAP security based client authentication using an issued token. This binding element requires the transport to provide server authentication and message protection (for example, HTTPS). A object. - set to `true`. - - The object returned from has its property set to `false`. - - The object returned from has its property set to `false`. - + set to `true`. + + The object returned from has its property set to `false`. + + The object returned from has its property set to `false`. + > [!NOTE] -> Once a object is created by calling this method, the property should be treated as immutable. Inconsistent binding behavior may occur if this value is modified. - +> Once a object is created by calling this method, the property should be treated as immutable. Inconsistent binding behavior may occur if this value is modified. + ]]> @@ -895,11 +895,11 @@ Creates a symmetric security binding element that is configured to require client authentication based on the client's Kerberos token. A object. - @@ -928,15 +928,15 @@ Creates a security binding element that is configured to require SOAP-security based client authentication using the client's Kerberos token. This binding element requires the transport to provide server authentication and message protection (for example, HTTPS). A object. - set to `true`. The object returned from has its property set to `false`. - - The object returned from has its property set to `false`. - + set to `true`. The object returned from has its property set to `false`. + + The object returned from has its property set to `false`. + ]]> @@ -949,11 +949,11 @@ Creates an asymmetric security binding element that is configured to require certificate-based client authentication as well as certificate-based server authentication. - @@ -986,20 +986,20 @@ Creates an asymmetric security binding element that is configured to require certificate-based client authentication as well as certificate-based server authentication. A object. - is actually created. - - - -## Examples - The following code shows how to call this method. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/c_createsecuresession/cs/secureservice.cs" id="Snippet5"::: - + is actually created. + + + +## Examples + The following code shows how to call this method. + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/c_createsecuresession/cs/secureservice.cs" id="Snippet5"::: + ]]> @@ -1041,16 +1041,16 @@ Creates an asymmetric security binding element that is configured to require certificate-based client authentication as well as certificate-based server authentication. A object. - [!NOTE] -> Once a object is created by calling this method, the property is immutable. Calling `set` on it does not change it. - +> Once a object is created by calling this method, the property is immutable. Calling `set` on it does not change it. + ]]> @@ -1091,14 +1091,14 @@ Creates an asymmetric security binding element that is configured to require certificate-based client authentication as well as certificate-based server authentication. A object. - [!NOTE] -> Once a object is created by calling this method, the property should be treated as immutable. Inconsistent binding behavior may occur if this value is modified. - +> Once a object is created by calling this method, the property should be treated as immutable. Inconsistent binding behavior may occur if this value is modified. + ]]> @@ -1167,13 +1167,13 @@ Creates an asymmetric security binding element that is configured to require certificate-based client authentication as well as certificate-based server authentication. This authentication mode can be used to secure duplex message exchange patterns and requires the service to be configured with the client certificate out of band. An object. - [!NOTE] -> Once a object is created by calling this method, the property should be treated as immutable. Inconsistent binding behavior may occur if this value is modified. - +> Once a object is created by calling this method, the property should be treated as immutable. Inconsistent binding behavior may occur if this value is modified. + ]]> @@ -1236,17 +1236,17 @@ Creates a symmetric security binding element that is configured to establish a secure conversation between the client and service. The security context token issued at the end of the secure conversation handshake is used to secure the messages. The bootstrap security binding element specifies how the secure conversation handshake messages are secured. A object. - , the binding element returned by this method is also one, and is set to `true`; and the object returned from has its property set to `false`; and the object returned from has its property set to `false`. - - Otherwise, a is returned, with set to `false`. - + , the binding element returned by this method is also one, and is set to `true`; and the object returned from has its property set to `false`; and the object returned from has its property set to `false`. + + Otherwise, a is returned, with set to `false`. + ]]> @@ -1283,8 +1283,8 @@ System.ServiceModel.Channels.SecurityBindingElement - - + + A that contains specification on how the secure conversation handshake messages are secured. @@ -1293,27 +1293,27 @@ Creates a symmetric security binding element that is configured to establish a secure conversation between the client and service. The security context token issued at the end of the secure conversation handshake is used to secure the messages. A object. - , the binding element returned by this method is also a `TransportSecurityBindingElement`, and is set to `true`; and the object returned from has its property set to `false`; and the object returned from has its property set to `false`. - - Otherwise, a is returned, with set to `false`. - + , the binding element returned by this method is also a `TransportSecurityBindingElement`, and is set to `true`; and the object returned from has its property set to `false`; and the object returned from has its property set to `false`. + + Otherwise, a is returned, with set to `false`. + > [!NOTE] -> When impersonation is required on Windows XP, use a secure session without a security context token. When security context tokens are used with impersonation an is thrown. For more information, see [Unsupported Scenarios](/dotnet/framework/wcf/feature-details/unsupported-scenarios). For more information about secure sessions, see [Secure Sessions](/dotnet/framework/wcf/feature-details/secure-sessions). - - - -## Examples - The following code shows how to call this method. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/c_createsecuresession/cs/secureservice.cs" id="Snippet6"::: - +> When impersonation is required on Windows XP, use a secure session without a security context token. When security context tokens are used with impersonation an is thrown. For more information, see [Unsupported Scenarios](/dotnet/framework/wcf/feature-details/unsupported-scenarios). For more information about secure sessions, see [Secure Sessions](/dotnet/framework/wcf/feature-details/secure-sessions). + + + +## Examples + The following code shows how to call this method. + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/c_createsecuresession/cs/secureservice.cs" id="Snippet6"::: + ]]> @@ -1344,9 +1344,9 @@ System.ServiceModel.Channels.SecurityBindingElement - - - + + + A that contains specification on how the secure conversation handshake messages are secured. @@ -1356,20 +1356,20 @@ Creates a symmetric security binding element that is configured to establish a secure conversation between the client and service. The security context token issued at the end of the secure conversation handshake is used to secure the messages. The bootstrap security binding element specifies how the secure conversation handshake messages are secured. A object. - , the binding element returned by this method is also a `TransportSecurityBindingElement`, and is set to `true`; and the object returned from has its property set to `false`; and the object returned from has its property set to `false`. - - Otherwise, a is returned, with set to `false`. - + , the binding element returned by this method is also a `TransportSecurityBindingElement`, and is set to `true`; and the object returned from has its property set to `false`; and the object returned from has its property set to `false`. + + Otherwise, a is returned, with set to `false`. + > [!NOTE] -> When impersonation is required on Windows XP, use a secure session without a security context token. When security context tokens are used with impersonation an is thrown. For more information, see [Unsupported Scenarios](/dotnet/framework/wcf/feature-details/unsupported-scenarios). For more information about secure sessions, see [Secure Sessions](/dotnet/framework/wcf/feature-details/secure-sessions). - +> When impersonation is required on Windows XP, use a secure session without a security context token. When security context tokens are used with impersonation an is thrown. For more information, see [Unsupported Scenarios](/dotnet/framework/wcf/feature-details/unsupported-scenarios). For more information about secure sessions, see [Secure Sessions](/dotnet/framework/wcf/feature-details/secure-sessions). + ]]> @@ -1419,11 +1419,11 @@ Creates a symmetric security binding element that is configured to do SOAP-level SSL negotiation between the client and server, noting whether a client certificate is required. A that holds the new binding. - @@ -1459,11 +1459,11 @@ Creates a symmetric security binding element that does SOAP SSL negotiation, noting whether a client certificate and cancellation is required. A that holds the new binding. - @@ -1507,11 +1507,11 @@ Creates a symmetric security binding element that does SOAP SSPI negotiation based on the Negotiate authentication package. A object. - @@ -1543,11 +1543,11 @@ Creates a symmetric security binding element that does SOAP SSPI negotiation based on the Negotiate authentication package. A object. - @@ -1591,15 +1591,15 @@ Creates a security binding element that is configured for client authentication based on SOAP SSPI negotiation using the Negotiate authentication package. The binding element requires the transport to provide server authentication and message protection (for example, HTTPS). A object. - set to `true`. The object returned from has its property set to `false`. - - The object returned from has its property set to `false`. - + set to `true`. The object returned from has its property set to `false`. + + The object returned from has its property set to `false`. + ]]> @@ -1631,15 +1631,15 @@ Creates a security binding element that is configured for client authentication based on SOAP SSPI negotiation using the Negotiate authentication package. The binding element requires the transport to provide server authentication and message protection (for example, HTTPS). A object. - set to `true`. The object returned from has its property set to `false`. - - The object returned from has its property set to `false`. - + set to `true`. The object returned from has its property set to `false`. + + The object returned from has its property set to `false`. + ]]>
@@ -1668,11 +1668,11 @@ Creates a symmetric security binding element that is configured to require user name- and password-based client authentication and certificate-based server authentication. The created binding element requires the client to be configured with a service certificate that is out-of-band before opening a communication channel with a service. A object. -
@@ -1716,13 +1716,13 @@ Creates a symmetric security binding element that is configured to require user name- and password-based client authentication and certificate-based server authentication. The client authenticates the server using the SOAP-level SSL protocol. A object. -
@@ -1754,13 +1754,13 @@ Creates a symmetric security binding element that is configured to require user name- and password-based client authentication and certificate-based server authentication. The client authenticates the server using the SOAP-level SSL protocol. A object. -
@@ -1802,13 +1802,13 @@ Creates a security binding element that is configured for client authentication based on a user name and password sent as part of the SOAP message. The binding element requires the transport to provide server authentication and message protection (for example, HTTPS). A object. - set to `true`. The object returned from has its property set to `false`. - - The object returned from has its property set to `false`. - + set to `true`. The object returned from has its property set to `false`. + + The object returned from has its property set to `false`. + ]]>
@@ -1850,18 +1850,18 @@ Gets or sets the message encryption and key-wrap algorithms. The object that represents the message encryption and key-wrap algorithms. - object that contains numerous properties that specify security algorithms that are to be used for signing, encryption, key derivation, and other cryptographic operations. It also controls the key sizes that are used for doing these cryptographic operations. - - - -## Examples - The following code shows how to set this property. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/c_custombindingsauthmode/cs/source.cs" id="Snippet8"::: - + object that contains numerous properties that specify security algorithms that are to be used for signing, encryption, key derivation, and other cryptographic operations. It also controls the key sizes that are used for doing these cryptographic operations. + + + +## Examples + The following code shows how to set this property. + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/c_custombindingsauthmode/cs/source.cs" id="Snippet8"::: + ]]> The value is null on a . @@ -1950,18 +1950,18 @@ Gets the endpoint that supports token parameters. The object that represents the endpoint that supports token parameters. - contains additional token parameters () for all operations defined by an endpoint. The primary token parameters are found on either the or the (both inherit from the class). In the case of the , the primary token parameters are returned by the property. On the element there are two parameter properties, the and properties. - + contains additional token parameters () for all operations defined by an endpoint. The primary token parameters are found on either the or the (both inherit from the class). In the case of the , the primary token parameters are returned by the property. On the element there are two parameter properties, the and properties. + > [!NOTE] -> The properties are called parameters because they specify only the type of the security token, not the actual values. -> -> Supporting tokens can be scoped at the endpoint level, in which case they are included in all secured messages sent by the client to the service. The service enforces that all secured messages from the client contain the supporting token types configured by this property. -> -> To provide supporting tokens only for an operation (not all operations on an endpoint), use the property. - +> The properties are called parameters because they specify only the type of the security token, not the actual values. +> +> Supporting tokens can be scoped at the endpoint level, in which case they are included in all secured messages sent by the client to the service. The service enforces that all secured messages from the client contain the supporting token types configured by this property. +> +> To provide supporting tokens only for an operation (not all operations on an endpoint), use the property. + ]]> @@ -2014,13 +2014,13 @@ Gets a specified object using the specified . The specified object from the or if the object is not found. - . - - If the `SecurityBindingElement` does not recognize the type of property requested, it delegates the call to the binding element stack below it, passing the binding context parameter. The types of properties that the `SecurityBindingElement` can provide are and . - + . + + If the `SecurityBindingElement` does not recognize the type of property requested, it delegates the call to the binding element stack below it, passing the binding context parameter. The types of properties that the `SecurityBindingElement` can provide are and . + ]]> @@ -2072,11 +2072,11 @@ if time stamps are included in each message; otherwise, . The default is . - property is `true` and if `DetectReplays` is `true`, WCF detects a replay attack. - + property is `true` and if `DetectReplays` is `true`, WCF detects a replay attack. + ]]> @@ -2118,11 +2118,11 @@ Gets or sets the source of entropy used to create keys. The used to create keys. The default value is . - specifies how the key for tokens (such as ) issued by the service is computed: whether it is computed based on the client key material only, on the service key material only, or on a combination of both. - + specifies how the key for tokens (such as ) issued by the service is computed: whether it is computed based on the client key material only, on the service key material only, or on a combination of both. + ]]> @@ -2169,19 +2169,19 @@ Gets the binding properties specific to local security settings used by the client. The that represents the binding properties specific to local security settings used by the client. - object and use it to set security properties for this binding. - - - -## Examples - The following code shows how to access this property to set a property in another object. - + object and use it to set security properties for this binding. + + + +## Examples + The following code shows how to access this property to set a property in another object. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/c_maxclockskew/cs/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/c_maxclockskew/vb/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/c_maxclockskew/vb/source.vb" id="Snippet1"::: + ]]> @@ -2215,23 +2215,23 @@ Gets the binding properties specific to local security settings used by the service. The object that represents the binding properties specific to local security settings used by the service. - object can help mitigate a denial-of-service (DOS) security attack: - -- : controls the maximum number of time-bounded `SecurityContextToken`s that are cached by the server after doing SPNEGO or SSL negotiation. - -- : controls the lifetime of the `SecurityContextToken`s that are issued by the server following SPNEGO or SSL negotiation. The server caches the `SecurityContextToken`s for this period of time. - -- : controls the maximum number of secure conversations that are established at the server but for which no application messages have been processed. This quota prevents clients from establishing secure conversations at the service, thereby causing the service to maintain state for each client, but never using them. - -- : controls the maximum time that the service keeps a secure conversation alive without ever receiving an application message on it. This quota prevents clients from establishing secure conversations at the service, thereby causing the service to maintain state for each client, but never using them. - - In a secure conversation session, note that both and the `ReceiveTimeout` property on the binding affect session timeout. The shorter of the two determines when timeouts occur. - + object can help mitigate a denial-of-service (DOS) security attack: + +- : controls the maximum number of time-bounded `SecurityContextToken`s that are cached by the server after doing SPNEGO or SSL negotiation. + +- : controls the lifetime of the `SecurityContextToken`s that are issued by the server following SPNEGO or SSL negotiation. The server caches the `SecurityContextToken`s for this period of time. + +- : controls the maximum number of secure conversations that are established at the server but for which no application messages have been processed. This quota prevents clients from establishing secure conversations at the service, thereby causing the service to maintain state for each client, but never using them. + +- : controls the maximum time that the service keeps a secure conversation alive without ever receiving an application message on it. This quota prevents clients from establishing secure conversations at the service, thereby causing the service to maintain state for each client, but never using them. + + In a secure conversation session, note that both and the `ReceiveTimeout` property on the binding affect session timeout. The shorter of the two determines when timeouts occur. + ]]> @@ -2278,14 +2278,14 @@ Gets or sets the message security version. The object that represents the message security version. - contains numerous properties that specify version numbers of different security specifications used when securing messages exchanged on the channel. - + contains numerous properties that specify version numbers of different security specifications used when securing messages exchanged on the channel. + > [!NOTE] -> Once a object is created, this property is immutable. Calling `set` on it does not change it. - +> Once a object is created, this property is immutable. Calling `set` on it does not change it. + ]]> @@ -2325,20 +2325,20 @@ Gets the collection of operation supporting token parameters. A of types (key) and (value). - property contains additional token parameters () for specific operations defined. The primary token parameters are found on either the or the (both inherit from the class). In the case of the , the primary token parameters are returned by the property. On the there are two parameter properties, the and properties. - + property contains additional token parameters () for specific operations defined. The primary token parameters are found on either the or the (both inherit from the class). In the case of the , the primary token parameters are returned by the property. On the there are two parameter properties, the and properties. + > [!NOTE] -> The properties are called parameters because they specify only the type of the security token, not the actual values. - - Supporting tokens can be scoped at a different scope than the binding, in this case the operation, in which case they are included in all secured messages sent by the client to services that have the specified Action. - - To provide supporting tokens only for an operation (not all operations on an endpoint), use the property. - +> The properties are called parameters because they specify only the type of the security token, not the actual values. + + Supporting tokens can be scoped at a different scope than the binding, in this case the operation, in which case they are included in all secured messages sent by the client to services that have the specified Action. + + To provide supporting tokens only for an operation (not all operations on an endpoint), use the property. + ]]> @@ -2376,11 +2376,11 @@ Gets the optional supporting token parameters for the service endpoint. The for the service endpoint. - collection. - + collection. + ]]> @@ -2418,11 +2418,11 @@ Gets the collection of optional operation supporting token parameters. A of types (key) and (value). - collection. - + collection. + ]]> @@ -2495,19 +2495,19 @@ Gets or sets the ordering of the elements in the security header for this binding. The that represents the ordering of the elements in the security header for this binding. The default is . - enumeration contains the following members: - -- : Items are added to the security header according to the general principle of "declare before use". - -- : Items are added to the security header in any order that conforms to WSS: SOAP Message security. - -- : Items are added to the security header in any order that conforms to WSS: SOAP message security except that the first element in the security header must be a `wsse:Timestamp` element. - -- : Items are added to the security header in any order that conforms to WSS: SOAP message security except that the last element in the security header must be a `wsse:Timestamp` element. - + enumeration contains the following members: + +- : Items are added to the security header according to the general principle of "declare before use". + +- : Items are added to the security header in any order that conforms to WSS: SOAP Message security. + +- : Items are added to the security header in any order that conforms to WSS: SOAP message security except that the first element in the security header must be a `wsse:Timestamp` element. + +- : Items are added to the security header in any order that conforms to WSS: SOAP message security except that the last element in the security header must be a `wsse:Timestamp` element. + ]]> The value is not a valid value. @@ -2545,11 +2545,11 @@ The object that represents the key for the token requirement property whose value is the BindingContext used to talk to the issuing party. Sets the key for the token requirement property whose value is the BindingContext used to talk to the issuing party if the requirement is for an issued token. - @@ -2585,13 +2585,13 @@ to require derived keys; otherwise, . Sets a value that indicates whether derived keys are required. - @@ -2632,11 +2632,11 @@ Returns a description of this class. A description of the current instance. - includes the , , , , , , and values of the current instance. - + includes the , , , , , , and values of the current instance. + ]]> diff --git a/xml/System.ServiceModel.Channels/TextMessageEncodingBindingElement.xml b/xml/System.ServiceModel.Channels/TextMessageEncodingBindingElement.xml index 24304f1961b..826c0606a0f 100644 --- a/xml/System.ServiceModel.Channels/TextMessageEncodingBindingElement.xml +++ b/xml/System.ServiceModel.Channels/TextMessageEncodingBindingElement.xml @@ -51,19 +51,19 @@ The binding element that specifies the character encoding and message versioning used for text-based SOAP messages. - is the most interoperable, but the least efficient encoder for XML messages. Web service or Web service client can generally understand textual XML. However, transmitting large blocks of binary data as text is not efficient. - - For more information about the binding element that specifies messages are encoded using the .NET Binary Format for XML, see . - - For more information about the binding element that specifies messages are encoded using the MTOM message encoding, see . - - For more information about how to implement a custom message encoder, use the class. - + is the most interoperable, but the least efficient encoder for XML messages. Web service or Web service client can generally understand textual XML. However, transmitting large blocks of binary data as text is not efficient. + + For more information about the binding element that specifies messages are encoded using the .NET Binary Format for XML, see . + + For more information about the binding element that specifies messages are encoded using the MTOM message encoding, see . + + For more information about how to implement a custom message encoder, use the class. + ]]> @@ -107,11 +107,11 @@ Initializes a new instance of the class. - for this constructor is the version of WS-Addressing 1.0 and SOAP 1.2. The default text encoding is the UTF-8 format. - + for this constructor is the version of WS-Addressing 1.0 and SOAP 1.2. The default text encoding is the UTF-8 format. + ]]> @@ -228,7 +228,7 @@ - + The type of channel the channel listener accepts. @@ -266,7 +266,7 @@ - + The type of channel the channel listener accepts. @@ -311,11 +311,11 @@ Creates a new object initialized from the current one. A object with property values equal to those of the current element. - @@ -354,11 +354,11 @@ Creates a factory for text message encoders that employs the message version and character encoding specified by the current encoding binding element. The that this factory creates. - objects that the factory produces can read messages from a stream and write them to a stream for specific types of message encoding. - + objects that the factory produces can read messages from a stream and write them to a stream for specific types of message encoding. + ]]> @@ -408,11 +408,11 @@ Returns a typed object requested, if present, from the appropriate layer in the binding element stack. The typed object requested if it is present or if it is not. - @@ -451,11 +451,11 @@ Gets or sets the number of readers that are allocated to a pool and ready for use to process incoming messages. The number of readers in the pool. The default value is 64 readers. - The value is less than or equal to zero. @@ -495,11 +495,11 @@ Gets or sets the number of writers that are allocated to a pool and ready for use to process outgoing messages. The maximum number of writers to be kept in the pool. The default value is 16 writers. - The value is less than or equal to zero. @@ -544,11 +544,11 @@ Gets or sets the SOAP and WS-Addressing versions that are used to format the text message. The that is used to format messages. The default value is . - for this constructor is the version of WS-Addressing 1.0 and SOAP 1.2. - + for this constructor is the version of WS-Addressing 1.0 and SOAP 1.2. + ]]> The value is . @@ -597,21 +597,21 @@ Gets or sets constraints on the complexity of SOAP messages that can be processed by endpoints configured with this binding. The that specifies the complexity constraints on SOAP messages exchanged. The default values for these constraints are provided in the following Remarks section. - = 32 - -- = 8192 - -- = 16384 - -- = 4096 - -- = 16384 - + = 32 + +- = 8192 + +- = 16384 + +- = 4096 + +- = 16384 + ]]> @@ -746,11 +746,11 @@ A object that provides mappings from exported WSDL elements to the contract description. Generates WSDL contract information from encoding policies contained in the binding element. - is responsible for setting information about the message version in the WSDL. But this is done by the method, not by , which is implemented but empty. - + is responsible for setting information about the message version in the WSDL. But this is done by the method, not by , which is implemented but empty. + ]]> @@ -786,11 +786,11 @@ A object that provides mappings from exported WSDL elements to the endpoint description. Generates WSDL contract information from encoding policies contained in the binding element. - is responsible for setting information about the message version in the WSDL. But this is done by the method. - + is responsible for setting information about the message version in the WSDL. But this is done by the method. + ]]> @@ -840,11 +840,11 @@ Gets or sets the encoding that is used to format the characters in the text message. The that is used to format the characters in the text message. The default text encoding is the UTF-8 format. - The value is . diff --git a/xml/System.ServiceModel.Channels/WindowsStreamSecurityBindingElement.xml b/xml/System.ServiceModel.Channels/WindowsStreamSecurityBindingElement.xml index b529de4f699..07ed89fa117 100644 --- a/xml/System.ServiceModel.Channels/WindowsStreamSecurityBindingElement.xml +++ b/xml/System.ServiceModel.Channels/WindowsStreamSecurityBindingElement.xml @@ -63,25 +63,25 @@ Represents the binding element used to specify Windows stream security settings. - , which can be configured and added to a custom binding. In addition, a third party can write its own custom `StreamSecurityBindingElement`. These binding elements extend the class that is called to build the client and server stream upgrade providers. - - A custom binding contains a collection of binding elements arranged in a specific order: the element representing the top of the binding stack is added first, the next element down in the binding stack is added second, and so on. - -### To add this class to a binding - -1. Create a . - -2. Create any required custom binding elements that are above this binding element in the binding stack, such as the optional and . - -3. Add the created elements in the order described previously to the using the method. - -4. Create an instance of and add it to the collection. - -5. Add any additional custom binding elements to the collection, such as . - + , which can be configured and added to a custom binding. In addition, a third party can write its own custom `StreamSecurityBindingElement`. These binding elements extend the class that is called to build the client and server stream upgrade providers. + + A custom binding contains a collection of binding elements arranged in a specific order: the element representing the top of the binding stack is added first, the next element down in the binding stack is added second, and so on. + +### To add this class to a binding + +1. Create a . + +2. Create any required custom binding elements that are above this binding element in the binding stack, such as the optional and . + +3. Add the created elements in the order described previously to the using the method. + +4. Create an instance of and add it to the collection. + +5. Add any additional custom binding elements to the collection, such as . + ]]> Custom Stream Upgrades @@ -156,11 +156,9 @@ - Instance of this class to clone. - Instance of this class to clone. Initializes a new instance of the class from an existing instance. To be added. @@ -210,11 +208,11 @@ Creates a channel factory that can be used to create a channel. Returns a channel factory of the specified type. This method adds this class instance to the and delegates to the build method . - @@ -261,11 +259,11 @@ Creates a channel listener of the specified type. Returns a channel listener of the specified type. This method adds this class instance to the and delegates to the build method . - @@ -305,13 +303,13 @@ Creates an instance on the client of the based on the channel context provided. An instance of the . - abstract class. - - The parameter enables reacting to other elements in the channel stack. - + abstract class. + + The parameter enables reacting to other elements in the channel stack. + ]]> @@ -346,13 +344,13 @@ Creates an instance on the server of the based on the channel context provided. An instance of the . - abstract class. - - The parameter enables reacting to other elements in the channel stack. - + abstract class. + + The parameter enables reacting to other elements in the channel stack. + ]]> @@ -402,11 +400,11 @@ if a channel factory can be built; otherwise, . - method. - + method. + ]]> @@ -453,11 +451,11 @@ if a channel listener can be built; otherwise, . - method. - + method. + ]]> @@ -552,19 +550,19 @@ Gets a specified object from the . The specified object from the or if the object is not found. - , then an instance of this class is returned with , - - , and all set to `true`, and and set to the current value in this binding. - - If the type of `T` is , then a default instance of this class is returned. - - This method is implemented by binding elements as well as by the run-time objects such as , , and . - + , then an instance of this class is returned with , + + , and all set to `true`, and and set to the current value in this binding. + + If the type of `T` is , then a default instance of this class is returned. + + This method is implemented by binding elements as well as by the run-time objects such as , , and . + ]]> @@ -599,11 +597,11 @@ Gets the that represents the transport token used in the security binding. An that represents the transport token used in the policy generated by this binding. - @@ -684,17 +682,17 @@ The that you can use to insert your custom policy assertion. Exports a custom policy assertion about Windows stream security. - and objects. Use the , , and methods to obtain collections of policy assertions that have already been exported at various scopes. Then use this method to add your own policy assertions to the appropriate collection. - - The property exposes the for the endpoint that is being exported. This enables this method to correctly scope their exported policy assertions. For example, security attributes in code can add behaviors to the that indicate where security policy assertions should be added. - - Once custom policy assertions are attached to the WSDL information, clients can detect and import the custom binding assertions by implementing an interface. - + and objects. Use the , , and methods to obtain collections of policy assertions that have already been exported at various scopes. Then use this method to add your own policy assertions to the appropriate collection. + + The property exposes the for the endpoint that is being exported. This enables this method to correctly scope their exported policy assertions. For example, security attributes in code can add behaviors to the that indicate where security policy assertions should be added. + + Once custom policy assertions are attached to the WSDL information, clients can detect and import the custom binding assertions by implementing an interface. + ]]> diff --git a/xml/System.ServiceModel.Description/ContractDescription.xml b/xml/System.ServiceModel.Description/ContractDescription.xml index a32a928b39e..668c51c99e5 100644 --- a/xml/System.ServiceModel.Description/ContractDescription.xml +++ b/xml/System.ServiceModel.Description/ContractDescription.xml @@ -45,31 +45,31 @@ Describes a Windows Communication Foundation (WCF) contract that specifies what an endpoint communicates to the outside world. - object is used to describe WCF contracts and their operations. Within a , each contract operation has a corresponding that describes aspects of the each operation that is part of the contract, such as whether the operation is one-way or request/reply. Each also describes the messages that make up the operation using a . contains a reference to an interface that defines the contract using the programming model. This interface is marked with and its methods that correspond to endpoint operations are marked with the . - - A *duplex* contract defines the following logical sets of operations: - -- A set that the service exposes for the client to call. - -- A set that the client exposes for the service to call. - - The programming model for defining a duplex contract is to split each set in a separate interface and apply attributes to each interface. In this case, contains a reference to each of the interfaces that groups them into one duplex contract. - - Similar to bindings, each contract has a and that uniquely identify it in the metadata of the service. - - - -## Examples - The following example shows a number of ways to create or retrieve a object. It then displays the various pieces of information that are stored in the object. - + object is used to describe WCF contracts and their operations. Within a , each contract operation has a corresponding that describes aspects of the each operation that is part of the contract, such as whether the operation is one-way or request/reply. Each also describes the messages that make up the operation using a . contains a reference to an interface that defines the contract using the programming model. This interface is marked with and its methods that correspond to endpoint operations are marked with the . + + A *duplex* contract defines the following logical sets of operations: + +- A set that the service exposes for the client to call. + +- A set that the client exposes for the service to call. + + The programming model for defining a duplex contract is to split each set in a separate interface and apply attributes to each interface. In this case, contains a reference to each of the interfaces that groups them into one duplex contract. + + Similar to bindings, each contract has a and that uniquely identify it in the metadata of the service. + + + +## Examples + The following example shows a number of ways to create or retrieve a object. It then displays the various pieces of information that are stored in the object. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_ue_contractdescription/cs/calculatorservice.cs" id="Snippet0"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_ue_contractdescription/vb/calculatorservice.vb" id="Snippet0"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_ue_contractdescription/vb/calculatorservice.vb" id="Snippet0"::: + ]]> @@ -123,12 +123,12 @@ The name of the contract. Initializes a new instance of the class with a specified name. - @@ -172,17 +172,17 @@ The namespace that contains the name of the contract. Initializes a new instance of the class with a namespace-qualified name specified. - @@ -225,12 +225,12 @@ Gets the behaviors associated with the contract description. The of type associated with the contract description. - @@ -278,17 +278,17 @@ Gets or sets the type of callback contract that the contract description specifies. The of callback contract that the contract description specifies. - property is not serializable, so it is only available when the description is bound to runtime. It cannot be imported or exported as part of the metadata. - - - -## Examples + property is not serializable, so it is only available when the description is bound to runtime. It cannot be imported or exported as part of the metadata. + + + +## Examples :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_ue_contractdescription/cs/calculatorservice.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_ue_contractdescription/vb/calculatorservice.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_ue_contractdescription/vb/calculatorservice.vb" id="Snippet4"::: + ]]> @@ -340,12 +340,12 @@ Gets or sets the configuration name for the contract description. The configuration name for the contract. - @@ -427,17 +427,17 @@ Gets or sets the contract type that the contract description specifies. The of contract that the contract description specifies. - property is not serializable, so it is only available when the description is bound to runtime. It cannot be imported or exported as part of the metadata. - - - -## Examples + property is not serializable, so it is only available when the description is bound to runtime. It cannot be imported or exported as part of the metadata. + + + +## Examples :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_ue_contractdescription/cs/calculatorservice.cs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_ue_contractdescription/vb/calculatorservice.vb" id="Snippet6"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_ue_contractdescription/vb/calculatorservice.vb" id="Snippet6"::: + ]]> @@ -451,11 +451,11 @@ Returns the contract description for a specified type of contract. - overloads is that the ones with two arguments allow you to find attributes from the service (for example, ). - + overloads is that the ones with two arguments allow you to find attributes from the service (for example, ). + ]]> @@ -494,17 +494,17 @@ Returns the contract description for a specified type of contract. The for the specified type of contract. - overloads is that the ones with two arguments allow you to find attributes from the service (for example, ). - - - -## Examples + overloads is that the ones with two arguments allow you to find attributes from the service (for example, ). + + + +## Examples :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_ue_contractdescription/cs/calculatorservice.cs" id="Snippet13"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_ue_contractdescription/vb/calculatorservice.vb" id="Snippet13"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_ue_contractdescription/vb/calculatorservice.vb" id="Snippet13"::: + ]]> @@ -530,8 +530,8 @@ System.ServiceModel.Description.ContractDescription - - + + The of contract. @@ -539,17 +539,17 @@ Returns the contract description for a specified type of contract and service implementation. The for the specified type of contract and service implementation. - overloads is that the ones with two arguments allow you to find attributes from the service (for example, ). - - - -## Examples + overloads is that the ones with two arguments allow you to find attributes from the service (for example, ). + + + +## Examples :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_ue_contractdescription/cs/calculatorservice.cs" id="Snippet14"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_ue_contractdescription/vb/calculatorservice.vb" id="Snippet14"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_ue_contractdescription/vb/calculatorservice.vb" id="Snippet14"::: + ]]> @@ -575,8 +575,8 @@ System.ServiceModel.Description.ContractDescription - - + + The of contract. @@ -584,17 +584,17 @@ Returns the contract description for a specified type of contract and a specified type of service. The for the specified type of contract and type of service. - overloads is that the ones with two arguments allow you to find attributes from the service (for example, ). - - - -## Examples + overloads is that the ones with two arguments allow you to find attributes from the service (for example, ). + + + +## Examples :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_ue_contractdescription/cs/calculatorservice.cs" id="Snippet15"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_ue_contractdescription/vb/calculatorservice.vb" id="Snippet15"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_ue_contractdescription/vb/calculatorservice.vb" id="Snippet15"::: + ]]> @@ -624,12 +624,12 @@ Returns a collection of contract descriptions that are inherited by the current contract description. The of type that is inherited by the current contract description. - @@ -665,17 +665,17 @@ if the protection level has been set; otherwise, . - is set, the property is set to `true`. - - - -## Examples + is set, the property is set to `true`. + + + +## Examples :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_ue_contractdescription/cs/calculatorservice.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_ue_contractdescription/vb/calculatorservice.vb" id="Snippet7"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_ue_contractdescription/vb/calculatorservice.vb" id="Snippet7"::: + ]]> @@ -713,12 +713,12 @@ Gets or sets the name of the contract. The name of the contract description. - @@ -762,17 +762,17 @@ Gets or sets the namespace for the contract. The namespace of the contract. - The value set is . @@ -817,12 +817,12 @@ Gets the collection of operation descriptions associated with the contract. The that contains the operation descriptions associated with the contract description. - @@ -857,17 +857,17 @@ Gets or sets the level of security protection associated with the contract. The for the operation. - is set, the property is set to `true`. - - - -## Examples + is set, the property is set to `true`. + + + +## Examples :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_ue_contractdescription/cs/calculatorservice.cs" id="Snippet11"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_ue_contractdescription/vb/calculatorservice.vb" id="Snippet11"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_ue_contractdescription/vb/calculatorservice.vb" id="Snippet11"::: + ]]> @@ -906,17 +906,17 @@ Gets or sets a value that indicates whether a session is required by the contract. The that specifies the support for reliable sessions that a contract requires or supports. - diff --git a/xml/System.ServiceModel.Description/FaultDescriptionCollection.xml b/xml/System.ServiceModel.Description/FaultDescriptionCollection.xml index 6278fe977b3..4f8bd7a0c30 100644 --- a/xml/System.ServiceModel.Description/FaultDescriptionCollection.xml +++ b/xml/System.ServiceModel.Description/FaultDescriptionCollection.xml @@ -42,11 +42,11 @@ Represents a collection of objects that you can use to obtain information about SOAP faults in a contract. - and methods to retrieve a or group of objects. - + and methods to retrieve a or group of objects. + ]]> @@ -73,11 +73,9 @@ - The value of the SOAP fault action. - The value of the SOAP fault action. Returns the object that has the specified action value. The object that has the specified action, or . If more than one object has the same action, the first one in the collection is returned. To be added. @@ -105,11 +103,9 @@ - The value of the SOAP fault action. - The value of the SOAP fault action. Returns all objects that have the specified action value. A collection of objects that have the specified action. If there are no objects with the action, an empty collection is returned. To be added. diff --git a/xml/System.ServiceModel.Dispatcher/DispatchOperation.xml b/xml/System.ServiceModel.Dispatcher/DispatchOperation.xml index 064127256c0..4f6bbe6f4b5 100644 --- a/xml/System.ServiceModel.Dispatcher/DispatchOperation.xml +++ b/xml/System.ServiceModel.Dispatcher/DispatchOperation.xml @@ -39,33 +39,33 @@ Used to modify or extend the execution behavior of a specific service operation in a service endpoint. This class cannot be inherited. - class is the location for run-time modifications and insertion point for custom extensions that are scoped to only one service operation. (To modify service run-time behavior for all messages in a contract, use the class.) - - Install modifications using a custom operation behavior object or a behavior at a larger scope in order to modify operations across a contract. - - Use the property to locate the object that represents a particular service operation. - -- The , , , , , and properties obtain the respective values for the operation. - -- The and properties specify transaction behavior. - -- The and properties control the lifetime of the user-defined service object relative to the . - -- The , , and the properties enable explicit control over the conversion from messages to objects and vice versa. - -- The property specifies the operation impersonation level. - -- The property inserts custom call context extensions for the operation. For more information, see . - -- The property controls whether parameter objects are disposed when the service operation is completed. - -- The property to insert a custom invoker object. - -- The property enables you to insert a custom parameter inspector that you can use to inspect or modify parameters and return values. - + class is the location for run-time modifications and insertion point for custom extensions that are scoped to only one service operation. (To modify service run-time behavior for all messages in a contract, use the class.) + + Install modifications using a custom operation behavior object or a behavior at a larger scope in order to modify operations across a contract. + + Use the property to locate the object that represents a particular service operation. + +- The , , , , , and properties obtain the respective values for the operation. + +- The and properties specify transaction behavior. + +- The and properties control the lifetime of the user-defined service object relative to the . + +- The , , and the properties enable explicit control over the conversion from messages to objects and vice versa. + +- The property specifies the operation impersonation level. + +- The property inserts custom call context extensions for the operation. For more information, see . + +- The property controls whether parameter objects are disposed when the service operation is completed. + +- The property to insert a custom invoker object. + +- The property enables you to insert a custom parameter inspector that you can use to inspect or modify parameters and return values. + ]]> @@ -117,11 +117,11 @@ The message action for which this dispatch operation is being created. Initializes a new instance of the class using the specified dispatch run-time, name, and action values. - @@ -144,10 +144,10 @@ 6.0.0.0 - - - - + + + + The associated object. @@ -156,11 +156,11 @@ The reply action associated with this dispatch operation. Initializes a new instance of the class using the specified dispatch run-time, name, action, and reply action values. - @@ -246,11 +246,11 @@ if the parameters are to be automatically disposed; otherwise . - parameters (input, output or reference parameters) that were created while processing a message. The default value is `true`. Set this property to `false` to prevent the system from disposing resources. In this case, you are responsible for the parameter lifetimes. See the event if you need to dispose parameters when the operation completes. - + parameters (input, output or reference parameters) that were created while processing a message. The default value is `true`. Set this property to `false` to prevent the system from disposing resources. In this case, you are responsible for the parameter lifetimes. See the event if you need to dispose parameters when the operation completes. + ]]> @@ -284,11 +284,11 @@ A collection of objects that defines the methods that enable the initialization and recycling of thread-local storage with the thread that invokes user code. A collection of objects. - property to add custom objects that add state to the call context for the duration of the call and can retrieve it subsequent to the completion of the call but prior to returning the message. - + property to add custom objects that add state to the call context for the duration of the call and can retrieve it subsequent to the completion of the call but prior to returning the message. + ]]> @@ -333,13 +333,13 @@ if the return type is of type and there are no out parameters; otherwise, . - property to control whether the formatter deserializes the return value from an inbound message or whether the inbound message is returned directly as the return value. - -- **Note** If `false`, the return type must be of type and there can be no out parameters or an is thrown at run-time. - + property to control whether the formatter deserializes the return value from an inbound message or whether the inbound message is returned directly as the return value. + +- **Note** If `false`, the return type must be of type and there can be no out parameters or an is thrown at run-time. + ]]> @@ -374,11 +374,11 @@ Gets a collection of objects that represent the specified SOAP faults for this operation. A collection of SOAP faults specified for this operation. - property to get a collection of all contractually specified SOAP faults. - + property to get a collection of all contractually specified SOAP faults. + ]]> @@ -412,13 +412,13 @@ Gets or sets the formatter that deserializes messages into objects and serializes objects into messages. An implementation. - property to insert a custom implementation for an operation or modify the current formatter. In the case of strongly-typed message operations, the use of the formatter can be controlled by the and properties. - - The interface defines the and methods, which are used to convert a set of object parameters to a message and from a message to a set of return values, respectively. - + property to insert a custom implementation for an operation or modify the current formatter. In the case of strongly-typed message operations, the use of the formatter can be controlled by the and properties. + + The interface defines the and methods, which are used to convert a set of object parameters to a message and from a message to a set of return values, respectively. + ]]> @@ -484,11 +484,11 @@ Gets or sets the object that invokes the user-defined method. The object that invokes the user-defined method. - . - + . + ]]> @@ -670,11 +670,11 @@ Gets or sets a collection of objects that can inspect and modify inbound and outbound objects for a particular proxy method. A collection of implementations. - property to insert a custom implementation or to modify the current one. Parameter inspectors are invoked in the order in which they are added to the collection for requests and in the reverse order for replies. - + property to insert a custom implementation or to modify the current one. Parameter inspectors are invoked in the order in which they are added to the collection for requests and in the reverse order for replies. + ]]> @@ -856,14 +856,14 @@ if the property serializes the return values into a reply message; otherwise, . - property to indicate whether the formatter serializes operation parameters into a reply message or whether the first parameter is sent as the outbound message. - + property to indicate whether the formatter serializes operation parameters into a reply message or whether the first parameter is sent as the outbound message. + > [!NOTE] -> If set to `false`, the return value of the operation must be of type or an exception is thrown. - +> If set to `false`, the return value of the operation must be of type or an exception is thrown. + ]]> @@ -930,11 +930,11 @@ if the operation must execute within the scope of a transaction; otherwise, . The default is . - property is `true`, WCF sets the current transaction to the transaction used to receive the message if using a transacted transport; or the transaction flowed over the channel if the message had a transaction; or the dispatcher will create a new one. - + property is `true`, WCF sets the current transaction to the transaction used to receive the message if using a transacted transport; or the transaction flowed over the channel if the message had a transaction; or the dispatcher will create a new one. + ]]> diff --git a/xml/System.ServiceModel.Security.Tokens/BinarySecretSecurityToken.xml b/xml/System.ServiceModel.Security.Tokens/BinarySecretSecurityToken.xml index c049c107c1c..de67e9e98b4 100644 --- a/xml/System.ServiceModel.Security.Tokens/BinarySecretSecurityToken.xml +++ b/xml/System.ServiceModel.Security.Tokens/BinarySecretSecurityToken.xml @@ -92,14 +92,14 @@ A byte-array that represents the key. Initializes a new instance of the class. - @@ -125,7 +125,7 @@ System.ServiceModel.Security - + The key size in bits. @@ -205,8 +205,8 @@ - - + + The token ID. diff --git a/xml/System.ServiceModel.Security.Tokens/SecureConversationSecurityTokenParameters.xml b/xml/System.ServiceModel.Security.Tokens/SecureConversationSecurityTokenParameters.xml index 67b39ff81bc..f83674e3d4d 100644 --- a/xml/System.ServiceModel.Security.Tokens/SecureConversationSecurityTokenParameters.xml +++ b/xml/System.ServiceModel.Security.Tokens/SecureConversationSecurityTokenParameters.xml @@ -42,13 +42,13 @@ Represents the parameters for a secure conversation security token. - @@ -101,17 +101,17 @@ Initializes a new instance of the class. - is set to . - -- is set to . - -- is set to `true`. - + is set to . + +- is set to . + +- is set to `true`. + ]]> @@ -158,11 +158,11 @@ The bootstrap security binding element. Initializes a new instance of the class from the properties of a specified . - @@ -190,8 +190,8 @@ - - + + The bootstrap security binding element. @@ -199,11 +199,11 @@ to require cancellation; otherwise, . Initializes a new instance of the class from the properties of a specified . - @@ -230,18 +230,16 @@ - The other instance of this class. - The other instance of this class. Initializes a new instance of the class from another instance of this class. - @@ -320,13 +318,13 @@ The bootstrap protection requirements. Initializes a new instance of the class from the properties of a specified with specified . - @@ -521,15 +519,15 @@ Clones another instance of this instance of the class. A instance that represents the copy. - and methods follow the Core design pattern. - - is an `abstract` class which is overridden by . - - The method calls the constructor. - + and methods follow the Core design pattern. + + is an `abstract` class which is overridden by . + + The method calls the constructor. + ]]> @@ -567,11 +565,11 @@ Creates a key identifier clause for a token. The key identifier clause for a token. - method, with `referenceStyle` as a generic parameter. - + method, with `referenceStyle` as a generic parameter. + ]]> @@ -607,11 +605,11 @@ Gets a value that indicates whether the security token has an asymmetric key. This property always returns . - @@ -646,23 +644,23 @@ The requirement of the security token. Initializes a security token requirement. - are initialized: - -- = . - -- = `true`. - -- The property in is set to . - -- The property in is set to . - -- The property in is set to a clone of the current instance. - -- = . - + are initialized: + +- = . + +- = `true`. + +- The property in is set to . + +- The property in is set to . + +- The property in is set to a clone of the current instance. + +- = . + ]]> @@ -710,29 +708,29 @@ if cancellation is required; otherwise, . The default is . - property with the actual caller's identity, but instead sets the property to anonymous. Because WCF security must re-create the content of the service security context for every request from the incoming security context token, the server does not keep track of the security session in the memory. Because it is impossible to serialize the instance into the security context token, the property returns an anonymous identity. - - The following configuration exhibits this behavior. - -``` - - - - - - - - - -``` - - For more information about security context tokens, see [How to: Create a Security Context Token for a Secure Session](/dotnet/framework/wcf/feature-details/how-to-create-a-security-context-token-for-a-secure-session). - + property with the actual caller's identity, but instead sets the property to anonymous. Because WCF security must re-create the content of the service security context for every request from the incoming security context token, the server does not keep track of the security session in the memory. Because it is impossible to serialize the instance into the security context token, the property returns an anonymous identity. + + The following configuration exhibits this behavior. + +``` + + + + + + + + + +``` + + For more information about security context tokens, see [How to: Create a Security Context Token for a Secure Session](/dotnet/framework/wcf/feature-details/how-to-create-a-security-context-token-for-a-secure-session). + ]]> @@ -855,11 +853,11 @@ Displays a text representation of this instance of the class. A text representation of this instance of the class. - , and, if non-null, . - + , and, if non-null, . + ]]> diff --git a/xml/System.ServiceModel.Security.Tokens/SecurityTokenParameters.xml b/xml/System.ServiceModel.Security.Tokens/SecurityTokenParameters.xml index 5a71fe86dd9..2027f9596ce 100644 --- a/xml/System.ServiceModel.Security.Tokens/SecurityTokenParameters.xml +++ b/xml/System.ServiceModel.Security.Tokens/SecurityTokenParameters.xml @@ -42,21 +42,21 @@ Specifies an class that when implemented represents security token parameters. - has no relevance in an issued token (SAML token) case. - - - -## Examples - The following code shows a custom override of this class called *CreditCardTokenParameters*. - + has no relevance in an issued token (SAML token) case. + + + +## Examples + The following code shows a custom override of this class called *CreditCardTokenParameters*. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/c_customtoken/cs/source.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/c_customtoken/vb/source.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/c_customtoken/vb/source.vb" id="Snippet2"::: + ]]> @@ -70,21 +70,21 @@ Initializes a new instance of the class. - sets them to their default values. takes them from the instance referenced by the input parameter. - + sets them to their default values. takes them from the instance referenced by the input parameter. + ]]> - - - - - + + + + + Constructor System.ServiceModel @@ -103,17 +103,17 @@ Initializes a new instance of the class. - is set to . - -- is set to . - -- is set to `true`. - + is set to . + +- is set to . + +- is set to `true`. + ]]> @@ -139,17 +139,17 @@ 6.0.0.0 - + The other instance of this class. Initializes a new instance of the class from another instance. - @@ -193,11 +193,11 @@ Clones another instance of this instance of the class. A copy of instance. - and methods follow the Core design pattern. In that pattern, this method performs some validation and then calls , which is an `abstract` method that is overridden in derived classes to perform the core functionality. - + and methods follow the Core design pattern. In that pattern, this method performs some validation and then calls , which is an `abstract` method that is overridden in derived classes to perform the core functionality. + ]]> Unable to clone this instance of the class. @@ -239,11 +239,11 @@ Clones another instance of this instance of the class. A instance that represents the copy. - and methods follow the Core design pattern. is an `abstract` method that is overridden in derived classes. - + and methods follow the Core design pattern. is an `abstract` method that is overridden in derived classes. + ]]> @@ -281,11 +281,11 @@ Creates a key identifier clause for a token. The key identifier clause for a token. - @@ -318,11 +318,11 @@ if the token has an asymmetric key; otherwise, . - @@ -360,21 +360,21 @@ Gets or sets the token inclusion requirements. The token inclusion requirements. - enumeration has the following values: - -- - -- - -- - -- - + enumeration has the following values: + +- + +- + +- + +- + ]]> @@ -409,11 +409,11 @@ The requirement of the security token. When overridden in a derived class, initializes a security token requirement. - @@ -489,13 +489,13 @@ Gets or sets the token reference style. The reference style for the token. - An invalid token reference style was . @@ -544,13 +544,13 @@ if keys need to be derived from the token's key; otherwise, . The default is . - @@ -673,11 +673,11 @@ Displays a text representation of this instance of the class. A text representation of this instance of the class. - , , and . - + , , and . + ]]> diff --git a/xml/System.ServiceModel.Security.Tokens/SupportingTokenParameters.xml b/xml/System.ServiceModel.Security.Tokens/SupportingTokenParameters.xml index 2f4fe619e0b..2567645325f 100644 --- a/xml/System.ServiceModel.Security.Tokens/SupportingTokenParameters.xml +++ b/xml/System.ServiceModel.Security.Tokens/SupportingTokenParameters.xml @@ -42,11 +42,11 @@ Represents the parameters for supporting security tokens required by the security binding element. - @@ -83,17 +83,17 @@ Initializes a new instance of the class. - is set to . - -- is set to . - -- is set to `true`. - + is set to . + +- is set to . + +- is set to `true`. + ]]> @@ -208,11 +208,11 @@ Gets a collection of security token parameters for endorsing supporting tokens required by the security binding element. A collection of . - @@ -241,17 +241,17 @@ System.Void - + A that determines whether parameters require derived keys. Sets a value that indicates whether all endorsing or signed endorsing token parameters require derived keys. - in or in has its property set to `requireDerivedKeys`. - + in or in has its property set to `requireDerivedKeys`. + ]]> @@ -294,11 +294,11 @@ Gets a collection of security token parameters for signed supporting tokens required by the security binding element. A collection of . - @@ -345,11 +345,11 @@ Gets a collection of security token parameters for signed and encrypted supporting tokens required by the security binding element. A collection of . - @@ -387,11 +387,11 @@ Gets a collection of security token parameters for signed and endorsing supporting tokens required by the security binding element. A collection of . - @@ -424,11 +424,11 @@ Displays a text representation of this instance of the class. A text representation of this instance of this class. - , , , and . - + , , , and . + ]]> diff --git a/xml/System.ServiceModel.Security.Tokens/UserNameSecurityTokenParameters.xml b/xml/System.ServiceModel.Security.Tokens/UserNameSecurityTokenParameters.xml index 792b9b8580e..306a57a999c 100644 --- a/xml/System.ServiceModel.Security.Tokens/UserNameSecurityTokenParameters.xml +++ b/xml/System.ServiceModel.Security.Tokens/UserNameSecurityTokenParameters.xml @@ -42,11 +42,11 @@ Represents the parameters for a user name security token. - @@ -60,11 +60,11 @@ Initializes a new instance of the class. - sets them to their default values. takes them from the instance referenced by the input parameter. - + sets them to their default values. takes them from the instance referenced by the input parameter. + ]]> @@ -101,17 +101,17 @@ Initializes a new instance of the class. - is set to . - -- is set to . - - is set to `true`. - + is set to . + +- is set to . + + is set to `true`. + ]]> @@ -138,18 +138,16 @@ - The other instance of this class. - The other instance of this class. Initializes a new instance of the class. - @@ -192,15 +190,15 @@ Clones another instance of this instance of the class. An . - and methods follow the Core design pattern. - - is an `abstract` class that is overridden by . - - The method calls the constructor. - + and methods follow the Core design pattern. + + is an `abstract` class that is overridden by . + + The method calls the constructor. + ]]> @@ -238,11 +236,11 @@ Creates a key identifier clause for a token. The security key identifier clause. - method, with `referenceStyle` as a generic parameter. - + method, with `referenceStyle` as a generic parameter. + ]]> @@ -279,11 +277,11 @@ if the token has an asymmetric key; otherwise, . Always returns . - @@ -318,15 +316,15 @@ The . Initializes a security token requirement. - are initialized: - -- = . - -- = `true`. - + are initialized: + +- = . + +- = `true`. + ]]> diff --git a/xml/System.ServiceModel.Security/MessageSecurityException.xml b/xml/System.ServiceModel.Security/MessageSecurityException.xml index 7fd6eb228a7..a4b6da50bdf 100644 --- a/xml/System.ServiceModel.Security/MessageSecurityException.xml +++ b/xml/System.ServiceModel.Security/MessageSecurityException.xml @@ -46,11 +46,11 @@ Represents an exception that occurred when there is something wrong with the security applied on a message. - @@ -242,8 +242,8 @@ System.Void - - + + @@ -254,7 +254,7 @@ 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.ServiceModel.Security/SecureConversationVersion.xml b/xml/System.ServiceModel.Security/SecureConversationVersion.xml index e50b72fb3aa..3f4caf18661 100644 --- a/xml/System.ServiceModel.Security/SecureConversationVersion.xml +++ b/xml/System.ServiceModel.Security/SecureConversationVersion.xml @@ -44,27 +44,6 @@ To be added. - - - - - - - Constructor - - System.ServiceModel - 2.0.5.0 - 4.0.0.0 - - - System.ServiceModel.Security - - - - To be added. - To be added. - - diff --git a/xml/System.ServiceModel.Security/SecurityPolicyVersion.xml b/xml/System.ServiceModel.Security/SecurityPolicyVersion.xml index 96c1d1ef353..09b6c536ba6 100644 --- a/xml/System.ServiceModel.Security/SecurityPolicyVersion.xml +++ b/xml/System.ServiceModel.Security/SecurityPolicyVersion.xml @@ -44,27 +44,6 @@ To be added. - - - - - - - Constructor - - System.ServiceModel - 2.0.5.0 - 4.0.0.0 - - - System.ServiceModel.Security - - - - To be added. - To be added. - - diff --git a/xml/System.ServiceModel.Security/SecurityVersion.xml b/xml/System.ServiceModel.Security/SecurityVersion.xml index 8a37642288d..3b789092810 100644 --- a/xml/System.ServiceModel.Security/SecurityVersion.xml +++ b/xml/System.ServiceModel.Security/SecurityVersion.xml @@ -44,27 +44,6 @@ To be added. - - - - - - - Constructor - - System.ServiceModel - 2.0.5.0 - 4.0.0.0 - - - System.ServiceModel.Security - - - - To be added. - To be added. - - diff --git a/xml/System.ServiceModel.Security/TrustVersion.xml b/xml/System.ServiceModel.Security/TrustVersion.xml index d6e5272ed52..5b08fc19686 100644 --- a/xml/System.ServiceModel.Security/TrustVersion.xml +++ b/xml/System.ServiceModel.Security/TrustVersion.xml @@ -44,27 +44,6 @@ To be added. - - - - - - - Constructor - - System.ServiceModel - 2.0.5.0 - 4.0.0.0 - - - System.ServiceModel.Security - - - - To be added. - To be added. - - diff --git a/xml/System.ServiceModel.Web/WebOperationContext.xml b/xml/System.ServiceModel.Web/WebOperationContext.xml index 468a141854e..12955e8ecbf 100644 --- a/xml/System.ServiceModel.Web/WebOperationContext.xml +++ b/xml/System.ServiceModel.Web/WebOperationContext.xml @@ -22,14 +22,14 @@ A helper class that provides easy access to contextual properties of Web requests and responses. - instance associated with the Web operation context of the current call. The code also shows how to set the HTTP status for the outgoing response. - + instance associated with the Web operation context of the current call. The code also shows how to set the HTTP status for the outgoing response. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/advancedwebprogramming/cs/service.cs" id="Snippet0"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/advancedwebprogramming/vb/service.vb" id="Snippet0"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/advancedwebprogramming/vb/service.vb" id="Snippet0"::: + ]]> @@ -109,7 +109,7 @@ System.ServiceModel.Channels.Message - + The content to write to the message. @@ -134,7 +134,7 @@ System.ServiceModel.Channels.Message - + The content to write to the message. @@ -159,7 +159,7 @@ System.ServiceModel.Channels.Message - + The content to write to the message. @@ -196,7 +196,7 @@ - + The type of object to write to the message. @@ -225,8 +225,8 @@ - - + + The type of object to write to the message. @@ -643,14 +643,14 @@ Gets the current Web operation context. A instance. - instance. - + instance. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/advancedwebprogramming/cs/snippets.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/advancedwebprogramming/vb/snippets.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/advancedwebprogramming/vb/snippets.vb" id="Snippet2"::: + ]]> @@ -728,14 +728,14 @@ Gets the Web request context for the request being received. An instance. - property to access the headers in the incoming HTTP request. - + property to access the headers in the incoming HTTP request. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/advancedwebprogramming/cs/snippets.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/advancedwebprogramming/vb/snippets.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/advancedwebprogramming/vb/snippets.vb" id="Snippet2"::: + ]]> @@ -760,14 +760,14 @@ Gets the Web response context for the request being received. An instance. - property. - + property. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/advancedwebprogramming/cs/snippets.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/advancedwebprogramming/vb/snippets.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/advancedwebprogramming/vb/snippets.vb" id="Snippet3"::: + ]]> @@ -792,14 +792,14 @@ Gets the Web request context for the request being sent. An instance. - @@ -824,14 +824,14 @@ Gets the Web response context for the response being sent. An instance. - diff --git a/xml/System.ServiceModel/BasicHttpsSecurity.xml b/xml/System.ServiceModel/BasicHttpsSecurity.xml index f4bd7764b59..bc6c5d4fc15 100644 --- a/xml/System.ServiceModel/BasicHttpsSecurity.xml +++ b/xml/System.ServiceModel/BasicHttpsSecurity.xml @@ -39,11 +39,11 @@ - - - - - + + + + + Constructor System.ServiceModel diff --git a/xml/System.ServiceModel/ChannelFactory`1.xml b/xml/System.ServiceModel/ChannelFactory`1.xml index ccc099de321..5146c24a912 100644 --- a/xml/System.ServiceModel/ChannelFactory`1.xml +++ b/xml/System.ServiceModel/ChannelFactory`1.xml @@ -54,27 +54,27 @@ The type of channel produced by the channel factory. This type must be either or . A factory that creates channels of different types that are used by clients to send messages to variously configured service endpoints. - prior to the creation of any channel. See the example section for a code sample. - - Frequently client or calling applications (for example, middle-tier applications are client applications, too) using this type also have complex state management needs as well as performance needs. For more information about these scenarios, please see [Middle-Tier Client Applications](/dotnet/framework/wcf/feature-details/middle-tier-client-applications). - - - -## Examples - The following sample shows how to create a channel factory and use it to create and manage channels. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uechannels/cs/clientsnippets.cs" id="Snippet21"::: - - The following code example shows how to insert programmatically a client behavior prior to the creation of the channel object by the factory. - + prior to the creation of any channel. See the example section for a code sample. + + Frequently client or calling applications (for example, middle-tier applications are client applications, too) using this type also have complex state management needs as well as performance needs. For more information about these scenarios, please see [Middle-Tier Client Applications](/dotnet/framework/wcf/feature-details/middle-tier-client-applications). + + + +## Examples + The following sample shows how to create a channel factory and use it to create and manage channels. + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uechannels/cs/clientsnippets.cs" id="Snippet21"::: + + The following code example shows how to insert programmatically a client behavior prior to the creation of the channel object by the factory. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/channelfactorybehaviors/cs/client.cs" id="Snippet10"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/channelfactorybehaviors/vb/client.vb" id="Snippet10"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/channelfactorybehaviors/vb/client.vb" id="Snippet10"::: + ]]> This type is thread safe. @@ -110,13 +110,13 @@ Initializes a new instance of the class. - class with the `IRequestChannel` interface. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uechannels/cs/clientsnippets.cs" id="Snippet24"::: - + class with the `IRequestChannel` interface. + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uechannels/cs/clientsnippets.cs" id="Snippet24"::: + ]]> @@ -147,17 +147,17 @@ - + The specified for the channels produced by the factory. Initializes a new instance of the class. - @@ -192,16 +192,16 @@ The for the channels produced by the factory. Initializes a new instance of the class that produces channels with a specified endpoint. - The is . @@ -249,16 +249,16 @@ The configuration name used for the endpoint. Initializes a new instance of the class with a specified endpoint configuration name. - @@ -298,11 +298,11 @@ The of channel produced by the factory. Initializes a new instance of the class. - The is . @@ -344,16 +344,16 @@ The that provides the location of the service. Initializes a new instance of the class with a specified binding and endpoint address. - The is . @@ -377,24 +377,24 @@ 6.0.0.0 - - + + The used to configure the endpoint. The address that provides the location of the service. Initializes a new instance of the class with a specified binding and remote address. - @@ -441,11 +441,11 @@ The that provides the location of the service. Initializes a new instance of the class associated with a specified name for the endpoint configuration and remote address. - @@ -461,11 +461,11 @@ Creates a channel of a specified type to a specified endpoint address. - @@ -504,16 +504,16 @@ Creates a channel of a specified type to a specified endpoint address. The of type created by the factory. - @@ -558,11 +558,11 @@ Creates a channel that is used to send messages to a service at a specific endpoint address. The of type created by the factory. - @@ -590,18 +590,18 @@ TChannel - + The name of the endpoint configuration used for the service. Creates a channel that is used to send messages to a service whose endpoint is configured in a specified way. The of type created by the factory. - The has duplex operations it does not support. @@ -649,11 +649,11 @@ Creates a channel that is used to send messages to a service at a specific endpoint address through a specified transport address. The of type created by the factory. - @@ -682,22 +682,20 @@ TChannel - + - The used to configure the endpoint. The that provides the location of the service. - The that provides the location of the service. Creates a channel of a specified type that is used to send messages to a service endpoint that is configured with a specified binding. The of type created by the factory. - The has duplex operations it does not support. @@ -724,26 +722,24 @@ TChannel - + - - + The used to configure the endpoint. The that provides the location of the service. - The that provides the location of the service. The that contains the transport address to which the channel sends messages. Creates a channel of a specified type that is used to send messages to a service endpoint at a specified transport address that is configured with a specified binding. The of type created by the factory. - The has duplex operations it does not support. diff --git a/xml/System.ServiceModel/ClientBase`1.xml b/xml/System.ServiceModel/ClientBase`1.xml index 5900f8371ce..d96bcc6f432 100644 --- a/xml/System.ServiceModel/ClientBase`1.xml +++ b/xml/System.ServiceModel/ClientBase`1.xml @@ -68,33 +68,33 @@ The channel to be used to connect to the service. Provides the base implementation used to create Windows Communication Foundation (WCF) client objects that can call services. - class to create a custom WCF client object that can be used to connect to a service. Typically, the WCF client base class is extended by a tool such as the [ServiceModel Metadata Utility Tool (Svcutil.exe)](/dotnet/framework/wcf/servicemodel-metadata-utility-tool-svcutil-exe) on your behalf. For an example, see the Example section. - - The class can be used quickly and easily by developers who prefer objects to the use of the interfaces and the class. In all cases this class wraps or exposes the methods and functionality of the class and the interface. - - As when using the class, you can create the class and modify the endpoint, channel factory, or security information prior to making any calls or calling . For more information, see [WCF Client Overview](/dotnet/framework/wcf/wcf-client-overview) and [Accessing Services Using a WCF Client](/dotnet/framework/wcf/accessing-services-using-a-wcf-client). - - Special note for Managed C++ users deriving from this class: - -- Put your clean-up code in (On)(Begin)Close (and/or OnAbort), not in a destructor. - -- Avoid destructors: they cause the compiler to auto-generate . - -- Avoid non-reference members: they can cause the compiler to auto-generate . - -- Avoid finalizers; but if you include one, you should suppress the build warning and call and the finalizer itself from (On)(Begin)Close (and/or OnAbort) to emulate what would have been the auto-generated behavior. - - - -## Examples - The following code example shows how the [ServiceModel Metadata Utility Tool (Svcutil.exe)](/dotnet/framework/wcf/servicemodel-metadata-utility-tool-svcutil-exe) extends the class to create a WCF client class. - + class to create a custom WCF client object that can be used to connect to a service. Typically, the WCF client base class is extended by a tool such as the [ServiceModel Metadata Utility Tool (Svcutil.exe)](/dotnet/framework/wcf/servicemodel-metadata-utility-tool-svcutil-exe) on your behalf. For an example, see the Example section. + + The class can be used quickly and easily by developers who prefer objects to the use of the interfaces and the class. In all cases this class wraps or exposes the methods and functionality of the class and the interface. + + As when using the class, you can create the class and modify the endpoint, channel factory, or security information prior to making any calls or calling . For more information, see [WCF Client Overview](/dotnet/framework/wcf/wcf-client-overview) and [Accessing Services Using a WCF Client](/dotnet/framework/wcf/accessing-services-using-a-wcf-client). + + Special note for Managed C++ users deriving from this class: + +- Put your clean-up code in (On)(Begin)Close (and/or OnAbort), not in a destructor. + +- Avoid destructors: they cause the compiler to auto-generate . + +- Avoid non-reference members: they can cause the compiler to auto-generate . + +- Avoid finalizers; but if you include one, you should suppress the build warning and call and the finalizer itself from (On)(Begin)Close (and/or OnAbort) to emulate what would have been the auto-generated behavior. + + + +## Examples + The following code example shows how the [ServiceModel Metadata Utility Tool (Svcutil.exe)](/dotnet/framework/wcf/servicemodel-metadata-utility-tool-svcutil-exe) extends the class to create a WCF client class. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/clientbase/cs/clientbase.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/clientbase/vb/clientbase.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/clientbase/vb/clientbase.vb" id="Snippet1"::: + ]]> @@ -108,11 +108,11 @@ Initializes a new instance of the class. - where the type parameter is the type of the target service contract. - + where the type parameter is the type of the target service contract. + ]]> @@ -146,19 +146,19 @@ Initializes a new instance of the class using the default target endpoint from the application configuration file. - class. - + class. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/servicecontractattribute/cs/client.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/servicecontractattribute/vb/client.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/servicecontractattribute/vb/client.vb" id="Snippet3"::: + ]]> Either there is no default endpoint information in the configuration file, more than one endpoint in the file, or no configuration file. @@ -233,11 +233,11 @@ The name of the endpoint in the application configuration file. Initializes a new instance of the class using the configuration information specified in the application configuration file by . - The specified endpoint information is . @@ -301,26 +301,24 @@ - The callback object that the client application uses to listen for messages from the connected service. - The callback object that the client application uses to listen for messages from the connected service. Initializes a new instance of the class using the as the callback object in a duplex conversation. - The callback instance is . @@ -368,11 +366,11 @@ The address of the service. Initializes a new instance of the class using the specified target address and endpoint information. - @@ -420,11 +418,11 @@ The address of the service. Initializes a new instance of the class. - @@ -450,12 +448,10 @@ - - + The callback object that the client application uses to listen for messages from the connected service. - The callback object that the client application uses to listen for messages from the connected service. The endpoint for a service that allows clients to find and communicate with the service. Initializes a new instance of the class using the specified and objects. To be added. @@ -479,20 +475,18 @@ - - + The callback object that the client uses to listen for messages from the connected service. - The callback object that the client uses to listen for messages from the connected service. The name of the endpoint in the application configuration file. Initializes a new instance of the class using the specified callback service and endpoint configuration information. - The callback instance or is . @@ -518,13 +512,11 @@ - - - + + The callback service. - The callback service. The binding with which to call the service. The address of the service endpoint. Initializes a new instance of the class. @@ -550,22 +542,20 @@ - - - + + The callback object that the client uses to listen for messages from the connected service. - The callback object that the client uses to listen for messages from the connected service. The name of the endpoint in the application configuration file. The address of the service. Initializes a new instance of the class. - The callback instance, , or is . @@ -591,22 +581,20 @@ - - - + + The callback object that the client uses to listen for messages from the connected service. - The callback object that the client uses to listen for messages from the connected service. The name of the endpoint in the application configuration file. The address of the service. Initializes a new instance of the class. - The callback instance, , or is . @@ -650,11 +638,11 @@ Causes the object to transition immediately from its current state into the closed state. - . - + . + ]]> @@ -754,11 +742,11 @@ Gets the underlying object. A object. - @@ -796,19 +784,19 @@ Gets the client credentials used to call an operation. The proof of identity presented by the client. - property to configure the credentials that the object uses to connect to the service. - - - -## Examples - The following code shows how to use the property to set the username and password prior to calling the service. - + property to configure the credentials that the object uses to connect to the service. + + + +## Examples + The following code shows how to use the property to set the username and password prior to calling the service. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/c_programmingsecurity/cs/source.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/c_programmingsecurity/vb/source.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/c_programmingsecurity/vb/source.vb" id="Snippet4"::: + ]]> @@ -850,11 +838,11 @@ Causes the object to transition from its current state into the closed state. - . - + . + ]]> @@ -920,11 +908,11 @@ Returns a new channel to the service. A channel of the type of the service contract. - can be expected here. - + can be expected here. + ]]> @@ -952,11 +940,11 @@ Instructs the inner channel to display a user interface if one is required to initialize the channel prior to using it. - method if the inner channel requires user interaction prior to constructing the channel. For example, if a user must enter a username and password to secure the channel, that custom can be invoked by calling this method. - + method if the inner channel requires user interaction prior to constructing the channel. For example, if a user must enter a username and password to secure the channel, that custom can be invoked by calling this method. + ]]> @@ -995,11 +983,11 @@ Gets the target endpoint for the service to which the WCF client can connect. The target endpoint. - property to obtain the object to inspect or modify prior to using the object. - + property to obtain the object to inspect or modify prior to using the object. + ]]> @@ -1078,11 +1066,11 @@ Gets the underlying implementation. The client channel for the WCF client object. - property to obtain the that is used to connect to the service. - + property to obtain the that is used to connect to the service. + ]]> @@ -1131,11 +1119,11 @@ The object to associate with the asynchronous call. Provides support for implementing the event-based asynchronous pattern. For more information about this pattern, see Event-based Asynchronous Pattern Overview. - , and when each operation is completed, your event handler can determine which instance of the operation raised the completion event. - + , and when each operation is completed, your event handler can determine which instance of the operation raised the completion event. + ]]> @@ -1173,11 +1161,11 @@ Causes the object to transition from the created state into the opened state. - . - + . + ]]> @@ -1218,11 +1206,11 @@ Gets the current state of the object. The value of the of the object. - . - + . + ]]> @@ -1296,11 +1284,11 @@ Explicit implementation of the method. - . - + . + ]]> @@ -1357,11 +1345,11 @@ Begins an asynchronous operation to close the . The that references the asynchronous close operation. - . - + . + ]]> @@ -1410,11 +1398,11 @@ Begins an asynchronous operation to close the with a specified timeout. The that references the asynchronous begin close operation. - . - + . + ]]> @@ -1471,11 +1459,11 @@ Begins an asynchronous operation to open the object. The that references the asynchronous open operation. - . - + . + ]]> @@ -1524,11 +1512,11 @@ Begins an asynchronous operation to open the object within a specified interval of time. The that references the asynchronous open operation. - . - + . + ]]> @@ -1615,11 +1603,11 @@ This member is an explicit interface member implementation. It can be used only The time within which the call must complete. Causes the object to transition from its current state into the closed state. - . - + . + ]]> @@ -1658,11 +1646,11 @@ This member is an explicit interface member implementation. It can be used only The event handler that is invoked when the object has transitioned from its current state to the closed state. - . - + . + ]]> @@ -1701,11 +1689,11 @@ For more information, see The event handler that is invoked when the object transitions from its current state to the closed state. - . - + . + ]]> @@ -1749,11 +1737,11 @@ For more information, see The used to complete the asynchronous close operation. Completes an asynchronous operation to close the object. - . - + . + ]]> @@ -1797,11 +1785,11 @@ For more information, see The used to complete the asynchronous end open operation. Completes an asynchronous operation to open the object. - . - + . + ]]> @@ -1840,11 +1828,11 @@ For more information, see The event handler that is invoked when a fault occurs while performing an operation on the object. - . - + . + ]]> @@ -1931,11 +1919,11 @@ This member is an explicit interface member implementation. It can be used only The time period within which the call must complete. Causes the object to transition from the created state into the opened state within a specified interval of time. - . - + . + ]]> @@ -1974,11 +1962,11 @@ This member is an explicit interface member implementation. It can be used only The event handler that is invoked when the object transitions from the created state to the opened state. - . - + . + ]]> @@ -2017,11 +2005,11 @@ For more information, see The event handler that is invoked when the object transitions from the created state to the opened state. - . - + . + ]]> diff --git a/xml/System.ServiceModel/DuplexChannelFactory`1.xml b/xml/System.ServiceModel/DuplexChannelFactory`1.xml index b930e5436ef..2583c11de77 100644 --- a/xml/System.ServiceModel/DuplexChannelFactory`1.xml +++ b/xml/System.ServiceModel/DuplexChannelFactory`1.xml @@ -49,20 +49,20 @@ The type of channel produced by the channel factory. Provides the means to create and manage duplex channels of different types that are used by clients to send and receive messages to and from service endpoints. - methods are used to create these duplex channels. The duplex message pattern is one of three message patterns available to Windows Communication Foundation (WCF) services. The other two message patterns are one-way and request-reply. - - For a general discussion of duplex services that allow clients to connect back to the service, see [Duplex Services](/dotnet/framework/wcf/feature-details/duplex-services). For an outline and discussion of the steps involved in writing a Windows Communication Foundation (WCF) client application using a channel factory, see [How to: Use the ChannelFactory](/dotnet/framework/wcf/feature-details/how-to-use-the-channelfactory). For a procedure describing how to create a Windows Communication Foundation (WCF) client in a client class that implements the callback interface to access a service that uses a duplex messaging pattern, see [How to: Access Services with a Duplex Contract](/dotnet/framework/wcf/feature-details/how-to-access-services-with-a-duplex-contract). - - - -## Examples - The following sample shows how to create a channel factory and use it to create and manage channels. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_customauthentication/cs/instance.cs" id="Snippet1"::: - + methods are used to create these duplex channels. The duplex message pattern is one of three message patterns available to Windows Communication Foundation (WCF) services. The other two message patterns are one-way and request-reply. + + For a general discussion of duplex services that allow clients to connect back to the service, see [Duplex Services](/dotnet/framework/wcf/feature-details/duplex-services). For an outline and discussion of the steps involved in writing a Windows Communication Foundation (WCF) client application using a channel factory, see [How to: Use the ChannelFactory](/dotnet/framework/wcf/feature-details/how-to-use-the-channelfactory). For a procedure describing how to create a Windows Communication Foundation (WCF) client in a client class that implements the callback interface to access a service that uses a duplex messaging pattern, see [How to: Access Services with a Duplex Contract](/dotnet/framework/wcf/feature-details/how-to-access-services-with-a-duplex-contract). + + + +## Examples + The following sample shows how to create a channel factory and use it to create and manage channels. + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_customauthentication/cs/instance.cs" id="Snippet1"::: + ]]> @@ -104,7 +104,7 @@ - + The that the client uses to listen for messages from the connected service. @@ -143,7 +143,7 @@ - + The that provides the callback instance that the client uses to listen for messages from the connected service. @@ -175,18 +175,16 @@ - The that the client uses to listen for messages from the connected service. - The that the client uses to listen for messages from the connected service. Initializes a new instance of the class with an object that implements the callback contract. - @@ -237,11 +235,11 @@ The used to connect to the service by channels produced by the factory. Initializes a new instance of the class with a context that implements the callback contract and a specified binding. - @@ -275,19 +273,19 @@ - - + + The that the client uses to listen for messages from the connected service. The to which channels produced by the factory connect. Initializes a new instance of the class with an object that implements the callback contract and a specified endpoint. - @@ -341,11 +339,11 @@ The name used for the endpoint configuration. Initializes a new instance of the class with an object that implements the callback contract and a specified configuration. - @@ -381,8 +379,8 @@ - - + + The that provides the callback instance that the client uses to listen for messages from the connected service. @@ -420,8 +418,8 @@ - - + + The that provides the callback instance that the client uses to listen for messages from the connected service. @@ -460,20 +458,18 @@ - - + The that the client uses to listen for messages from the connected service. - The that the client uses to listen for messages from the connected service. The used to connect to the service by channels produced by the factory. Initializes a new instance of the class with an object that implements the callback contract and a specified binding. - @@ -502,20 +498,18 @@ - - + The that the client uses to listen for messages from the connected service. - The that the client uses to listen for messages from the connected service. The to which channels produced by the factory connect. Initializes a new instance of the class with an object that implements the callback contract and a specified endpoint. - @@ -550,20 +544,18 @@ - - + The that the client uses to listen for messages from the connected service. - The that the client uses to listen for messages from the connected service. The configuration name used for the endpoint. Initializes a new instance of the class with an object that implements the callback contract and a specified configuration. - @@ -616,11 +608,11 @@ The that provides the location of the service. Initializes a new instance of the class with an object that implements the callback contract and a specified binding and endpoint address. - @@ -720,11 +712,11 @@ The that provides the location of the service. Initializes a new instance of the class with an object that implements the callback contract and a specified configuration and endpoint address. - @@ -760,9 +752,9 @@ - - - + + + The that provides the callback instance that the client uses to listen for messages from the connected service. @@ -797,9 +789,9 @@ 8.0.0.0 - - - + + + The that provides the callback instance that the client uses to listen for messages from the connected service. @@ -845,8 +837,8 @@ - - + + @@ -886,9 +878,9 @@ - - - + + + The that provides the callback instance that the client uses to listen for messages from the connected service. @@ -922,22 +914,20 @@ - - - + + The that the client uses to listen for messages from the connected service. - The that the client uses to listen for messages from the connected service. The used to connect to the service by channels produced by the factory. The that provides the location of the service. Initializes a new instance of the class with an object that implements the callback contract and a specified binding and endpoint address. - @@ -966,13 +956,11 @@ - - - + + The that the client uses to listen for messages from the connected service. - The that the client uses to listen for messages from the connected service. The used to connect to the service by channels produced by the factory. The remote address that provides the location of the service. Initializes a new instance of the class with specified callback object, binding, and remote address. @@ -1003,22 +991,20 @@ - - - + + The that the client uses to listen for messages from the connected service. - The that the client uses to listen for messages from the connected service. The name used for the endpoint configuration. The that provides the location of the service. Initializes a new instance of the class with an object that implements the callback contract, and a specified configuration and endpoint address. - @@ -1103,8 +1089,8 @@ TChannel - - + + The that the client uses to listen for messages from the connected service. @@ -1236,8 +1222,8 @@ TChannel - - + + The that the client uses to listen for messages from the connected service. @@ -1275,9 +1261,9 @@ TChannel - - - + + + The that the client uses to listen for messages from the connected service. @@ -1316,9 +1302,9 @@ TChannel - - - + + + The that the client uses to listen for messages from the connected service. @@ -1407,10 +1393,10 @@ TChannel - - - - + + + + The that the client uses to listen for messages from the connected service. @@ -1450,10 +1436,10 @@ TChannel - - - - + + + + The that the client uses to listen for messages from the connected service. diff --git a/xml/System.ServiceModel/DuplexClientBase`1.xml b/xml/System.ServiceModel/DuplexClientBase`1.xml index e139810cb87..b62f9c95710 100644 --- a/xml/System.ServiceModel/DuplexClientBase`1.xml +++ b/xml/System.ServiceModel/DuplexClientBase`1.xml @@ -53,29 +53,29 @@ The type of the channel to be created. Used to create a channel to a duplex service and associate that channel with a callback object. - class to create a channel to a service that specifies a callback object. The object wraps a object, which provides the connectivity for the WCF object. You can use either type to connect to a duplex service. For more information about duplex services, see [Duplex Services](/dotnet/framework/wcf/feature-details/duplex-services). - - Special note for Managed C++ users deriving from this class: - -- Put your cleanup code in (On)(Begin)Close (and/or OnAbort), not in a destructor. - -- Avoid destructors: they cause the compiler to auto-generate - -- Avoid non-reference members: they can cause the compiler to auto-generate - -- Avoid finalizers; but if you include one, you should suppress the build warning and call and the finalizer itself from (On)(Begin)Close (and/or OnAbort) in order to emulate what would have been the auto-generated behavior. - - - -## Examples - The following example shows the use in the client of a duplex WCF client type, the `SampleDuplexHelloClient`, to pass a new object with the callback object to listen for callbacks. - + class to create a channel to a service that specifies a callback object. The object wraps a object, which provides the connectivity for the WCF object. You can use either type to connect to a duplex service. For more information about duplex services, see [Duplex Services](/dotnet/framework/wcf/feature-details/duplex-services). + + Special note for Managed C++ users deriving from this class: + +- Put your cleanup code in (On)(Begin)Close (and/or OnAbort), not in a destructor. + +- Avoid destructors: they cause the compiler to auto-generate + +- Avoid non-reference members: they can cause the compiler to auto-generate + +- Avoid finalizers; but if you include one, you should suppress the build warning and call and the finalizer itself from (On)(Begin)Close (and/or OnAbort) in order to emulate what would have been the auto-generated behavior. + + + +## Examples + The following example shows the use in the client of a duplex WCF client type, the `SampleDuplexHelloClient`, to pass a new object with the callback object to listen for callbacks. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/callbackbehaviorattribute/cs/client.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/callbackbehaviorattribute/vb/client.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/callbackbehaviorattribute/vb/client.vb" id="Snippet3"::: + ]]> @@ -107,17 +107,17 @@ System.ServiceModel.Duplex - + An object used to create the instance context that associates the callback object with the channel to the service. Initializes a new instance of the class using the specified callback object. - object using the `callbackInstance` object to handle all callback operations. - + object using the `callbackInstance` object to handle all callback operations. + ]]> @@ -166,11 +166,11 @@ An object that associates the callback object with the channel to the service. Initializes a new instance of the class using the specified callback object. - @@ -193,8 +193,8 @@ System.ServiceModel.Duplex - - + + An object used to create the instance context that associates the callback object with the channel to the service. @@ -222,19 +222,19 @@ System.ServiceModel.Duplex - - + + An object used to create the instance context that associates the callback object with the channel to the service. The name of the client endpoint information in the application configuration file. Initializes a new instance of the class using the specified callback object and configuration name. - object using the `callbackInstance` object to handle all callback operations. - + object using the `callbackInstance` object to handle all callback operations. + ]]> @@ -263,8 +263,8 @@ - - + + An object that associates the callback object with the channel to the service. @@ -322,11 +322,11 @@ The name of the client endpoint information in the application configuration file. Initializes a new instance of the class using the specified callback object and configuration name. - @@ -350,9 +350,9 @@ System.ServiceModel.Duplex - - - + + + An object used to create the instance context that associates the callback object with the channel to the service. @@ -360,11 +360,11 @@ The service endpoint address to use. Initializes a new instance of the class using the specified callback object, binding, and service endpoint address. - object using the `callbackInstance` object to handle all callback operations. - + object using the `callbackInstance` object to handle all callback operations. + ]]> @@ -388,9 +388,9 @@ System.ServiceModel.Duplex - - - + + + An object used to create the instance context that associates the callback object with the channel to the service. @@ -398,11 +398,11 @@ The address of the service endpoint to use. Initializes a new instance of the class using the specified callback object, endpoint configuration name, and service endpoint address. - object using the `callbackInstance` object to handle all callback operations. - + object using the `callbackInstance` object to handle all callback operations. + ]]> @@ -455,11 +455,11 @@ The service endpoint address to use. Initializes a new instance of the class using the specified callback object, binding, and service endpoint address. - @@ -513,11 +513,11 @@ The address of the service endpoint to use. Initializes a new instance of the class using the specified callback object, configuration name, and service endpoint address. - @@ -573,11 +573,11 @@ The address of the service endpoint to use. Initializes a new instance of the class using the specified callback object, configuration name, and service endpoint address. - @@ -601,23 +601,21 @@ System.ServiceModel.Duplex - + - - + An object used to create the instance context that associates the callback object with the channel to the service. The name of the client endpoint information in the application configuration file. - The name of the client endpoint information in the application configuration file. The address of the service endpoint to use. Initializes a new instance of the class using the specified callback object, configuration name, and service endpoint address. - object using the `callbackInstance` object to handle all callback operations. - + object using the `callbackInstance` object to handle all callback operations. + ]]> diff --git a/xml/System.ServiceModel/EndpointAddress.xml b/xml/System.ServiceModel/EndpointAddress.xml index a1f8d7580bf..89e4e8d9014 100644 --- a/xml/System.ServiceModel/EndpointAddress.xml +++ b/xml/System.ServiceModel/EndpointAddress.xml @@ -244,9 +244,9 @@ System.ServiceModel.Primitives - - - + + + The that identifies the endpoint location. @@ -288,11 +288,11 @@ - - - - - + + + + + The that identifies the endpoint location. @@ -972,7 +972,7 @@ System.ServiceModel.EndpointAddress - + The from which the endpoint address is obtained. @@ -1058,8 +1058,8 @@ System.ServiceModel.EndpointAddress - - + + The of the current endpoint address. @@ -1098,9 +1098,9 @@ System.ServiceModel.EndpointAddress - - - + + + The from which the endpoint address is obtained. @@ -1141,10 +1141,10 @@ System.ServiceModel.EndpointAddress - - - - + + + + The of the current endpoint address. @@ -1183,10 +1183,10 @@ System.ServiceModel.EndpointAddress - - - - + + + + The of the current endpoint address. @@ -1385,8 +1385,8 @@ System.Void - - + + The of the current endpoint address. @@ -1435,8 +1435,8 @@ System.Void - - + + The of the current endpoint address. @@ -1475,8 +1475,8 @@ System.Void - - + + The of the current endpoint address. @@ -1515,17 +1515,15 @@ System.Void - - + + - - + The of the current endpoint address. The to which the endpoint address is saved. The local name for the XML node to contain the endpoint address. - The local name for the XML node to contain the endpoint address. The that contains the namespace for the XML node to contain the endpoint address. Saves the current endpoint address of a specified version to an XML dictionary writer with a specified namespace and local name. @@ -1561,17 +1559,15 @@ System.Void - - + + - - + The of the current endpoint address. The to which the endpoint address is saved. The local name for the XML node to contain the endpoint address. - The local name for the XML node to contain the endpoint address. The that contains the namespace for the XML node to contain the endpoint address. Saves the current endpoint address of a specified version to an XML writer with a specified namespace and local name. diff --git a/xml/System.ServiceModel/EndpointAddressBuilder.xml b/xml/System.ServiceModel/EndpointAddressBuilder.xml index 391643874e2..8ce06472cfb 100644 --- a/xml/System.ServiceModel/EndpointAddressBuilder.xml +++ b/xml/System.ServiceModel/EndpointAddressBuilder.xml @@ -39,19 +39,19 @@ A factory for producing new (immutable) endpoint addresses with specific property values. - constructor. - - The endpoint addresses created can have their URI and identity values set using the and properties of the endpoint address builder. Note that is an immutable class. - - - -## Examples + constructor. + + The endpoint addresses created can have their URI and identity values set using the and properties of the endpoint address builder. Note that is an immutable class. + + + +## Examples :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_ueendpointaddressbuilder/cs/program.cs" id="Snippet0"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_ueendpointaddressbuilder/vb/module1.vb" id="Snippet0"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_ueendpointaddressbuilder/vb/module1.vb" id="Snippet0"::: + ]]> @@ -95,12 +95,12 @@ Initializes a new instance of the class. - @@ -138,17 +138,17 @@ The whose property values are used to initialize the property values of this instance. Initializes a new instance of the class from an existing endpoint address. - @@ -180,17 +180,17 @@ Returns the XML dictionary reader that contains the extensions of the endpoint address. The that reads the extensions of the endpoint address. - @@ -220,12 +220,12 @@ Returns the reader that contains the metadata associated with the endpoint address. The that reads the metadata associated the endpoint address if there is some; otherwise, . - @@ -269,17 +269,17 @@ Gets the list of address headers for the endpoints that the builder can create. The of type that contains the address headers for the endpoints that the builder can create. - constructor. - - - -## Examples + constructor. + + + +## Examples :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_ueendpointaddressbuilder/cs/program.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_ueendpointaddressbuilder/vb/module1.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_ueendpointaddressbuilder/vb/module1.vb" id="Snippet3"::: + ]]> @@ -327,17 +327,17 @@ Gets or sets the identity for the endpoints that the builder can create. The for the endpoint. - @@ -363,18 +363,18 @@ System.Void - + The that reads the extensions of the endpoint. Specifies the XML dictionary reader that contains the extensions of the endpoint address. - @@ -400,18 +400,18 @@ System.Void - + The that reads the metadata associated with the endpoint. Specifies the XML dictionary reader that contains the metadata associated with the endpoint address. - @@ -450,17 +450,17 @@ Creates a new endpoint address initialized with the property values of the current endpoint address builder. The whose property are initialized with the values of the current endpoint address builder. - @@ -508,17 +508,17 @@ Gets or sets the URI for the endpoints that the builder can create. The that specifies the endpoint address. - diff --git a/xml/System.ServiceModel/EndpointIdentity.xml b/xml/System.ServiceModel/EndpointIdentity.xml index 5529c69d41a..62c04e26799 100644 --- a/xml/System.ServiceModel/EndpointIdentity.xml +++ b/xml/System.ServiceModel/EndpointIdentity.xml @@ -39,11 +39,11 @@ An abstract class that when implemented provides an identity that enables the authentication of an endpoint by clients that exchange messages with it. - , where its value can also be accessed as a read-only property. - + , where its value can also be accessed as a read-only property. + ]]> @@ -106,27 +106,27 @@ System.ServiceModel.EndpointIdentity - + The name for the DNS identity. Creates a DNS identity with a specified DNS name. A DNS associated with the specified . - by calling its constructor . - - - -## Examples - The following code shows how to call this method. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_ueendpointidentity/cs/source.cs" id="Snippet41"::: - + by calling its constructor . + + + +## Examples + The following code shows how to call this method. + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_ueendpointidentity/cs/source.cs" id="Snippet41"::: + ]]> @@ -156,27 +156,27 @@ System.ServiceModel.EndpointIdentity - + A used to create the new identity. Creates an identity with the specified claim. An associated with the specified . - , , , or . - - - -## Examples - The following code shows how to call this method. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_ueendpointidentity/cs/source.cs" id="Snippet42"::: - + , , , or . + + + +## Examples + The following code shows how to call this method. + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_ueendpointidentity/cs/source.cs" id="Snippet42"::: + ]]> @@ -191,13 +191,13 @@ Creates an RSA identity. - by calling its constructor . - + by calling its constructor . + ]]> @@ -222,27 +222,27 @@ System.ServiceModel.EndpointIdentity - + An that contains the certificate for the RSA identity. Creates an RSA identity with the specified X.509 certificate. An RSA associated with the specified . - by calling its constructor, . - - - -## Examples - The following code shows how to call this method. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_ueendpointidentity/cs/source.cs" id="Snippet41"::: - + by calling its constructor, . + + + +## Examples + The following code shows how to call this method. + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_ueendpointidentity/cs/source.cs" id="Snippet41"::: + ]]> @@ -271,20 +271,20 @@ System.ServiceModel.EndpointIdentity - + The public key for the RSA identity. Creates an RSA identity with the specified public key. An RSA associated with the specified . - by calling its constructor, . - + by calling its constructor, . + ]]> @@ -312,29 +312,29 @@ System.ServiceModel.EndpointIdentity - + The name for the SPN identity. Creates a server principal name (SPN) identity with a specified name. An SPN associated with the specified . - by calling its constructor, , using `spnName` as the input parameter. - - If `spnName` is specified with an empty string, authentication falls back from Kerberos to NTLM if possible. If is `false`, authentication fails. - - - -## Examples - The following code shows how to call this method. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_ueendpointidentity/cs/source.cs" id="Snippet12"::: - + by calling its constructor, , using `spnName` as the input parameter. + + If `spnName` is specified with an empty string, authentication falls back from Kerberos to NTLM if possible. If is `false`, authentication fails. + + + +## Examples + The following code shows how to call this method. + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_ueendpointidentity/cs/source.cs" id="Snippet12"::: + ]]> @@ -362,29 +362,29 @@ System.ServiceModel.EndpointIdentity - + The name for the UPN identity. Creates a user principal name (UPN) identity with a specified name. A UPN associated with the specified . - by calling its constructor, , using `upnName` as the input parameter. - - If `upnName` is specified with an empty string, authentication falls back from Kerberos to NTLM if possible. If is `false`, WCF makes a best-effort to throw an exception if NTLM is used. Note that setting this property to `false` may not prevent NTLM credentials from being sent over the wire. - - - -## Examples - The following code shows how to call this method. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_ueendpointidentity/cs/source.cs" id="Snippet30"::: - + by calling its constructor, , using `upnName` as the input parameter. + + If `upnName` is specified with an empty string, authentication falls back from Kerberos to NTLM if possible. If is `false`, WCF makes a best-effort to throw an exception if NTLM is used. Note that setting this property to `false` may not prevent NTLM credentials from being sent over the wire. + + + +## Examples + The following code shows how to call this method. + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_ueendpointidentity/cs/source.cs" id="Snippet30"::: + ]]> @@ -399,13 +399,13 @@ Creates an X509Certificate identity. - @@ -430,27 +430,27 @@ System.ServiceModel.EndpointIdentity - + An that contains the certificate for the identity. Creates an X509Certificate identity with the specified certificate. An X509Certificate associated with the specified . - by calling its constructor, , using `certificate` as the input parameter. - - - -## Examples - The following code shows how to call this method. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_ueendpointidentity/cs/source.cs" id="Snippet40"::: - + by calling its constructor, , using `certificate` as the input parameter. + + + +## Examples + The following code shows how to call this method. + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_ueendpointidentity/cs/source.cs" id="Snippet40"::: + ]]> @@ -477,22 +477,22 @@ System.ServiceModel.EndpointIdentity - - + + An that contains the primary certificate for the identity. An that contains the supporting certificates for the identity. Creates an X509Certificate identity with the specified primary and supporting certificates. - A secure WCF client that connects to an endpoint with this identity verifies that the claims presented by the server contain the claim that contains the thumbprint of the certificate used to construct this identity. - + A secure WCF client that connects to an endpoint with this identity verifies that the claims presented by the server contain the claim that contains the thumbprint of the certificate used to construct this identity. + An X509Certificate associated with the specified and . - by calling its constructor, , using `primaryCertificate` and `supportingCertificates` as input parameters. - + by calling its constructor, , using `primaryCertificate` and `supportingCertificates` as input parameters. + ]]> @@ -599,11 +599,11 @@ Gets the identity claim that corresponds to the identity. The that represents the identity claim. - @@ -640,19 +640,17 @@ System.Void - - + The used to initialize the . - The used to initialize the . Initializes an with the specified claim. - ). - + ). + ]]> @@ -680,16 +678,12 @@ System.Void - - - - + + The used to initialize the . - The used to initialize the . The used to compare claims. - The used to compare claims. Initializes an with the specified claim and an interface and compares equality. To be added. diff --git a/xml/System.ServiceModel/FaultCode.xml b/xml/System.ServiceModel/FaultCode.xml index 3f0c3b2470a..fc332e1ddb0 100644 --- a/xml/System.ServiceModel/FaultCode.xml +++ b/xml/System.ServiceModel/FaultCode.xml @@ -39,17 +39,17 @@ Represents a SOAP fault code. - @@ -189,11 +189,11 @@ The namespace name of the fault code. Initializes a new instance of the class with the specified name and namespace. - object is used in conjunction with a object to fully represent a SOAP fault. - + object is used in conjunction with a object to fully represent a SOAP fault. + ]]> @@ -276,7 +276,7 @@ System.ServiceModel.FaultCode - + A object that represents the fault subcode. @@ -308,8 +308,8 @@ System.ServiceModel.FaultCode - - + + The local name for the fault subcode. @@ -391,8 +391,8 @@ System.ServiceModel.FaultCode - - + + The local name for the fault subcode. diff --git a/xml/System.ServiceModel/FaultException.xml b/xml/System.ServiceModel/FaultException.xml index 410b652b89d..dd4932c6dc2 100644 --- a/xml/System.ServiceModel/FaultException.xml +++ b/xml/System.ServiceModel/FaultException.xml @@ -62,34 +62,34 @@ Represents a SOAP fault. - class to create an untyped fault to return to the client for debugging purposes. - - In a client, catch objects to handle unknown or generic faults, such as those returned by a service with the property set to `true`. Because extends , remember to catch any objects prior to catching objects if you want to catch them separately. - + class to create an untyped fault to return to the client for debugging purposes. + + In a client, catch objects to handle unknown or generic faults, such as those returned by a service with the property set to `true`. Because extends , remember to catch any objects prior to catching objects if you want to catch them separately. + > [!NOTE] -> Duplex services can also catch objects returned from their interaction with a duplex client. - - In general, it is strongly recommended that you use the to design your services to return strongly-typed SOAP faults (and not managed exception objects) for all fault cases in which you decide the client requires fault information. However, use the in the following situations: - -- To send SOAP faults from a service for debugging purposes. - -- To catch SOAP faults on a client when the faults are not part of the service contract. - - Throw objects when you want the string to be passed to the constructor and retrieved by the client by calling the method. If you specify a fault contract of type where the type parameter is , the string value is available as the property and not by calling . - - For details, see [Specifying and Handling Faults in Contracts and Services](/dotnet/framework/wcf/specifying-and-handling-faults-in-contracts-and-services). - - - -## Examples - The following code example shows the use of a try/catch block to catch and handle objects thrown from a service. This often occurs when debugging is turned on in the service application. - +> Duplex services can also catch objects returned from their interaction with a duplex client. + + In general, it is strongly recommended that you use the to design your services to return strongly-typed SOAP faults (and not managed exception objects) for all fault cases in which you decide the client requires fault information. However, use the in the following situations: + +- To send SOAP faults from a service for debugging purposes. + +- To catch SOAP faults on a client when the faults are not part of the service contract. + + Throw objects when you want the string to be passed to the constructor and retrieved by the client by calling the method. If you specify a fault contract of type where the type parameter is , the string value is available as the property and not by calling . + + For details, see [Specifying and Handling Faults in Contracts and Services](/dotnet/framework/wcf/specifying-and-handling-faults-in-contracts-and-services). + + + +## Examples + The following code example shows the use of a try/catch block to catch and handle objects thrown from a service. This often occurs when debugging is turned on in the service application. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/ierrorhandler/cs/client.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/ierrorhandler/vb/client.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/ierrorhandler/vb/client.vb" id="Snippet3"::: + ]]> @@ -153,7 +153,7 @@ 6.0.0.0 - + The message fault that contains the default SOAP fault values. @@ -179,7 +179,7 @@ 6.0.0.0 - + The reason for the SOAP fault. @@ -276,8 +276,8 @@ 6.0.0.0 - - + + The reason for the SOAP fault. @@ -308,11 +308,9 @@ - The reason for the fault. - The reason for the fault. Initializes a new instance of the class with the specified fault reason. To be added. @@ -374,9 +372,9 @@ 6.0.0.0 - - - + + + The reason for the SOAP fault. @@ -405,12 +403,10 @@ - - + The reason for the SOAP fault. - The reason for the SOAP fault. The SOAP fault code for the fault. Initializes a new instance of the class using the specified reason and SOAP fault code. To be added. @@ -560,11 +556,11 @@ Returns a object from the specified message fault and an array of detail types. A object that you can throw to indicate that a SOAP fault message was received. - is returned where the type parameter is the matching candidate type. - + is returned where the type parameter is the matching candidate type. + ]]> @@ -617,11 +613,11 @@ Returns a object from the specified message fault, action and an array of detail types. A object that you can throw to indicate that a SOAP fault message was received. - is returned where the type parameter is the matching candidate type. - + is returned where the type parameter is the matching candidate type. + ]]> @@ -689,8 +685,8 @@ System.Void - - + + The serialization information to which the object data is added when serialized. diff --git a/xml/System.ServiceModel/FaultException`1.xml b/xml/System.ServiceModel/FaultException`1.xml index 375ead2a227..c492ac78941 100644 --- a/xml/System.ServiceModel/FaultException`1.xml +++ b/xml/System.ServiceModel/FaultException`1.xml @@ -50,36 +50,36 @@ The serializable error detail type. Used in a client application to catch contractually-specified SOAP faults. - object in a Windows Communication Foundation (WCF) client application to handle a SOAP fault that has been contractually specified in an operation contract. - - Typical deployed services use the to formally specify all SOAP faults that a client can expect to receive in the normal course of an operation. Error information in a appears as a (where the typeparameter is the serializable error object specified in the operation's ) when it arrives at a client application. The can be used to specify SOAP faults for both two-way service methods and for asynchronous method pairs. - - Because is both a and therefore a , to catch specified SOAP faults make sure you catch the types prior to the and types or handle the specified exceptions in one of those exception handlers. - + object in a Windows Communication Foundation (WCF) client application to handle a SOAP fault that has been contractually specified in an operation contract. + + Typical deployed services use the to formally specify all SOAP faults that a client can expect to receive in the normal course of an operation. Error information in a appears as a (where the typeparameter is the serializable error object specified in the operation's ) when it arrives at a client application. The can be used to specify SOAP faults for both two-way service methods and for asynchronous method pairs. + + Because is both a and therefore a , to catch specified SOAP faults make sure you catch the types prior to the and types or handle the specified exceptions in one of those exception handlers. + > [!NOTE] -> If you use to specify a where the type parameter is a , the string value is assigned to the property in the client application; clients cannot retrieve that string by calling the method. To have the string value returned when the client application calls , throw a exception inside the operation and pass the string to the constructor. -> In general, it is recommended that detail types be custom serializable types appropriate to the fault and not a . - - - -## Examples - The following code example shows how a service uses the type to throw a managed exception that gets converted into the SOAP fault specified by the . - +> If you use to specify a where the type parameter is a , the string value is assigned to the property in the client application; clients cannot retrieve that string by calling the method. To have the string value returned when the client application calls , throw a exception inside the operation and pass the string to the constructor. +> In general, it is recommended that detail types be custom serializable types appropriate to the fault and not a . + + + +## Examples + The following code example shows how a service uses the type to throw a managed exception that gets converted into the SOAP fault specified by the . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/faultcontractattribute/cs/Host/services.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/faultcontractattribute/vb/services.vb" id="Snippet1"::: - - The following code example shows how the client code looks when imported by the client using the [ServiceModel Metadata Utility Tool (Svcutil.exe)](/dotnet/framework/wcf/servicemodel-metadata-utility-tool-svcutil-exe). - - - - The following code example shows how a client can catch the type that represents the custom SOAP fault specified in the operation contract. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/faultcontractattribute/vb/services.vb" id="Snippet1"::: + + The following code example shows how the client code looks when imported by the client using the [ServiceModel Metadata Utility Tool (Svcutil.exe)](/dotnet/framework/wcf/servicemodel-metadata-utility-tool-svcutil-exe). + + + + The following code example shows how a client can catch the type that represents the custom SOAP fault specified in the operation contract. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/faultcontractattribute/cs/Client/client.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/faultcontractattribute/vb/client.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/faultcontractattribute/vb/client.vb" id="Snippet3"::: + ]]> @@ -123,25 +123,25 @@ - + The object used as the SOAP fault detail. Initializes a new instance of the class that uses the specified detail object. - is serialized. - - - -## Examples - The following code example shows how a service uses the type to throw a managed exception that gets converted into the SOAP fault specified by the . - + is serialized. + + + +## Examples + The following code example shows how a service uses the type to throw a managed exception that gets converted into the SOAP fault specified by the . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/faultcontractattribute/cs/Host/services.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/faultcontractattribute/vb/services.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/faultcontractattribute/vb/services.vb" id="Snippet1"::: + ]]> @@ -209,8 +209,8 @@ - - + + The object used as the SOAP fault detail. @@ -243,8 +243,8 @@ - - + + The object used as the SOAP fault detail. @@ -277,9 +277,9 @@ - - - + + + The object used as the SOAP fault detail. @@ -313,9 +313,9 @@ - - - + + + The object used as the SOAP fault detail. @@ -396,10 +396,10 @@ - - - - + + + + The object used as the SOAP fault detail. @@ -514,8 +514,8 @@ System.Void - - + + The serialization information to which the object data is added when serialized. diff --git a/xml/System.ServiceModel/FaultReasonText.xml b/xml/System.ServiceModel/FaultReasonText.xml index 3a1409480af..bd1fbe7c592 100644 --- a/xml/System.ServiceModel/FaultReasonText.xml +++ b/xml/System.ServiceModel/FaultReasonText.xml @@ -39,11 +39,11 @@ Represents the text of the reason of a SOAP fault. - class to specify the text of the SOAP fault reason. - + class to specify the text of the SOAP fault reason. + ]]> @@ -111,8 +111,8 @@ 6.0.0.0 - - + + The text that is the reason of the SOAP fault. diff --git a/xml/System.ServiceModel/HttpBindingBase.xml b/xml/System.ServiceModel/HttpBindingBase.xml index 78b83e11b47..1216a78004b 100644 --- a/xml/System.ServiceModel/HttpBindingBase.xml +++ b/xml/System.ServiceModel/HttpBindingBase.xml @@ -49,27 +49,6 @@ To be added. - - - - - - - Constructor - - System.ServiceModel - 2.0.5.0 - 4.0.0.0 - - - System.ServiceModel.Http - - - - To be added. - To be added. - - diff --git a/xml/System.ServiceModel/NetHttpBinding.xml b/xml/System.ServiceModel/NetHttpBinding.xml index 0acead8576b..c42dfcfd3d2 100644 --- a/xml/System.ServiceModel/NetHttpBinding.xml +++ b/xml/System.ServiceModel/NetHttpBinding.xml @@ -38,19 +38,19 @@ Specifies settings for . - is a binding designed for consuming HTTP or WebSocket services and uses binary encoding by default. Note: WebSockets are only supported on Windows 8. will detect whether it is used with a request-reply contract or duplex contract and change its behavior to match - it will use HTTP for request-reply and WebSockets for duplex (only on Windows 8). This behavior can be overridden by setting the property to one of the following values: - -1. WhenDuplex- This is the default value and behaves as described above. - -2. Never - This prevents WebSockets from being used. Attempting to use a duplex contract with this setting will result in an exception. - -3. Always - This forces WebSockets to be used even for request-reply contracts. - - supports reliable sessions in both HTTP mode and WebSocket mode. In WebSocket mode sessions are provided by the transport. - + is a binding designed for consuming HTTP or WebSocket services and uses binary encoding by default. Note: WebSockets are only supported on Windows 8. will detect whether it is used with a request-reply contract or duplex contract and change its behavior to match - it will use HTTP for request-reply and WebSockets for duplex (only on Windows 8). This behavior can be overridden by setting the property to one of the following values: + +1. WhenDuplex- This is the default value and behaves as described above. + +2. Never - This prevents WebSockets from being used. Attempting to use a duplex contract with this setting will result in an exception. + +3. Always - This forces WebSockets to be used even for request-reply contracts. + + supports reliable sessions in both HTTP mode and WebSocket mode. In WebSocket mode sessions are provided by the transport. + ]]> @@ -188,8 +188,8 @@ 8.0.0.0 - - + + The mode of the security. diff --git a/xml/System.ServiceModel/NetHttpsBinding.xml b/xml/System.ServiceModel/NetHttpsBinding.xml index 95cc813bbf5..1095c11b4be 100644 --- a/xml/System.ServiceModel/NetHttpsBinding.xml +++ b/xml/System.ServiceModel/NetHttpsBinding.xml @@ -126,7 +126,7 @@ System.ServiceModel.Http - + The binding configuration name. @@ -154,8 +154,8 @@ 8.0.0.0 - - + + The type of security used with the binding. diff --git a/xml/System.ServiceModel/NetTcpBinding.xml b/xml/System.ServiceModel/NetTcpBinding.xml index 08e0b127ffd..a1785f36685 100644 --- a/xml/System.ServiceModel/NetTcpBinding.xml +++ b/xml/System.ServiceModel/NetTcpBinding.xml @@ -48,23 +48,23 @@ A secure, reliable binding suitable for cross-machine communication. - generates a run-time communication stack by default, which uses transport security, TCP for message delivery, and a binary message encoding. This binding is an appropriate Windows Communication Foundation (WCF) system-provided choice for communicating over an Intranet. - - The default configuration for the is faster than the configuration provided by the , but it is intended only for WCF communication. The security behavior is configurable using the optional `securityMode` parameter in the constructor. The use of WS-ReliableMessaging is configurable using the optional `reliableSessionEnabled` parameter. But reliable messaging is off by default. More generally, the HTTP system-provided bindings such as and are configured to turn things on by default, whereas the binding turns things off by default so that you have to opt-in to get support, for example, for one of the WS-* specifications. This means that the default configuration for TCP is faster at exchanging messages between endpoints than that configured for the HTTP bindings by default. - + generates a run-time communication stack by default, which uses transport security, TCP for message delivery, and a binary message encoding. This binding is an appropriate Windows Communication Foundation (WCF) system-provided choice for communicating over an Intranet. + + The default configuration for the is faster than the configuration provided by the , but it is intended only for WCF communication. The security behavior is configurable using the optional `securityMode` parameter in the constructor. The use of WS-ReliableMessaging is configurable using the optional `reliableSessionEnabled` parameter. But reliable messaging is off by default. More generally, the HTTP system-provided bindings such as and are configured to turn things on by default, whereas the binding turns things off by default so that you have to opt-in to get support, for example, for one of the WS-* specifications. This means that the default configuration for TCP is faster at exchanging messages between endpoints than that configured for the HTTP bindings by default. + > [!WARNING] -> The uses TCP connection pooling based on the service's host DNS name and the port number the service is listening on. This works well when a client makes calls to different services on different ports, or services are hosted in a single process and share a port. If a single client calls multiple services sharing a port that are hosted in different processes, or are WAS/IIS hosted, the client side pooling may lead to problems where a connection to Service A is reused for Service B, resulting in an exception being thrown, the connection aborted, and a new channel created. To avoid this problem, use a CustomBinding and specify a different ConnectionPoolSettings.GroupName for each service the client communicates with. - - - -## Examples - This example shows how to create a , setting the security mode and transport credential type. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uenettcpbinding/cs/source.cs" id="Snippet1"::: - +> The uses TCP connection pooling based on the service's host DNS name and the port number the service is listening on. This works well when a client makes calls to different services on different ports, or services are hosted in a single process and share a port. If a single client calls multiple services sharing a port that are hosted in different processes, or are WAS/IIS hosted, the client side pooling may lead to problems where a connection to Service A is reused for Service B, resulting in an exception being thrown, the connection aborted, and a new channel created. To avoid this problem, use a CustomBinding and specify a different ConnectionPoolSettings.GroupName for each service the client communicates with. + + + +## Examples + This example shows how to create a , setting the security mode and transport credential type. + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uenettcpbinding/cs/source.cs" id="Snippet1"::: + ]]> @@ -78,11 +78,11 @@ Initializes a new instance of the class. - @@ -116,18 +116,18 @@ Initializes a new instance of the class. - is set to ) and reliable sessions are disabled (that is is `false`). - - - -## Examples - This example shows how to create a , setting the security mode and transport credential type. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uenettcpbinding/cs/source.cs" id="Snippet1"::: - + is set to ) and reliable sessions are disabled (that is is `false`). + + + +## Examples + This example shows how to create a , setting the security mode and transport credential type. + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uenettcpbinding/cs/source.cs" id="Snippet1"::: + ]]> @@ -165,18 +165,18 @@ The value that specifies the type of security used with the binding. Initializes a new instance of the class with the type of security used specified. - . - - - -## Examples - This example shows how to create a using the security mode parameter. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uenettcpbinding/cs/source.cs" id="Snippet3"::: - + . + + + +## Examples + This example shows how to create a using the security mode parameter. + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uenettcpbinding/cs/source.cs" id="Snippet3"::: + ]]> @@ -219,18 +219,18 @@ The binding configuration name for the . Initializes a new instance of the class with a specified configuration name. - using the `configurationName` parameter. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uenettcpbinding/cs/source.cs" id="Snippet4"::: - + using the `configurationName` parameter. + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uenettcpbinding/cs/source.cs" id="Snippet4"::: + ]]> netTcpBinding Element @@ -257,8 +257,8 @@ 8.0.0.0 - - + + The value that specifies the type of security used with the binding. @@ -266,18 +266,18 @@ if reliable sessions are enabled; otherwise, . Initializes a new instance of the class with the type of security used specified and with a value that indicates whether reliable sessions are explicitly enabled. - using the `securityMode` and `reliableSessionEnabled` parameters. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uenettcpbinding/cs/source.cs" id="Snippet5"::: - + using the `securityMode` and `reliableSessionEnabled` parameters. + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uenettcpbinding/cs/source.cs" id="Snippet5"::: + ]]> @@ -316,13 +316,13 @@ Creates a collection with the binding elements for the binding. The of type that makes up the binding. - method to create a collection with the binding elements for the binding. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uenettcpbinding/cs/source.cs" id="Snippet20"::: - + method to create a collection with the binding elements for the binding. + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uenettcpbinding/cs/source.cs" id="Snippet20"::: + ]]> @@ -360,18 +360,18 @@ Gets the version of SOAP that is used for messages processed by this binding. The value of the that is used with this binding. The value is SOAP 1.2. - value. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uenettcpbinding/cs/source.cs" id="Snippet6"::: - + value. + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uenettcpbinding/cs/source.cs" id="Snippet6"::: + ]]> @@ -405,13 +405,13 @@ Gets or sets a value that indicates whether the hostname is used to reach the service when matching the URI. One of the values that indicates whether the hostname is used to reach the service when matching the URI. The default value is , which ignores the hostname in the match. - value. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uenettcpbinding/cs/source.cs" id="Snippet7"::: - + value. + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uenettcpbinding/cs/source.cs" id="Snippet7"::: + ]]> @@ -445,18 +445,18 @@ Gets or sets the maximum number of queued connection requests that can be pending. The maximum number of pending queued connection requests. The default is 10. - is a socket-level property that describes the number of "pending accept" requests to be queued. If the listen backlog queue fills up, new socket requests will be rejected. - - - -## Examples - This example shows how to get the value. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uenettcpbinding/cs/source.cs" id="Snippet8"::: - + is a socket-level property that describes the number of "pending accept" requests to be queued. If the listen backlog queue fills up, new socket requests will be rejected. + + + +## Examples + This example shows how to get the value. + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uenettcpbinding/cs/source.cs" id="Snippet8"::: + ]]> The value cannot be less than zero. @@ -501,18 +501,18 @@ Gets or sets the maximum size, in bytes, allowed for a buffer pool that stores TCP messages processed by the binding. The maximum size allowed for a buffer pool that stores TCP messages processed by the binding. The default value is 524,288 bytes. - value. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uenettcpbinding/cs/source.cs" id="Snippet9"::: - + value. + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uenettcpbinding/cs/source.cs" id="Snippet9"::: + ]]> @@ -556,18 +556,18 @@ Gets or sets a value that specifies the maximum size, in bytes, of the buffer used to store messages in memory. The maximum size, in bytes, of the buffer used to store messages in memory. The default value is 65,536 bytes. - . - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uenettcpbinding/cs/source.cs" id="Snippet10"::: - + . + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uenettcpbinding/cs/source.cs" id="Snippet10"::: + ]]> @@ -605,18 +605,18 @@ Gets or sets a value that controls the maximum number of connections to be pooled for subsequent reuse on the client and the maximum number of connections allowed to be pending dispatch on the server. On the client, the maximum number of connections to be pooled for subsequent reuse; on the server, the maximum number of connections allowed to be pending dispatch. - value. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uenettcpbinding/cs/source.cs" id="Snippet11"::: - + value. + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uenettcpbinding/cs/source.cs" id="Snippet11"::: + ]]> @@ -660,13 +660,13 @@ Gets or sets the maximum size, in bytes, for a received message that is processed by the binding. The maximum size (in bytes) for a received message that is processed by the binding. The default value is 65,536 bytes. - value. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uenettcpbinding/cs/source.cs" id="Snippet12"::: - + value. + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uenettcpbinding/cs/source.cs" id="Snippet12"::: + ]]> @@ -701,20 +701,20 @@ if TCP port sharing is enabled; otherwise, . The default value is . - . - - - -## Examples - This example shows how to get the value. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uenettcpbinding/cs/source.cs" id="Snippet13"::: - + . + + + +## Examples + This example shows how to get the value. + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uenettcpbinding/cs/source.cs" id="Snippet13"::: + ]]> @@ -752,28 +752,28 @@ Gets or sets constraints on the complexity of SOAP messages that can be processed by endpoints configured with this binding. The that specifies the complexity constraints on soap messages exchanged. The default values for these constraints are provided in the following Remarks section. - = 32 - -- = 8192 - -- = 16384 - -- = 4096 - -- = 16384 - - - -## Examples - The following example shows how to get the object. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uenettcpbinding/cs/source.cs" id="Snippet14"::: - + = 32 + +- = 8192 + +- = 16384 + +- = 4096 + +- = 16384 + + + +## Examples + The following example shows how to get the object. + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uenettcpbinding/cs/source.cs" id="Snippet14"::: + ]]> @@ -815,13 +815,13 @@ Gets an object that indicates whether a reliable session is established between channel endpoints. An that indicates whether a WS-RM reliable session is established between channel endpoints. The default value for is . - value. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uenettcpbinding/cs/source.cs" id="Snippet15"::: - + value. + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uenettcpbinding/cs/source.cs" id="Snippet15"::: + ]]> @@ -859,18 +859,18 @@ Returns the URI scheme for the transport. The URI scheme for the transport, which is "net.tcp". - value. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uenettcpbinding/cs/source.cs" id="Snippet16"::: - + value. + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uenettcpbinding/cs/source.cs" id="Snippet16"::: + ]]> @@ -918,18 +918,18 @@ Gets an object that specifies the type of security used with services configured with this binding. The that contains the types of security used with this binding. The default mode of security for the is . - provides the types of security and settings available to the . - - - -## Examples - This example shows how to get the value. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uenettcpbinding/cs/source.cs" id="Snippet17"::: - + provides the types of security and settings available to the . + + + +## Examples + This example shows how to get the value. + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uenettcpbinding/cs/source.cs" id="Snippet17"::: + ]]> @@ -1153,18 +1153,18 @@ if incoming requests are handled synchronously; if incoming requests are handled asynchronously. The default value is . - value. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uenettcpbinding/cs/source.cs" id="Snippet21"::: - + value. + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uenettcpbinding/cs/source.cs" id="Snippet21"::: + ]]> @@ -1199,13 +1199,13 @@ if transaction flow is enabled; otherwise, . The default value is . - value. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uenettcpbinding/cs/source.cs" id="Snippet18"::: - + value. + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uenettcpbinding/cs/source.cs" id="Snippet18"::: + ]]> @@ -1233,13 +1233,13 @@ Gets or sets the transactions protocol used by the service to flow transactions. The used by the service to flow transactions. - value. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uenettcpbinding/cs/source.cs" id="Snippet19"::: - + value. + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uenettcpbinding/cs/source.cs" id="Snippet19"::: + ]]> @@ -1283,13 +1283,13 @@ Gets or sets a value that indicates whether the service configured with the binding uses streamed or buffered (or both) modes of message transfer. The value that indicates whether the service configured with the binding uses streamed or buffered (or both) modes of message transfer. - value. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uenettcpbinding/cs/source.cs" id="Snippet22"::: - + value. + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uenettcpbinding/cs/source.cs" id="Snippet22"::: + ]]> diff --git a/xml/System.ServiceModel/WebHttpSecurity.xml b/xml/System.ServiceModel/WebHttpSecurity.xml index 7fd4eb3ae3f..a37c87b48ba 100644 --- a/xml/System.ServiceModel/WebHttpSecurity.xml +++ b/xml/System.ServiceModel/WebHttpSecurity.xml @@ -18,23 +18,23 @@ Specifies the types of security available to a service endpoint configured to receive HTTP requests. - provides the security requirements for an endpoint configured with a . - - If the value is specified by the method, then the settings provided by the property become effective for the service endpoint. The value of can only be set in the constructor that takes it as an explicit parameter and its value cannot be set again after the binding instance is created. - + provides the security requirements for an endpoint configured with a . + + If the value is specified by the method, then the settings provided by the property become effective for the service endpoint. The value of can only be set in the constructor that takes it as an explicit parameter and its value cannot be set again after the binding instance is created. + ]]> - - - - - + + + + + Constructor System.ServiceModel.Web @@ -67,11 +67,11 @@ Gets or sets the mode of security that is used by an endpoint configured to receive HTTP requests with a . A value of the that indicates whether transport-level security or no security is used by an endpoint. The default value is . - property becomes effective. - + property becomes effective. + ]]> The value is not a valid . @@ -157,19 +157,19 @@ Gets an object that contains the transport-level security settings for this binding. - The for this binding. - + The for this binding. + The default values set are a of , a of , and = "". - object returned by this property to set the transport security parameters for the . - - If the or value is specified by the method, then the settings provided by the property become effective for the service endpoint. - - If the value is specified by the method, then the settings provided by the property become effective for the service endpoint. The value of can only be set in the constructor that takes it as an explicit parameter and its value cannot be set again after the binding instance is created. - + object returned by this property to set the transport security parameters for the . + + If the or value is specified by the method, then the settings provided by the property become effective for the service endpoint. + + If the value is specified by the method, then the settings provided by the property become effective for the service endpoint. The value of can only be set in the constructor that takes it as an explicit parameter and its value cannot be set again after the binding instance is created. + ]]> diff --git a/xml/System.ServiceModel/X509CertificateEndpointIdentity.xml b/xml/System.ServiceModel/X509CertificateEndpointIdentity.xml index 58a48a750f7..a950c9fa07a 100644 --- a/xml/System.ServiceModel/X509CertificateEndpointIdentity.xml +++ b/xml/System.ServiceModel/X509CertificateEndpointIdentity.xml @@ -39,11 +39,11 @@ Initializes a new instance of the class. - @@ -80,11 +80,11 @@ The certificate to clone. Initializes a new instance of the class using an existing certificate. - @@ -109,19 +109,19 @@ 6.0.0.0 - - + + The primary certificate representing the service's identity. The certificates that are part of the trust chain of the primary certificate. Initializes a new instance of the class using the primary (leaf) certificate and certificates that are part of its trust chain. - @@ -166,11 +166,11 @@ Gets the collection of certificates for this identity. An object. - as well as any `supportingCertificates`. - + as well as any `supportingCertificates`. + ]]> diff --git a/xml/System.Text.RegularExpressions/CaptureCollection.xml b/xml/System.Text.RegularExpressions/CaptureCollection.xml index 8eab4237761..e93a2245d4d 100644 --- a/xml/System.Text.RegularExpressions/CaptureCollection.xml +++ b/xml/System.Text.RegularExpressions/CaptureCollection.xml @@ -102,35 +102,35 @@ Represents the set of captures made by a single capturing group. The collection is immutable (read-only) and has no public constructor. - object contains one or more objects. - - Instances of the class are returned by the following properties: - -- The property. Each member of the collection represents a substring captured by a capturing group. If a quantifier is not applied to a capturing group, the includes a single object that represents the same captured substring as the object. If a quantifier is applied to a capturing group, the includes one object for each captured substring, and the object provides information only about the last captured substring. - -- The `Match.Captures` property. In this case, the collection consists of a single object that provides information about the match as a whole. That is, the object provides the same information as the object. - - To iterate through the members of the collection, you should use the collection iteration construct provided by your language (such as `foreach` in C# and `For Each`…`Next` in Visual Basic) instead of retrieving the enumerator that is returned by the method. - - - -## Examples - The following example compares the objects in the object returned by the and `Match.Captures` properties. It also compares objects with the objects in the returned by the property. The example uses the following two regular expressions to find matches in a single input string: - -- `\b\w+\W{1,2}` - - This regular expression pattern identifies a word that consists of one or more word characters, followed by either one or two non-word characters such as white space or punctuation. The regular expression does not include any capturing groups. The output from the example shows that both the object and the objects returned by the and `Match.Captures` properties contain information about the same match. - -- `(\b\w+\W{1,2})+` - - This regular expression pattern identifies the words in a sentence. The pattern defines a single capturing group that consists of one or more word characters followed by one or two non-word characters. The regular expression pattern uses the `+` quantifier to match one or more occurrences of this group. The output from this example shows that the object and the object returned by the `Match.Captures` property contain information about the same match. The second object, which corresponds to the only capturing group in the regular expression, identifies only the last captured string, whereas the object returned by the first capturing group's property includes all captured substrings. + object contains one or more objects. + + Instances of the class are returned by the following properties: + +- The property. Each member of the collection represents a substring captured by a capturing group. If a quantifier is not applied to a capturing group, the includes a single object that represents the same captured substring as the object. If a quantifier is applied to a capturing group, the includes one object for each captured substring, and the object provides information only about the last captured substring. + +- The `Match.Captures` property. In this case, the collection consists of a single object that provides information about the match as a whole. That is, the object provides the same information as the object. + + To iterate through the members of the collection, you should use the collection iteration construct provided by your language (such as `foreach` in C# and `For Each`…`Next` in Visual Basic) instead of retrieving the enumerator that is returned by the method. + + + +## Examples + The following example compares the objects in the object returned by the and `Match.Captures` properties. It also compares objects with the objects in the returned by the property. The example uses the following two regular expressions to find matches in a single input string: + +- `\b\w+\W{1,2}` + + This regular expression pattern identifies a word that consists of one or more word characters, followed by either one or two non-word characters such as white space or punctuation. The regular expression does not include any capturing groups. The output from the example shows that both the object and the objects returned by the and `Match.Captures` properties contain information about the same match. + +- `(\b\w+\W{1,2})+` + + This regular expression pattern identifies the words in a sentence. The pattern defines a single capturing group that consists of one or more word characters followed by one or two non-word characters. The regular expression pattern uses the `+` quantifier to match one or more occurrences of this group. The output from this example shows that the object and the object returned by the `Match.Captures` property contain information about the same match. The second object, which corresponds to the only capturing group in the regular expression, identifies only the last captured string, whereas the object returned by the first capturing group's property includes all captured substrings. :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/CaptureCollection/Overview/capturecollectionex1.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.capturecollection/vb/capturecollectionex1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.capturecollection/vb/capturecollectionex1.vb" id="Snippet1"::: + ]]> @@ -175,31 +175,31 @@ System.Void - - + + The array the collection is to be copied into. The position in the destination array where copying is to begin. Copies all the elements of the collection to the given array beginning at the given index. - [!WARNING] -> This member is not present in the Portable Class Library. If you are developing applications that target the Portable Class Library, use the method instead. - +> This member is not present in the Portable Class Library. If you are developing applications that target the Portable Class Library, use the method instead. + ]]> is . - is outside the bounds of . - - -or- - + is outside the bounds of . + + -or- + plus is outside the bounds of . @@ -352,11 +352,11 @@ Provides an enumerator that iterates through the collection. An object that contains all objects within the . - method to retrieve an enumerator that lets you iterate through the objects in the collection, you should use the group iteration construct (such as `foreach` in C# and `For Each`…`Next` in Visual Basic) that is provided by your programming language. - + method to retrieve an enumerator that lets you iterate through the objects in the collection, you should use the group iteration construct (such as `foreach` in C# and `For Each`…`Next` in Visual Basic) that is provided by your programming language. + ]]> @@ -456,13 +456,13 @@ A collection that is read-only does not allow the addition or removal of element in all cases. - [!WARNING] -> This member is not present in the Portable Class Library. If you are developing applications that target the Portable Class Library, use the property instead. - +> This member is not present in the Portable Class Library. If you are developing applications that target the Portable Class Library, use the property instead. + ]]> @@ -575,13 +575,13 @@ A collection that is read-only does not allow the addition or removal of element Gets an object that can be used to synchronize access to the collection. An object that can be used to synchronize access to the collection. - [!WARNING] -> This member is not present in the Portable Class Library. If you are developing applications that target the Portable Class Library, use the property instead. - +> This member is not present in the Portable Class Library. If you are developing applications that target the Portable Class Library, use the property instead. + ]]> @@ -795,13 +795,13 @@ A collection that is read-only does not allow the addition or removal of element ## Remarks -The returned provides the ability to iterate through the collection by exposing a property .You can use enumerators to read the data in a collection, but not to modify the collection. - Initially, the enumerator is positioned before the first element in the collection. At this position, 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 is called again as 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. You cannot set to the first element of the collection again; you must create a new enumerator instance instead. If changes are made to the collection, such as adding, modifying, or deleting elements, the behavior of the enumerator is undefined. - An enumerator does not have exclusive access to the collection so 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 invalidated and you may get unexpected results. Also, enumerating a collection is not a thread-safe procedure. To guarantee thread-safety, you should lock the collection during enumerator or implement synchronization on the collection. - Default implementations of collections in the namespace aren't synchronized. - +The returned provides the ability to iterate through the collection by exposing a property .You can use enumerators to read the data in a collection, but not to modify the collection. + Initially, the enumerator is positioned before the first element in the collection. At this position, 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 is called again as 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. You cannot set to the first element of the collection again; you must create a new enumerator instance instead. If changes are made to the collection, such as adding, modifying, or deleting elements, the behavior of the enumerator is undefined. + An enumerator does not have exclusive access to the collection so 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 invalidated and you may get unexpected results. Also, enumerating a collection is not a thread-safe procedure. To guarantee thread-safety, you should lock the collection during enumerator or implement synchronization on the collection. + Default implementations of collections in the namespace aren't synchronized. + ]]> @@ -944,7 +944,7 @@ If an object occurs multiple times in the list, the property. Visual Basic implements as a [default](/dotnet/visual-basic/language-reference/modifiers/default) property, which provides the same indexing functionality. ]]> @@ -1072,7 +1072,7 @@ This property provides the ability to access a specific element in the collectio ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - + ]]> @@ -1113,7 +1113,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. - + ]]> @@ -1253,8 +1253,8 @@ This member is an explicit interface member implementation. It can be used only ## Remarks -Starting with the .NET Framework 2.0, this method uses the collection's objects' and methods on `item` to determine whether item exists. In earlier versions of the .NET Framework, this determination was made by using the and methods of the `item` parameter on the objects in the collection. - +Starting with the .NET Framework 2.0, this method uses the collection's objects' and methods on `item` to determine whether item exists. In earlier versions of the .NET Framework, this determination was made by using the and methods of the `item` parameter on the objects in the collection. + ]]> @@ -1303,8 +1303,8 @@ Starting with the .NET Framework 2.0, this method uses the collection's objects' ## Remarks -Starting with the .NET Framework 2.0, this method uses the collection's objects' and methods on `item` to determine whether item exists. In earlier versions of the .NET Framework, this determination was made by using the and methods of the `item` parameter on the objects in the collection. - +Starting with the .NET Framework 2.0, this method uses the collection's objects' and methods on `item` to determine whether item exists. In earlier versions of the .NET Framework, this determination was made by using the and methods of the `item` parameter on the objects in the collection. + ]]> @@ -1395,11 +1395,11 @@ Starting with the .NET Framework 2.0, this method uses the collection's objects' ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - - - - A collection with a fixed size does not allow the addition or removal of elements after the collection is created, but it allows the modification of existing elements. - + + + + A collection with a fixed size does not allow the addition or removal of elements after the collection is created, but it allows the modification of existing elements. + ]]> @@ -1455,9 +1455,9 @@ This member is an explicit interface member implementation. It can be used only ## Remarks -This property provides the ability to access a specific element in the collection by using the following syntax: `myCollection[index]`. - The C# language uses the [this](/dotnet/csharp/language-reference/keywords/this) keyword to define the indexers instead of implementing the property. Visual Basic implements as a default property, which provides the same indexing functionality. - +This property provides the ability to access a specific element in the collection by using the following syntax: `myCollection[index]`. + The C# language uses the [this](/dotnet/csharp/language-reference/keywords/this) keyword to define the indexers instead of implementing the property. Visual Basic implements as a default property, which provides the same indexing functionality. + ]]> diff --git a/xml/System.Text.RegularExpressions/Group.xml b/xml/System.Text.RegularExpressions/Group.xml index 18f5a4bb715..b8a52785338 100644 --- a/xml/System.Text.RegularExpressions/Group.xml +++ b/xml/System.Text.RegularExpressions/Group.xml @@ -62,27 +62,27 @@ Represents the results from a single capturing group. - property. Information about the last substring captured can be accessed directly from the `Value` and `Index` properties. (That is, the instance is equivalent to the last item of the collection returned by the property, which reflects the last capture made by the capturing group.) - - An example helps to clarify this relationship between a object and the that is returned by the property. The regular expression pattern `(\b(\w+?)[,:;]?\s?)+[?.!]` matches entire sentences. The regular expression is defined as shown in the following table. - -|Pattern|Description| -|-------------|-----------------| -|`\b`|Begin the match at a word boundary.| -|`(\w+?)`|Match one or more word characters, but as few characters as possible. This is the second (inner) capturing group. (The first capturing group includes the `\b` language element.)| -|`[,:;]?`|Match zero or one occurrence of a comma, colon, or semicolon.| -|`\s?`|Match zero or one occurrence of a white-space character.| -|`(\b(\w+?)[,:;]?\s?)+`|Match the pattern consisting of a word boundary, one or more word characters, a punctuation symbol, and a white-space character one or more times. This is the first capturing group.| -|`[?.!]`|Match any occurrence of a period, question mark, or exclamation point.| - - In this regular expression pattern, the subpattern `(\w+?)` is designed to match multiple words within a sentence. However, the value of the object represents only the last match that `(\w+?)` captures, whereas the property returns a that represents all captured text. As the output shows, the for the second capturing group contains four objects. The last of these corresponds to the object. - + property. Information about the last substring captured can be accessed directly from the `Value` and `Index` properties. (That is, the instance is equivalent to the last item of the collection returned by the property, which reflects the last capture made by the capturing group.) + + An example helps to clarify this relationship between a object and the that is returned by the property. The regular expression pattern `(\b(\w+?)[,:;]?\s?)+[?.!]` matches entire sentences. The regular expression is defined as shown in the following table. + +|Pattern|Description| +|-------------|-----------------| +|`\b`|Begin the match at a word boundary.| +|`(\w+?)`|Match one or more word characters, but as few characters as possible. This is the second (inner) capturing group. (The first capturing group includes the `\b` language element.)| +|`[,:;]?`|Match zero or one occurrence of a comma, colon, or semicolon.| +|`\s?`|Match zero or one occurrence of a white-space character.| +|`(\b(\w+?)[,:;]?\s?)+`|Match the pattern consisting of a word boundary, one or more word characters, a punctuation symbol, and a white-space character one or more times. This is the first capturing group.| +|`[?.!]`|Match any occurrence of a period, question mark, or exclamation point.| + + In this regular expression pattern, the subpattern `(\w+?)` is designed to match multiple words within a sentence. However, the value of the object represents only the last match that `(\w+?)` captures, whereas the property returns a that represents all captured text. As the output shows, the for the second capturing group contains four objects. The last of these corresponds to the object. + :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Group/Overview/groupandcaptures1.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.group.class/vb/groupandcaptures1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.group.class/vb/groupandcaptures1.vb" id="Snippet1"::: + ]]> @@ -129,19 +129,19 @@ Gets a collection of all the captures matched by the capturing group, in innermost-leftmost-first order (or innermost-rightmost-first order if the regular expression is modified with the option). The collection may have zero or more items. The collection of substrings matched by the group. - property contains a single object that provides information about the same substring as the object. This is illustrated in the following example. It defines a regular expression, `\b(\w+)\b`, that extracts a single word from a sentence. The object captures the word "This", and the single object in the contains information about the same capture. - + property contains a single object that provides information about the same substring as the object. This is illustrated in the following example. It defines a regular expression, `\b(\w+)\b`, that extracts a single word from a sentence. The object captures the word "This", and the single object in the contains information about the same capture. + :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Group/Captures/captures1.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.group.captures/vb/captures1.vb" id="Snippet1"::: - - The real utility of the property occurs when a quantifier is applied to a capturing group so that the group captures multiple substrings in a single regular expression. In this case, the object contains information about the last captured substring, whereas the property contains information about all the substrings captured by the group. In the following example, the regular expression `\b(\w+\s*)+\.` matches an entire sentence that ends in a period. The group `(\w+\s*)+` captures the individual words in the collection. Because the collection contains information only about the last captured substring, it captures the last word in the sentence, "sentence". However, each word captured by the group is available from the collection returned by the property. - + + The real utility of the property occurs when a quantifier is applied to a capturing group so that the group captures multiple substrings in a single regular expression. In this case, the object contains information about the last captured substring, whereas the property contains information about all the substrings captured by the group. In the following example, the regular expression `\b(\w+\s*)+\.` matches an entire sentence that ends in a period. The group `(\w+\s*)+` captures the individual words in the collection. Because the collection contains information only about the last captured substring, it captures the last word in the sentence, "sentence". However, each word captured by the group is available from the collection returned by the property. + :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Group/Captures/captures2.cs" interactive="try-dotnet" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.group.captures/vb/captures2.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.group.captures/vb/captures2.vb" id="Snippet2"::: + ]]> Grouping Constructs in Regular Expressions @@ -228,11 +228,11 @@ if the match is successful; otherwise, . - 0). - + 0). + ]]> @@ -272,7 +272,7 @@ System.Text.RegularExpressions.Group - + The input object. diff --git a/xml/System.Text.RegularExpressions/GroupCollection.xml b/xml/System.Text.RegularExpressions/GroupCollection.xml index ae9139c52e0..7c0c74a39c2 100644 --- a/xml/System.Text.RegularExpressions/GroupCollection.xml +++ b/xml/System.Text.RegularExpressions/GroupCollection.xml @@ -122,28 +122,28 @@ Returns the set of captured groups in a single match. The collection is immutable (read-only) and has no public constructor. - class is a zero-based collection class that consists of one or more objects that provide information about captured groups in a regular expression match. The collection is immutable (read-only) and has no public constructor. A object is returned by the property. - - The collection contains one or more objects. If the match is successful, the first element in the collection contains the object that corresponds to the entire match. Each subsequent element represents a captured group, if the regular expression includes capturing groups. Matches from numbered (unnamed) capturing groups appear in numeric order before matches from named capturing groups. If the match is unsuccessful, the collection contains a single object whose property is `false` and whose property equals . For more information, see the "Grouping Constructs and Regular Expression Objects" section in the [Grouping Constructs](/dotnet/standard/base-types/grouping-constructs-in-regular-expressions) article. - - To iterate through the members of the collection, you should use the collection iteration construct provided by your language (such as `foreach` in C# and `For Each`…`Next` in Visual Basic) instead of retrieving the enumerator that is returned by the method. In addition, you can access individual numbered captured groups from the property (the indexer in C#), and you can access individual named captured groups from the property. Note that you can retrieve an array that contains the numbers and names of all capturing groups by calling the and methods, respectively. Both are instance methods and require that you instantiate a object that represents the regular expression to be matched. - - - -## Examples - The following example uses a regular expression with capturing groups to extract information about trademarks and registered trademarks used in text. The regular expression pattern is `\b(\w+?)([\u00AE\u2122])`, which is interpreted as shown in the following table. - -|Pattern|Description| -|-------------|-----------------| -|`\b`|Look for a word boundary.| -|`(\w+?)`|Look for one or more word characters. Together, these form the trademarked name. (Note that this regular expression assumes that a trademark consists of a single word.) This is the first capturing group.| -|`([\u00AE\u2122])`|Look for either the ® or the ™ character. This is the second capturing group.| - - For each match, the contains three objects. The first object contains the string that matches the entire regular expression. The second object, which represents the first captured group, contains the product name. The third object, which represents the second captured group, contains the trademark or registered trademark symbol. - + class is a zero-based collection class that consists of one or more objects that provide information about captured groups in a regular expression match. The collection is immutable (read-only) and has no public constructor. A object is returned by the property. + + The collection contains one or more objects. If the match is successful, the first element in the collection contains the object that corresponds to the entire match. Each subsequent element represents a captured group, if the regular expression includes capturing groups. Matches from numbered (unnamed) capturing groups appear in numeric order before matches from named capturing groups. If the match is unsuccessful, the collection contains a single object whose property is `false` and whose property equals . For more information, see the "Grouping Constructs and Regular Expression Objects" section in the [Grouping Constructs](/dotnet/standard/base-types/grouping-constructs-in-regular-expressions) article. + + To iterate through the members of the collection, you should use the collection iteration construct provided by your language (such as `foreach` in C# and `For Each`…`Next` in Visual Basic) instead of retrieving the enumerator that is returned by the method. In addition, you can access individual numbered captured groups from the property (the indexer in C#), and you can access individual named captured groups from the property. Note that you can retrieve an array that contains the numbers and names of all capturing groups by calling the and methods, respectively. Both are instance methods and require that you instantiate a object that represents the regular expression to be matched. + + + +## Examples + The following example uses a regular expression with capturing groups to extract information about trademarks and registered trademarks used in text. The regular expression pattern is `\b(\w+?)([\u00AE\u2122])`, which is interpreted as shown in the following table. + +|Pattern|Description| +|-------------|-----------------| +|`\b`|Look for a word boundary.| +|`(\w+?)`|Look for one or more word characters. Together, these form the trademarked name. (Note that this regular expression assumes that a trademark consists of a single word.) This is the first capturing group.| +|`([\u00AE\u2122])`|Look for either the ® or the ™ character. This is the second capturing group.| + + For each match, the contains three objects. The first object contains the string that matches the entire regular expression. The second object, which represents the first captured group, contains the product name. The third object, which represents the second captured group, contains the trademark or registered trademark symbol. + :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/GroupCollection/Overview/Example1.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.RegularExpressions.GroupCollection/vb/Example1.vb" id="Snippet1"::: @@ -231,38 +231,38 @@ System.Void - - + + The array the collection is to be copied into. The position in the destination array where the copying is to begin. Copies all the elements of the collection to the given array beginning at the given index. - [!WARNING] -> This member is not present in the Portable Class Library. If you are developing applications that target the Portable Class Library, use the method instead. - - - -## Examples - The following example extracts each word from a sentence and captures it in a capturing group, The method is then used to copy the elements in each match's object to an array that contains the capturing groups from all matches. The individual captured words are then displayed to the console. - +> This member is not present in the Portable Class Library. If you are developing applications that target the Portable Class Library, use the method instead. + + + +## Examples + The following example extracts each word from a sentence and captures it in a capturing group, The method is then used to copy the elements in each match's object to an array that contains the capturing groups from all matches. The individual captured words are then displayed to the console. + :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/GroupCollection/CopyTo/copyto1.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.groupcollection.copyto/vb/copyto1.vb" id="Snippet1"::: - - The regular expression is defined as follows: - -|Pattern|Description| -|-------------|-----------------| -|`\b`|Match a word boundary.| -|`(\S+?)`|Match one or more non-white space characters. Assign them to the first capturing group.| -|`\b`|Match a word boundary.| - + + The regular expression is defined as follows: + +|Pattern|Description| +|-------------|-----------------| +|`\b`|Match a word boundary.| +|`(\S+?)`|Match one or more non-white space characters. Assign them to the first capturing group.| +|`\b`|Match a word boundary.| + ]]> @@ -374,11 +374,11 @@ Returns the number of groups in the collection. The number of groups in the collection. - object always has at least one member. If a match is unsuccessful, the property returns a object that contains a single member. - + object always has at least one member. If a match is unsuccessful, the property returns a object that contains a single member. + ]]> @@ -429,11 +429,11 @@ Provides an enumerator that iterates through the collection. An enumerator that contains all objects in the . - method to retrieve an enumerator that lets you iterate through the objects in the collection, you should use the group iteration construct (such as `foreach` in C# and `For Each`…`Next` in Visual Basic) that is provided by your programming language. - + method to retrieve an enumerator that lets you iterate through the objects in the collection, you should use the group iteration construct (such as `foreach` in C# and `For Each`…`Next` in Visual Basic) that is provided by your programming language. + ]]> @@ -533,13 +533,13 @@ A collection that is read-only does not allow the addition or removal of element in all cases. - [!WARNING] -> This member is not present in the Portable Class Library. If you are developing applications that target the Portable Class Library, use the property instead. - +> This member is not present in the Portable Class Library. If you are developing applications that target the Portable Class Library, use the property instead. + ]]> @@ -613,33 +613,33 @@ A collection that is read-only does not allow the addition or removal of element Enables access to a member of the collection by integer index. The member of the collection specified by . - property is the index (in C#) or the default property (in Visual Basic) of the class. It allows you to enumerate the members of the collection by using a `foreach` statement in C# or a `For Each` statement in Visual Basic. - - You can also use this property to retrieve individual captured groups by their index number. You can retrieve an array that contains the numbers of all capturing groups in a regular expression by calling the instance method. You can also map named capturing groups to their numbers by calling the instance method. - - You can determine the number of items in the collection by retrieving the value of the property. Valid values for the `groupnum` parameter range from 0 to one less than the number of items in the collection. - - The object returned by the property always has at least one member. If the regular expression engine cannot find any matches in a particular input string, the single object in the collection has its property set to `false` and its `Group.Value` property set to . - - If `groupnum` is not the index of a member of the collection, or if `groupnum` is the index of a capturing group that has not been matched in the input string, the method returns a object whose property is `false` and whose `Group.Value` property is . - - - -## Examples - The following example defines a regular expression that consists of two numbered groups. The first group captures one or more consecutive digits. The second group matches a single character. Because the regular expression engine looks for zero or one occurrence of the first group, it does not always find a match even if the regular expression match is successful. The example then illustrates the result when the property is used to retrieve an unmatched group, a matched group, and a group that is not defined in the regular expression. The example defines a regular expression pattern `(\d+)*(\w)\2`, which is interpreted as shown in the following table. - -|Pattern|Description| -|-------------|-----------------| -|`(\d+)*`|Match one or more occurrence of a decimal digit. This is the first capturing group. Match this pattern either zero or one time.| -|`(\w)`|This is the second capturing group.| -|`\k`|Match the string captured by the second capturing group.| - + property is the index (in C#) or the default property (in Visual Basic) of the class. It allows you to enumerate the members of the collection by using a `foreach` statement in C# or a `For Each` statement in Visual Basic. + + You can also use this property to retrieve individual captured groups by their index number. You can retrieve an array that contains the numbers of all capturing groups in a regular expression by calling the instance method. You can also map named capturing groups to their numbers by calling the instance method. + + You can determine the number of items in the collection by retrieving the value of the property. Valid values for the `groupnum` parameter range from 0 to one less than the number of items in the collection. + + The object returned by the property always has at least one member. If the regular expression engine cannot find any matches in a particular input string, the single object in the collection has its property set to `false` and its `Group.Value` property set to . + + If `groupnum` is not the index of a member of the collection, or if `groupnum` is the index of a capturing group that has not been matched in the input string, the method returns a object whose property is `false` and whose `Group.Value` property is . + + + +## Examples + The following example defines a regular expression that consists of two numbered groups. The first group captures one or more consecutive digits. The second group matches a single character. Because the regular expression engine looks for zero or one occurrence of the first group, it does not always find a match even if the regular expression match is successful. The example then illustrates the result when the property is used to retrieve an unmatched group, a matched group, and a group that is not defined in the regular expression. The example defines a regular expression pattern `(\d+)*(\w)\2`, which is interpreted as shown in the following table. + +|Pattern|Description| +|-------------|-----------------| +|`(\d+)*`|Match one or more occurrence of a decimal digit. This is the first capturing group. Match this pattern either zero or one time.| +|`(\w)`|This is the second capturing group.| +|`\k`|Match the string captured by the second capturing group.| + :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/GroupCollection/Item/item3.cs" interactive="try-dotnet" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.groupcollection.item/vb/item3.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.groupcollection.item/vb/item3.vb" id="Snippet2"::: + ]]> Grouping Constructs in Regular Expressions @@ -694,29 +694,29 @@ A collection that is read-only does not allow the addition or removal of element Enables access to a member of the collection by string index. The member of the collection specified by . - )` element in a regular expression, or the string representation of the number of a capturing group that is defined by a grouping construct. For more information about groups in regular expressions, see [Grouping Constructs](/dotnet/standard/base-types/grouping-constructs-in-regular-expressions). - - You can retrieve the names of all the captured groups in a object by calling the method. You can also map the numbers of capturing groups in a regular expression to their names by calling the method. Individual names from the array can then be passed to the property to retrieve the captured string. - - If `groupname` is not the name of a capturing group in the collection, or if `groupname` is the name of a capturing group that has not been matched in the input string, the method returns a object whose property is `false` and whose `Group.Value` property is . - - - -## Examples - The following example defines a regular expression that consists of two named groups. The first group, `numbers`, captures one or more consecutive digits. The second group, `letter`, matches a single character. Because the regular expression engine looks for zero or one occurrence of the pattern defined by the `numbers` group, the `numbers` group is not always present even if a match is successful. The example then illustrates the result when the property is used to retrieve an unmatched group, a matched group, and a group that is not defined in the regular expression. The example defines a regular expression pattern `(?\d+)*(?\w)\k`, which is interpreted as shown in the following table. - -|Pattern|Description| -|-------------|-----------------| -|`(?\d+)*`|Match one or more occurrence of a decimal digit. Name this the `numbers` capturing group. Match this pattern either zero or one time.| -|`(?\w)`|Match a single word character. Name this the `letter` capturing group.| -|`\k`|Match the string captured by the `letter` capturing group.| - + )` element in a regular expression, or the string representation of the number of a capturing group that is defined by a grouping construct. For more information about groups in regular expressions, see [Grouping Constructs](/dotnet/standard/base-types/grouping-constructs-in-regular-expressions). + + You can retrieve the names of all the captured groups in a object by calling the method. You can also map the numbers of capturing groups in a regular expression to their names by calling the method. Individual names from the array can then be passed to the property to retrieve the captured string. + + If `groupname` is not the name of a capturing group in the collection, or if `groupname` is the name of a capturing group that has not been matched in the input string, the method returns a object whose property is `false` and whose `Group.Value` property is . + + + +## Examples + The following example defines a regular expression that consists of two named groups. The first group, `numbers`, captures one or more consecutive digits. The second group, `letter`, matches a single character. Because the regular expression engine looks for zero or one occurrence of the pattern defined by the `numbers` group, the `numbers` group is not always present even if a match is successful. The example then illustrates the result when the property is used to retrieve an unmatched group, a matched group, and a group that is not defined in the regular expression. The example defines a regular expression pattern `(?\d+)*(?\w)\k`, which is interpreted as shown in the following table. + +|Pattern|Description| +|-------------|-----------------| +|`(?\d+)*`|Match one or more occurrence of a decimal digit. Name this the `numbers` capturing group. Match this pattern either zero or one time.| +|`(?\w)`|Match a single word character. Name this the `letter` capturing group.| +|`\k`|Match the string captured by the `letter` capturing group.| + :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/GroupCollection/Item/item2.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.groupcollection.item/vb/item2.vb" id="Snippet1"::: - + ]]> Grouping Constructs in Regular Expressions @@ -813,13 +813,13 @@ The order of the keys in the enumerable collection is unspecified, but the imple Gets an object that can be used to synchronize access to the . A copy of the object to synchronize. - [!WARNING] -> This member is not present in the Portable Class Library. If you are developing applications that target the Portable Class Library, use the property instead. - +> This member is not present in the Portable Class Library. If you are developing applications that target the Portable Class Library, use the property instead. + ]]> @@ -947,11 +947,11 @@ The order of the keys in the enumerable collection is unspecified, but the imple if the group item is found in the group collection; otherwise. - 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. ]]> @@ -1132,7 +1132,7 @@ Instead of calling this method to retrieve an enumerator that lets you iterate t Determines the index of a specific group in the group collection. The index of the if found; otherwise, -1. - Gets the group at the specified position in the collection. The group in the desired position. - The zero-based index in the destination array where copying is to begin. Copies all the elements of the collection to the specified array beginning at the specified index. - 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. ]]> @@ -1366,7 +1366,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. - + ]]> @@ -1407,7 +1407,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. - + ]]> @@ -1543,11 +1543,11 @@ This member is an explicit interface member implementation. It can be used only if the group item is found in the group collection; otherwise. - 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. ]]> @@ -1593,11 +1593,11 @@ This member is an explicit interface member implementation. It can be used only Determines the index of a specific group in the group collection. The index of the if found; otherwise, -1. - 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. ]]> @@ -1684,11 +1684,11 @@ This member is an explicit interface member implementation. It can be used only always. - 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. ]]> @@ -1741,11 +1741,11 @@ This member is an explicit interface member implementation. It can be used only Gets the group in the desired position. The group in the desired position. - 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. ]]> @@ -1922,11 +1922,11 @@ This member is an explicit interface member implementation. It can be used only Gets a group enumeration with all the groups in the group collection. A group enumeration. - 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.Text.RegularExpressions/Match.xml b/xml/System.Text.RegularExpressions/Match.xml index 90f6a8de859..7c5c3877fd4 100644 --- a/xml/System.Text.RegularExpressions/Match.xml +++ b/xml/System.Text.RegularExpressions/Match.xml @@ -62,49 +62,49 @@ Represents the results from a single regular expression match. - object is immutable and has no public constructor. An instance of the class is returned by the method and represents the first pattern match in a string. Subsequent matches are represented by objects returned by the method. In addition, a object that consists of zero, one, or more objects is returned by the method. - - If the method fails to match a regular expression pattern in an input string, it returns an empty object. You can then use a `foreach` construct in C# or a `For Each` construct in Visual Basic to iterate the collection. - - If the method fails to match the regular expression pattern, it returns a object that is equal to . You can use the property to determine whether the match was successful. The following example provides an illustration. - + object is immutable and has no public constructor. An instance of the class is returned by the method and represents the first pattern match in a string. Subsequent matches are represented by objects returned by the method. In addition, a object that consists of zero, one, or more objects is returned by the method. + + If the method fails to match a regular expression pattern in an input string, it returns an empty object. You can then use a `foreach` construct in C# or a `For Each` construct in Visual Basic to iterate the collection. + + If the method fails to match the regular expression pattern, it returns a object that is equal to . You can use the property to determine whether the match was successful. The following example provides an illustration. + :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Match/Overview/Match1.cs" interactive="try-dotnet-method" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.RegularExpressions.Match.Class/vb/Match1.vb" id="Snippet1"::: - - If a pattern match is successful, the property contains the matched substring, the property indicates the zero-based starting position of the matched substring in the input string, and the property indicates the length of matched substring in the input string. - - Because a single match can involve multiple capturing groups, has a property that returns the . The instance itself is equivalent to the first object in the collection, at `Match.Groups[0]` (`Match.Groups(0)` in Visual Basic), which represents the entire match. You can access the captured groups in a match in the following ways: - -- You can iterate the members of the object by using a `foreach` (C#) or `For Each` (Visual Basic) construct. - -- You can use the property to retrieve groups by the number of the capturing group. Note that you can determine which numbered groups are present in a regular expression by calling the instance method. - -- You can use the property to retrieve groups by the name of the capturing group. Note that you can determine which named groups are present in a regular expression by calling the instance method. - - - -## Examples - The following examples use the regular expression `Console\.Write(Line)?`. The regular expression is interpreted as follows: - -||| -|-|-| -|Console\\.Write|Match the string "Console.Write". Note that the "." character is escaped so that it is interpreted as a literal period rather than as a wildcard that matches any character.| -|(Line)?|Match zero or one occurrence of the string "Line".| - - **Example 1** - - The following example calls the method to retrieve all pattern matches in an input string. It then iterates the objects in the returned object to display information about each match. - + + If a pattern match is successful, the property contains the matched substring, the property indicates the zero-based starting position of the matched substring in the input string, and the property indicates the length of matched substring in the input string. + + Because a single match can involve multiple capturing groups, has a property that returns the . The instance itself is equivalent to the first object in the collection, at `Match.Groups[0]` (`Match.Groups(0)` in Visual Basic), which represents the entire match. You can access the captured groups in a match in the following ways: + +- You can iterate the members of the object by using a `foreach` (C#) or `For Each` (Visual Basic) construct. + +- You can use the property to retrieve groups by the number of the capturing group. Note that you can determine which numbered groups are present in a regular expression by calling the instance method. + +- You can use the property to retrieve groups by the name of the capturing group. Note that you can determine which named groups are present in a regular expression by calling the instance method. + + + +## Examples + The following examples use the regular expression `Console\.Write(Line)?`. The regular expression is interpreted as follows: + +||| +|-|-| +|Console\\.Write|Match the string "Console.Write". Note that the "." character is escaped so that it is interpreted as a literal period rather than as a wildcard that matches any character.| +|(Line)?|Match zero or one occurrence of the string "Line".| + + **Example 1** + + The following example calls the method to retrieve all pattern matches in an input string. It then iterates the objects in the returned object to display information about each match. + :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Match/Overview/Match2.cs" interactive="try-dotnet" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.RegularExpressions.Match.Class/vb/Match2.vb" id="Snippet2"::: - **Example 2** - - The following example calls the and methods to retrieve one match at a time. - + **Example 2** + + The following example calls the and methods to retrieve one match at a time. + :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Match/Overview/Match3.cs" interactive="try-dotnet" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.RegularExpressions.Match.Class/vb/Match3.vb" id="Snippet3"::: @@ -162,11 +162,11 @@ Gets the empty group. All failed matches return this empty match. An empty match. - ). - + ). + ]]> @@ -213,25 +213,25 @@ Gets a collection of groups matched by the regular expression. The character groups matched by the pattern. - property provides access to information about those subexpression matches. For example, the regular expression pattern `(\d{3})-(\d{3}-\d{4})`, which matches North American telephone numbers, has two subexpressions. The first consists of the area code, which composes the first three digits of the telephone number. This group is captured by the first portion of the regular expression, `(\d{3})`. The second consists of the individual telephone number, which composes the last seven digits of the telephone number. This group is captured by the second portion of the regular expression, `(\d{3}-\d{4})`. These two groups can then be retrieved from the object that is returned by the property, as the following example shows. - + property provides access to information about those subexpression matches. For example, the regular expression pattern `(\d{3})-(\d{3}-\d{4})`, which matches North American telephone numbers, has two subexpressions. The first consists of the area code, which composes the first three digits of the telephone number. This group is captured by the first portion of the regular expression, `(\d{3})`. The second consists of the individual telephone number, which composes the last seven digits of the telephone number. This group is captured by the second portion of the regular expression, `(\d{3}-\d{4})`. These two groups can then be retrieved from the object that is returned by the property, as the following example shows. + :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Match/Groups/groups1.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.match.groups/vb/groups1.vb" id="Snippet1"::: - - The object returned by the property is a zero-based collection object that always has at least one member. If the regular expression engine cannot find any matches in a particular input string, the property of the single object in the collection (the object at index 0) is set to `false` and the object's property is set to . If the regular expression engine can find a match, the first element of the object (the element at index 0) returned by the property contains a string that matches the entire regular expression pattern. Each subsequent element, from index one upward, represents a captured group, if the regular expression includes capturing groups. For more information, see the "Grouping Constructs and Regular Expression Objects" section of the [Grouping Constructs](/dotnet/standard/base-types/grouping-constructs-in-regular-expressions) article. - - - -## Examples - The following example attempts to match a regular expression pattern against a sample string. The example uses the property to store information that is retrieved by the match for display to the console. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.match.groups/vb/groups1.vb" id="Snippet1"::: + + The object returned by the property is a zero-based collection object that always has at least one member. If the regular expression engine cannot find any matches in a particular input string, the property of the single object in the collection (the object at index 0) is set to `false` and the object's property is set to . If the regular expression engine can find a match, the first element of the object (the element at index 0) returned by the property contains a string that matches the entire regular expression pattern. Each subsequent element, from index one upward, represents a captured group, if the regular expression includes capturing groups. For more information, see the "Grouping Constructs and Regular Expression Objects" section of the [Grouping Constructs](/dotnet/standard/base-types/grouping-constructs-in-regular-expressions) article. + + + +## Examples + The following example attempts to match a regular expression pattern against a sample string. The example uses the property to store information that is retrieved by the match for display to the console. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/regex match, nextmatch, groups, captures/cpp/snippet8.cpp" id="Snippet8"::: :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Match/Groups/snippet8.cs" interactive="try-dotnet" id="Snippet8"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/regex match, nextmatch, groups, captures/vb/snippet8.vb" id="Snippet8"::: - + ]]> @@ -279,33 +279,33 @@ Returns a new object with the results for the next match, starting at the position at which the last match ended (at the character after the last matched character). The next regular expression match. - again and passing (`Index+Length`) as the new starting position. - + again and passing (`Index+Length`) as the new starting position. + > [!NOTE] -> This method does not modify the current instance. Instead, it returns a new object that contains information about the next match. - - Attempting to retrieve the next match may throw a if a time-out value for matching operations is in effect and the attempt to find the next match exceeds that time-out interval. - - - -## Examples - The following example uses the method to capture regular expression matches beyond the first match. +> This method does not modify the current instance. Instead, it returns a new object that contains information about the next match. + + Attempting to retrieve the next match may throw a if a time-out value for matching operations is in effect and the attempt to find the next match exceeds that time-out interval. + + + +## Examples + The following example uses the method to capture regular expression matches beyond the first match. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/regex match, nextmatch, groups, captures/cpp/snippet8.cpp" id="Snippet8"::: :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Match/Groups/snippet8.cs" interactive="try-dotnet" id="Snippet8"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/regex match, nextmatch, groups, captures/vb/snippet8.vb" id="Snippet8"::: - + ]]> A time-out occurred. - When a match attempt is repeated by calling the method, the regular expression engine gives empty matches special treatment. Usually, begins the search for the next match exactly where the previous match left off. However, after an empty match, the method advances by one character before trying the next match. This behavior guarantees that the regular expression engine will progress through the string. Otherwise, because an empty match does not result in any forward movement, the next match would start in exactly the same place as the previous match, and it would match the same empty string repeatedly. - - The following example provides an illustration. The regular expression pattern a* searches for zero or more occurrences of the letter "a" in the string "abaabb". As the output from the example shows, the search finds six matches. The first match attempt finds the first "a". The second match starts exactly where the first match ends, before the first b; it finds zero occurrences of "a" and returns an empty string. The third match does not begin exactly where the second match ended, because the second match returned an empty string. Instead, it begins one character later, after the first "b". The third match finds two occurrences of "a" and returns "aa". The fourth match attempt begins where the third match ended, before the second "b", and returns an empty string. The fifth match attempt again advances one character so that it begins before the third "b" and returns an empty string. The sixth match begins after the last "b" and returns an empty string again. - + When a match attempt is repeated by calling the method, the regular expression engine gives empty matches special treatment. Usually, begins the search for the next match exactly where the previous match left off. However, after an empty match, the method advances by one character before trying the next match. This behavior guarantees that the regular expression engine will progress through the string. Otherwise, because an empty match does not result in any forward movement, the next match would start in exactly the same place as the previous match, and it would match the same empty string repeatedly. + + The following example provides an illustration. The regular expression pattern a* searches for zero or more occurrences of the letter "a" in the string "abaabb". As the output from the example shows, the search finds six matches. The first match attempt finds the first "a". The second match starts exactly where the first match ends, before the first b; it finds zero occurrences of "a" and returns an empty string. The third match does not begin exactly where the second match ended, because the second match returned an empty string. Instead, it begins one character later, after the first "b". The third match finds two occurrences of "a" and returns "aa". The fourth match attempt begins where the third match ended, before the second "b", and returns an empty string. The fifth match attempt again advances one character so that it begins before the third "b" and returns an empty string. The sixth match begins after the last "b" and returns an empty string again. + :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Match/NextMatch/nextmatch1.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.match.nextmatch/vb/nextmatch1.vb" id="Snippet1"::: @@ -357,33 +357,33 @@ Returns the expansion of the specified replacement pattern. The expanded version of the parameter. - method replaces all matches in an input string with a specified replacement pattern, the method replaces a single match with a specified replacement pattern. Because it operates on an individual match, it is also possible to perform processing on the matched string before you call the method. - - The `replacement` parameter is a standard regular expression replacement pattern. It can consist of literal characters and regular expression substitutions. For more information, see [Substitutions](/dotnet/standard/base-types/substitutions-in-regular-expressions). - - - -## Examples - The following example replaces the hyphens that begin and end a parenthetical expression with parentheses. + method replaces all matches in an input string with a specified replacement pattern, the method replaces a single match with a specified replacement pattern. Because it operates on an individual match, it is also possible to perform processing on the matched string before you call the method. + + The `replacement` parameter is a standard regular expression replacement pattern. It can consist of literal characters and regular expression substitutions. For more information, see [Substitutions](/dotnet/standard/base-types/substitutions-in-regular-expressions). + + + +## Examples + The following example replaces the hyphens that begin and end a parenthetical expression with parentheses. :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Match/Result/result1.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.match.result/vb/result1.vb" id="Snippet1"::: - - The regular expression pattern `--(.+?)--` is interpreted as shown in the following table. - -|Pattern|Description| -|-------------|-----------------| -|`--`|Match two hyphens.| -|`(.+?)`|Match any character one or more times, but as few times as possible. This is the first capturing group.| -|`--`|Match two hyphens.| - - Note that the regular expression pattern `--(.+?)--` uses the lazy quantifier `+?`. If the greedy quantifier `+` were used instead, the regular expression engine would find only a single match in the input string. - - The replacement string `($1)` replaces the match with the first captured group, which is enclosed in parentheses. - + + The regular expression pattern `--(.+?)--` is interpreted as shown in the following table. + +|Pattern|Description| +|-------------|-----------------| +|`--`|Match two hyphens.| +|`(.+?)`|Match any character one or more times, but as few times as possible. This is the first capturing group.| +|`--`|Match two hyphens.| + + Note that the regular expression pattern `--(.+?)--` uses the lazy quantifier `+?`. If the greedy quantifier `+` were used instead, the regular expression engine would find only a single match in the input string. + + The replacement string `($1)` replaces the match with the first captured group, which is enclosed in parentheses. + ]]> @@ -428,7 +428,7 @@ System.Text.RegularExpressions.Match - + A regular expression match equivalent to the one expected. diff --git a/xml/System.Text.RegularExpressions/MatchCollection.xml b/xml/System.Text.RegularExpressions/MatchCollection.xml index fea2f2bc709..23564093e09 100644 --- a/xml/System.Text.RegularExpressions/MatchCollection.xml +++ b/xml/System.Text.RegularExpressions/MatchCollection.xml @@ -102,30 +102,30 @@ Represents the set of successful matches found by iteratively applying a regular expression pattern to the input string. The collection is immutable (read-only) and has no public constructor. The method returns a object. - method returns a object. - - The collection contains zero or more objects. If the match is successful, the collection is populated with one object for each match found in the input string. If the match is unsuccessful, the collection contains no objects, and its property equals zero. - - When applying a regular expression pattern to a particular input string, the regular expression engine uses either of two techniques to build the object: - -- Direct evaluation. - - The object is populated all at once, with all matches resulting from a particular call to the method. This technique is used when the collection's property is accessed. It typically is the more expensive method of populating the collection and entails a greater performance hit. - -- Lazy evaluation. - - The object is populated as needed on a match-by-match basis. It is equivalent to the regular expression engine calling the method repeatedly and adding each match to the collection. This technique is used when the collection is accessed through its method, or when it is accessed using the `foreach` statement (in C#) or the `For Each`...`Next` statement (in Visual Basic). - - To iterate through the members of the collection, you should use the collection iteration construct provided by your language (such as `foreach` in C# and `For Each`…`Next` in Visual Basic) instead of retrieving the enumerator that is returned by the method. - - - -## Examples - The following example illustrates the use of the class to interrogate a set of instances. - + method returns a object. + + The collection contains zero or more objects. If the match is successful, the collection is populated with one object for each match found in the input string. If the match is unsuccessful, the collection contains no objects, and its property equals zero. + + When applying a regular expression pattern to a particular input string, the regular expression engine uses either of two techniques to build the object: + +- Direct evaluation. + + The object is populated all at once, with all matches resulting from a particular call to the method. This technique is used when the collection's property is accessed. It typically is the more expensive method of populating the collection and entails a greater performance hit. + +- Lazy evaluation. + + The object is populated as needed on a match-by-match basis. It is equivalent to the regular expression engine calling the method repeatedly and adding each match to the collection. This technique is used when the collection is accessed through its method, or when it is accessed using the `foreach` statement (in C#) or the `For Each`...`Next` statement (in Visual Basic). + + To iterate through the members of the collection, you should use the collection iteration construct provided by your language (such as `foreach` in C# and `For Each`…`Next` in Visual Basic) instead of retrieving the enumerator that is returned by the method. + + + +## Examples + The following example illustrates the use of the class to interrogate a set of instances. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Regex_Words/CPP/words.cpp" id="Snippet0"::: :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/MatchCollection/Overview/words.cs" interactive="try-dotnet" id="Snippet0"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Regex_Words/VB/words.vb" id="Snippet0"::: @@ -172,33 +172,33 @@ System.Void - - + + The array the collection is to be copied into. The position in the array where copying is to begin. Copies all the elements of the collection to the given array starting at the given index. - [!WARNING] -> This member is not present in the Portable Class Library. If you are developing applications that target the Portable Class Library, use the method instead. - - Because the object is generally populated by using lazy evaluation, trying to copy the collection before it has been fully populated may throw a exception. This exception can be thrown if a time-out value for matching operations is in effect, and the attempt to find a single match exceeds that time-out interval. - +> This member is not present in the Portable Class Library. If you are developing applications that target the Portable Class Library, use the method instead. + + Because the object is generally populated by using lazy evaluation, trying to copy the collection before it has been fully populated may throw a exception. This exception can be thrown if a time-out value for matching operations is in effect, and the attempt to find a single match exceeds that time-out interval. + ]]> is a multi-dimensional array. - is outside the bounds of . - - -or- - + is outside the bounds of . + + -or- + plus is outside the bounds of . A time-out occurred. @@ -293,23 +293,23 @@ Gets the number of matches. The number of matches. - object by retrieving the value of the collection's property causes the regular expression engine to populate the collection using direct evaluation. ln contrast, calling the method (or using the `foreach` statement in C# and the `For Each`...`Next` statement in Visual Basic) causes the regular expression engine to populate the collection on an as needed basis using lazy evaluation. Direct evaluation can be a much more expensive method of building the collection than lazy evaluation. - - Because the object is generally populated by using lazy evaluation, trying to determine the number of elements in the collection before it has been fully populated may throw a exception. This exception can be thrown if a time-out value for matching operations is in effect, and the attempt to find a single match exceeds that time-out interval. - - - -## Examples - The following example uses the property to determine whether the call to the method found any matches. If not, it indicates that no matches were found. Otherwise, it enumerates the matches and displays their value and the position in the input string at which they were found. - + object by retrieving the value of the collection's property causes the regular expression engine to populate the collection using direct evaluation. ln contrast, calling the method (or using the `foreach` statement in C# and the `For Each`...`Next` statement in Visual Basic) causes the regular expression engine to populate the collection on an as needed basis using lazy evaluation. Direct evaluation can be a much more expensive method of building the collection than lazy evaluation. + + Because the object is generally populated by using lazy evaluation, trying to determine the number of elements in the collection before it has been fully populated may throw a exception. This exception can be thrown if a time-out value for matching operations is in effect, and the attempt to find a single match exceeds that time-out interval. + + + +## Examples + The following example uses the property to determine whether the call to the method found any matches. If not, it indicates that no matches were found. Otherwise, it enumerates the matches and displays their value and the position in the input string at which they were found. + :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/MatchCollection/Count/countex1.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.matchcollection.count/vb/countex1.vb" id="Snippet1"::: - - The regular expression pattern `\d+` matches one or more decimal characters in an input string. - + + The regular expression pattern `\d+` matches one or more decimal characters in an input string. + ]]> A time-out occurred. @@ -361,15 +361,15 @@ Provides an enumerator that iterates through the collection. An object that contains all objects within the . - method to retrieve an enumerator that lets you iterate through the objects in the collection, you should use the group iteration construct (such as `foreach` in C# and `For Each`…`Next` in Visual Basic) provided by your programming language. - - Iterating the members of the object using the method (or the `foreach` statement in C# and the `For Each`...`Next` statement in Visual Basic) causes the regular expression engine to populate the collection on an as needed basis using lazy evaluation. This is analogous to repeatedly calling the method, and then adding the resulting match to the object. In contrast, the regular expression engine uses direct evaluation to populate the collection all at once when the property is accessed. This can be a much more expensive method of building the collection than lazy evaluation. - - Because the object is generally populated by using lazy evaluation, trying to navigate to the next member of the collection may throw a exception. This exception can be thrown if a time-out value for matching operations is in effect, and the attempt to find the next match exceeds that time-out interval. - + method to retrieve an enumerator that lets you iterate through the objects in the collection, you should use the group iteration construct (such as `foreach` in C# and `For Each`…`Next` in Visual Basic) provided by your programming language. + + Iterating the members of the object using the method (or the `foreach` statement in C# and the `For Each`...`Next` statement in Visual Basic) causes the regular expression engine to populate the collection on an as needed basis using lazy evaluation. This is analogous to repeatedly calling the method, and then adding the resulting match to the object. In contrast, the regular expression engine uses direct evaluation to populate the collection all at once when the property is accessed. This can be a much more expensive method of building the collection than lazy evaluation. + + Because the object is generally populated by using lazy evaluation, trying to navigate to the next member of the collection may throw a exception. This exception can be thrown if a time-out value for matching operations is in effect, and the attempt to find the next match exceeds that time-out interval. + ]]> A time-out occurred. @@ -470,13 +470,13 @@ A collection that is read-only does not allow the addition or removal of element in all cases. - [!WARNING] -> This member is not present in the Portable Class Library. If you are developing applications that target the Portable Class Library, use the property instead. - +> This member is not present in the Portable Class Library. If you are developing applications that target the Portable Class Library, use the property instead. + ]]> @@ -531,31 +531,31 @@ A collection that is read-only does not allow the addition or removal of element Gets an individual member of the collection. The captured substring at position in the collection. - property is an indexer; it is not explicitly referenced in code, but instead allows the collection to be accessed as if it were an array. - - Typically, individual items in the object are accessed by their index only after the total number of items in the collection has been determined from the property. However, accessing the property causes the regular expression engine to use direct evaluation to build the collection all at once. This is typically more expensive than iterating the collection using the method, the C# `foreach` statement, or the Visual Basic `For Each`...`Next` statement. - - Because the object is generally populated by using lazy evaluation, trying to navigate to a specific match may throw a exception. This exception can be thrown if a time-out value for matching operations is in effect, and the attempt to find a specific match exceeds that time-out interval. - - - -## Examples - The following example parses the first sentence of Nathaniel Hawthorne's *House of the Seven Gables* and returns a object that contains all words that begin with either an uppercase or lowercase "h". The property is then used to retrieve each word and display it to the console. + property is an indexer; it is not explicitly referenced in code, but instead allows the collection to be accessed as if it were an array. + + Typically, individual items in the object are accessed by their index only after the total number of items in the collection has been determined from the property. However, accessing the property causes the regular expression engine to use direct evaluation to build the collection all at once. This is typically more expensive than iterating the collection using the method, the C# `foreach` statement, or the Visual Basic `For Each`...`Next` statement. + + Because the object is generally populated by using lazy evaluation, trying to navigate to a specific match may throw a exception. This exception can be thrown if a time-out value for matching operations is in effect, and the attempt to find a specific match exceeds that time-out interval. + + + +## Examples + The following example parses the first sentence of Nathaniel Hawthorne's *House of the Seven Gables* and returns a object that contains all words that begin with either an uppercase or lowercase "h". The property is then used to retrieve each word and display it to the console. :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/MatchCollection/Item/RegEx_24804.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.RegularExpressions.MatchCollection.Item/vb/RegEx_24804.vb" id="Snippet1"::: - - The example produces the following output: - -``` -Half -house -huge -``` - + + The example produces the following output: + +``` +Half +house +huge +``` + ]]> @@ -605,13 +605,13 @@ huge Gets an object that can be used to synchronize access to the collection. An object that can be used to synchronize access to the collection. This property always returns the object itself. - [!WARNING] -> This member is not present in the Portable Class Library. If you are developing applications that target the Portable Class Library, use the property instead. - +> This member is not present in the Portable Class Library. If you are developing applications that target the Portable Class Library, use the property instead. + ]]> @@ -834,13 +834,13 @@ huge ## Remarks -The returned provides the ability to iterate through the collection by exposing a property .You can use enumerators to read the data in a collection, but not to modify the collection. - Initially, the enumerator is positioned before the first element in the collection. At this position, 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 is called again as 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. You cannot set to the first element of the collection again; you must create a new enumerator instance instead. If changes are made to the collection, such as adding, modifying, or deleting elements, the behavior of the enumerator is undefined. - An enumerator does not have exclusive access to the collection so 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 invalidated and you may get unexpected results. Also, enumerating a collection is not a thread-safe procedure. To guarantee thread-safety, you should lock the collection during enumerator or implement synchronization on the collection. - Default implementations of collections in the namespace aren't synchronized. - +The returned provides the ability to iterate through the collection by exposing a property .You can use enumerators to read the data in a collection, but not to modify the collection. + Initially, the enumerator is positioned before the first element in the collection. At this position, 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 is called again as 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. You cannot set to the first element of the collection again; you must create a new enumerator instance instead. If changes are made to the collection, such as adding, modifying, or deleting elements, the behavior of the enumerator is undefined. + An enumerator does not have exclusive access to the collection so 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 invalidated and you may get unexpected results. Also, enumerating a collection is not a thread-safe procedure. To guarantee thread-safety, you should lock the collection during enumerator or implement synchronization on the collection. + Default implementations of collections in the namespace aren't synchronized. + ]]> The collection is read-only. @@ -984,7 +984,7 @@ If an object occurs multiple times in the list, the property. Visual Basic implements as a [default property](/dotnet/visual-basic/language-reference/modifiers/default), which provides the same indexing functionality. ]]> @@ -1111,7 +1111,7 @@ This property provides the ability to access a specific element in the collectio ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - + ]]> @@ -1152,7 +1152,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. - + ]]> @@ -1241,11 +1241,11 @@ 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. - - - - 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. + ]]> The collection is read-only. @@ -1296,8 +1296,8 @@ This member is an explicit interface member implementation. It can be used only ## Remarks -Starting with the .NET Framework 2.0, this method uses the collection's objects' and methods on `item` to determine whether item exists. In earlier versions of the .NET Framework, this determination was made by using the and methods of the `item` parameter on the objects in the collection. - +Starting with the .NET Framework 2.0, this method uses the collection's objects' and methods on `item` to determine whether item exists. In earlier versions of the .NET Framework, this determination was made by using the and methods of the `item` parameter on the objects in the collection. + ]]> @@ -1346,8 +1346,8 @@ Starting with the .NET Framework 2.0, this method uses the collection's objects' ## Remarks -Starting with the .NET Framework 2.0, this method uses the collection's objects' and methods on `item` to determine whether item exists. In earlier versions of the .NET Framework, this determination was made by using the and methods of the `item` parameter on the objects in the collection. - +Starting with the .NET Framework 2.0, this method uses the collection's objects' and methods on `item` to determine whether item exists. In earlier versions of the .NET Framework, this determination was made by using the and methods of the `item` parameter on the objects in the collection. + ]]> @@ -1438,11 +1438,11 @@ Starting with the .NET Framework 2.0, this method uses the collection's objects' ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - - - - A collection with a fixed size does not allow the addition or removal of elements after the collection is created, but it allows the modification of existing elements. - + + + + A collection with a fixed size does not allow the addition or removal of elements after the collection is created, but it allows the modification of existing elements. + ]]> @@ -1498,9 +1498,9 @@ This member is an explicit interface member implementation. It can be used only ## Remarks -This property provides the ability to access a specific element in the collection by using the following syntax: `myCollection[index]`. - The C# language uses the [this](/dotnet/csharp/language-reference/keywords/this) keyword to define the indexers instead of implementing the property. Visual Basic implements as a default property, which provides the same indexing functionality. - +This property provides the ability to access a specific element in the collection by using the following syntax: `myCollection[index]`. + The C# language uses the [this](/dotnet/csharp/language-reference/keywords/this) keyword to define the indexers instead of implementing the property. Visual Basic implements as a default property, which provides the same indexing functionality. + ]]> diff --git a/xml/System.Text.RegularExpressions/Regex.xml b/xml/System.Text.RegularExpressions/Regex.xml index f0a6c0a7892..92ad7f90eff 100644 --- a/xml/System.Text.RegularExpressions/Regex.xml +++ b/xml/System.Text.RegularExpressions/Regex.xml @@ -274,8 +274,8 @@ - - + + The object that contains a serialized pattern and information. @@ -935,8 +935,8 @@ System.Void - - + + An array that describes the regular expressions to compile. @@ -1034,9 +1034,9 @@ System.Void - - - + + + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 2, 1 })] @@ -1158,9 +1158,9 @@ System.Void - - - + + + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 2, 1 })] @@ -1168,7 +1168,7 @@ - + [System.Runtime.CompilerServices.Nullable(2)] @@ -6649,8 +6649,8 @@ For more details about `startat`, see the Remarks section of System.Void - - + + The object to populate with serialization information. @@ -6939,7 +6939,7 @@ Any objects that are included in the System.Void - + The time-out interval to check. diff --git a/xml/System.Text.RegularExpressions/RegexMatchTimeoutException.xml b/xml/System.Text.RegularExpressions/RegexMatchTimeoutException.xml index dbb81b242eb..4a146ef085b 100644 --- a/xml/System.Text.RegularExpressions/RegexMatchTimeoutException.xml +++ b/xml/System.Text.RegularExpressions/RegexMatchTimeoutException.xml @@ -66,31 +66,31 @@ The exception that is thrown when the execution time of a regular expression pattern-matching method exceeds its time-out interval. - exception generally indicates one of the following conditions: - -- The regular expression engine is backtracking excessively as it attempts to match the input text to the regular expression pattern. - -- The time-out interval has been set too low, especially given high machine load. - - The way in which an exception handler handles an exception depends on the cause of the exception: - -- If the time-out results from excessive backtracking, your exception handler should abandon the attempt to match the input and inform the user that a time-out has occurred in the regular expression pattern-matching method. If possible, information about the regular expression pattern, which is available from the property, and the input that caused excessive backtracking, which is available from the property, should be logged so that the issue can be investigated and the regular expression pattern modified. Time-outs due to excessive backtracking are always reproducible. - -- If the time-out results from setting the time-out threshold too low, you can increase the time-out interval and retry the matching operation. The current time-out interval is available from the property. When a exception is thrown, the regular expression engine maintains its state so that any future invocations return the same result, as if the exception did not occur. The recommended pattern is to wait for a brief, random time interval after the exception is thrown before calling the matching method again. This can be repeated several times. However, the number of repetitions should be small in case the time-out is caused by excessive backtracking. - - The example in the next section illustrates both techniques for handling a . - - - -## Examples - The following example illustrates two possible approaches to handling the exception. A constant whose value is two seconds defines the maximum time-out interval. The method is initially called with a time-out interval of one second. Each exception causes the time-out interval to be increased by one second and results in another call to the method if the current time-out interval is less than the maximum time-out interval. However, if the current time-out interval exceeds the maximum time-out interval, the exception handler writes information to the event log and abandons the processing of the regular expression. - + exception generally indicates one of the following conditions: + +- The regular expression engine is backtracking excessively as it attempts to match the input text to the regular expression pattern. + +- The time-out interval has been set too low, especially given high machine load. + + The way in which an exception handler handles an exception depends on the cause of the exception: + +- If the time-out results from excessive backtracking, your exception handler should abandon the attempt to match the input and inform the user that a time-out has occurred in the regular expression pattern-matching method. If possible, information about the regular expression pattern, which is available from the property, and the input that caused excessive backtracking, which is available from the property, should be logged so that the issue can be investigated and the regular expression pattern modified. Time-outs due to excessive backtracking are always reproducible. + +- If the time-out results from setting the time-out threshold too low, you can increase the time-out interval and retry the matching operation. The current time-out interval is available from the property. When a exception is thrown, the regular expression engine maintains its state so that any future invocations return the same result, as if the exception did not occur. The recommended pattern is to wait for a brief, random time interval after the exception is thrown before calling the matching method again. This can be repeated several times. However, the number of repetitions should be small in case the time-out is caused by excessive backtracking. + + The example in the next section illustrates both techniques for handling a . + + + +## Examples + The following example illustrates two possible approaches to handling the exception. A constant whose value is two seconds defines the maximum time-out interval. The method is initially called with a time-out interval of one second. Each exception causes the time-out interval to be increased by one second and results in another call to the method if the current time-out interval is less than the maximum time-out interval. However, if the current time-out interval exceeds the maximum time-out interval, the exception handler writes information to the event log and abandons the processing of the regular expression. + :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/RegexMatchTimeoutException/Overview/class1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.regexmatchtimeoutexception/vb/class1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.regexmatchtimeoutexception/vb/class1.vb" id="Snippet1"::: + ]]> Backtracking in Regular Expressions @@ -146,11 +146,11 @@ Initializes a new instance of the class with a system-supplied message. - class. This constructor initializes the property of the new instance to a system-supplied message that describes the error. This message is localized for the current system culture. - + class. This constructor initializes the property of the new instance to a system-supplied message that describes the error. This message is localized for the current system culture. + ]]> @@ -195,11 +195,11 @@ A string that describes the exception. Initializes a new instance of the class with the specified message string. - property. The string should be localized for the current culture. - + property. The string should be localized for the current culture. + ]]> @@ -244,19 +244,19 @@ - - + + The object that contains the serialized data. The stream that contains the serialized data. Initializes a new instance of the class with serialized data. - object. Instead, it is called by the method when deserializing the object from a stream. - + object. Instead, it is called by the method when deserializing the object from a stream. + ]]> @@ -303,13 +303,13 @@ The exception that is the cause of the current exception. Initializes a new instance of the class with a specified error message and a reference to the inner exception that is the cause of this exception. - object's property. - - The `message` string is assigned to the property. The string should be localized for the current culture. - + object's property. + + The `message` string is assigned to the property. The string should be localized for the current culture. + ]]> @@ -358,11 +358,11 @@ The time-out interval. Initializes a new instance of the class with information about the regular expression pattern, the input text, and the time-out interval. - , , and properties of the new object. - + , , and properties of the new object. + ]]> @@ -407,13 +407,13 @@ Gets the input text that the regular expression engine was processing when the time-out occurred. The regular expression input text. - constructor. If this parameter is not explicitly initialized in a constructor call, its value is . - - When the exception is thrown by the regular expression engine, the value of the property reflects the entire input string passed to the regular expression engine. It does not reflect a partial string, such as the substring that the engine searches in the call to a method such as . - + constructor. If this parameter is not explicitly initialized in a constructor call, its value is . + + When the exception is thrown by the regular expression engine, the value of the property reflects the entire input string passed to the regular expression engine. It does not reflect a partial string, such as the substring that the engine searches in the call to a method such as . + ]]> @@ -458,13 +458,13 @@ Gets the time-out interval for a regular expression match. The time-out interval. - constructor. If the parameter is not properly initialized in a constructor call, its value is `Timespan.FromTicks(-1)`. - - The value of this property reflects the time-out interval set in the call to the constructor or static method. It does not reflect the exact interval that has elapsed from the beginning of the method call to the time the exception is thrown. - + constructor. If the parameter is not properly initialized in a constructor call, its value is `Timespan.FromTicks(-1)`. + + The value of this property reflects the time-out interval set in the call to the constructor or static method. It does not reflect the exact interval that has elapsed from the beginning of the method call to the time the exception is thrown. + ]]> @@ -509,11 +509,11 @@ Gets the regular expression pattern that was used in the matching operation when the time-out occurred. The regular expression pattern. - constructor. If the parameter is not properly initialized in a constructor call, its value is . - + constructor. If the parameter is not properly initialized in a constructor call, its value is . + ]]> @@ -559,9 +559,9 @@ System.Void - + - + The object to populate with data. @@ -569,13 +569,13 @@ The destination for this serialization. Populates a object with the data needed to serialize a object. - instance is cast to an interface object. - - Any objects that are included in the object are automatically tracked and serialized by the formatter. - + instance is cast to an interface object. + + Any objects that are included in the object are automatically tracked and serialized by the formatter. + ]]> diff --git a/xml/System.Text/Decoder.xml b/xml/System.Text/Decoder.xml index bb4924295d2..fc1b08803bc 100644 --- a/xml/System.Text/Decoder.xml +++ b/xml/System.Text/Decoder.xml @@ -303,14 +303,14 @@ The `completed` parameter can also be set to `false`, even though the `bytesUsed System.Void - - - - - - - - + + + + + + + + The address of a buffer that contains the byte sequences to convert. @@ -712,9 +712,9 @@ The following example uses the method to c System.Int32 - - - + + + A pointer to the first byte to decode. @@ -1052,11 +1052,11 @@ The following example uses the method to c System.Int32 - - - - - + + + + + A pointer to the first byte to decode. diff --git a/xml/System.Text/Encoder.xml b/xml/System.Text/Encoder.xml index a2917f8fb06..a1764c3f0f5 100644 --- a/xml/System.Text/Encoder.xml +++ b/xml/System.Text/Encoder.xml @@ -276,14 +276,14 @@ The following example demonstrates how to convert an array of Unicode characters System.Void - - - - - - - - + + + + + + + + The address of a string of UTF-16 encoded characters to convert. @@ -698,9 +698,9 @@ The following example demonstrates how to convert an array of Unicode characters System.Int32 - - - + + + A pointer to the first character to encode. @@ -935,11 +935,11 @@ If your application is to convert many segments of an input stream, consider usi System.Int32 - - - - - + + + + + A pointer to the first character to encode. diff --git a/xml/System.Text/Encoding.xml b/xml/System.Text/Encoding.xml index e32b5d7c986..27dc3218a43 100644 --- a/xml/System.Text/Encoding.xml +++ b/xml/System.Text/Encoding.xml @@ -86,15 +86,15 @@ Represents a character encoding. For more information about this API, see Supplemental API remarks for Encoding. - [!NOTE] -> The `byte[]` array is the only type in this example that contains the encoded data. The .NET `Char` and `String` types are themselves Unicode, so the call decodes the data back to Unicode. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.Convert Example/CPP/convert.cpp" id="Snippet1"::: -:::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/Overview/convert.cs" interactive="try-dotnet" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.Convert Example/VB/convert.vb" id="Snippet1"::: + [!NOTE] +> The `byte[]` array is the only type in this example that contains the encoded data. The .NET `Char` and `String` types are themselves Unicode, so the call decodes the data back to Unicode. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.Convert Example/CPP/convert.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/Overview/convert.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.Convert Example/VB/convert.vb" id="Snippet1"::: ]]> How to use character encoding classes in .NET @@ -149,11 +149,11 @@ The following example converts a string from one encoding to another. Initializes a new instance of the class. - @@ -205,20 +205,20 @@ The following example converts a string from one encoding to another. - The code page identifier of the preferred encoding. - - -or- - + The code page identifier of the preferred encoding. + + -or- + 0, to use the default encoding. Initializes a new instance of the class that corresponds to the specified code page. - object that uses best-fit fallback for both encoding and decoding operations. Both the and properties are read-only and cannot be modified. To control the fallback strategy for a class derived from , call the constructor. - + object that uses best-fit fallback for both encoding and decoding operations. Both the and properties are read-only and cannot be modified. To control the fallback strategy for a class derived from , call the constructor. + ]]> @@ -278,15 +278,15 @@ The following example converts a string from one encoding to another. An object that provides an error-handling procedure when a byte sequence cannot be decoded with the current encoding. Initializes a new instance of the class that corresponds to the specified code page with the specified encoder and decoder fallback strategies. - class constructors create read-only encoding objects that don't allow encoder or decoder fallback to be set after the object is created. - - If either `encoderFallback` or `decoderFallback` is null, best-fit fallback is used as the corresponding fallback strategy. - + class constructors create read-only encoding objects that don't allow encoder or decoder fallback to be set after the object is created. + + If either `encoderFallback` or `decoderFallback` is null, best-fit fallback is used as the corresponding fallback strategy. + ]]> @@ -341,32 +341,32 @@ The following example converts a string from one encoding to another. Gets an encoding for the ASCII (7-bit) character set. An encoding for the ASCII (7-bit) character set. - object that is returned by this property might not have the appropriate behavior for your app. It uses replacement fallback to replace each string that it cannot encode and each byte that it cannot decode with a question mark ("?") character. Instead, you can call the method to instantiate an object whose fallback is either an or a , as the following example illustrates. - - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/ASCII/encoding.ascii2.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.encoding.ascii/vb/encoding.ascii2.vb" id="Snippet1"::: - -## Examples - -The following example demonstrates the effect of the ASCII encoding on characters that are outside the ASCII range. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.ASCII Example/CPP/ascii.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/ASCII/ascii.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.ASCII Example/VB/ascii.vb" id="Snippet1"::: - + object that is returned by this property might not have the appropriate behavior for your app. It uses replacement fallback to replace each string that it cannot encode and each byte that it cannot decode with a question mark ("?") character. Instead, you can call the method to instantiate an object whose fallback is either an or a , as the following example illustrates. + + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/ASCII/encoding.ascii2.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.encoding.ascii/vb/encoding.ascii2.vb" id="Snippet1"::: + +## Examples + +The following example demonstrates the effect of the ASCII encoding on characters that are outside the ASCII range. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.ASCII Example/CPP/ascii.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/ASCII/ascii.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.ASCII Example/VB/ascii.vb" id="Snippet1"::: + ]]> @@ -419,29 +419,29 @@ The following example demonstrates the effect of the ASCII encoding on character Gets an encoding for the UTF-16 format that uses the big endian byte order. An encoding object for the UTF-16 format that uses the big endian byte order. - object that is returned by this property may not have the appropriate behavior for your app. It uses replacement fallback to replace each string that it cannot encode and each byte that it cannot decode with a question mark ("?") character. Instead, you can call the constructor to instantiate a big endian object whose fallback is either an or a , as the following example illustrates. - - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/BigEndianUnicode/bigendianunicode1.cs" interactive="try-dotnet" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.BigEndianUnicode/VB/bigendianunicode1.vb" id="Snippet2"::: - - The returned object has , , and properties, which yield the name "unicodeFFFE". Although the UTF-16 big endian byte order mark is hexadecimal FEFF, the name "unicodeFFFE" was chosen because the byte order mark appears as hexadecimal FFFE on little endian Windows computers. - -## Examples - The following example reads a text file with a UTF-16 encoding using the big endian byte order. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.BigEndianUnicode/CPP/bigendianunicode.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/BigEndianUnicode/bigendianunicode.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.BigEndianUnicode/VB/bigendianunicode.vb" id="Snippet1"::: - - The following example determines the number of bytes required to encode a character array, encodes the characters, and displays the resulting bytes. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArr/CPP/getbytes_chararr.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/BigEndianUnicode/getbytes_chararr.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArr/VB/getbytes_chararr.vb" id="Snippet1"::: - + object that is returned by this property may not have the appropriate behavior for your app. It uses replacement fallback to replace each string that it cannot encode and each byte that it cannot decode with a question mark ("?") character. Instead, you can call the constructor to instantiate a big endian object whose fallback is either an or a , as the following example illustrates. + + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/BigEndianUnicode/bigendianunicode1.cs" interactive="try-dotnet" id="Snippet2"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.BigEndianUnicode/VB/bigendianunicode1.vb" id="Snippet2"::: + + The returned object has , , and properties, which yield the name "unicodeFFFE". Although the UTF-16 big endian byte order mark is hexadecimal FEFF, the name "unicodeFFFE" was chosen because the byte order mark appears as hexadecimal FFFE on little endian Windows computers. + +## Examples + The following example reads a text file with a UTF-16 encoding using the big endian byte order. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.BigEndianUnicode/CPP/bigendianunicode.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/BigEndianUnicode/bigendianunicode.cs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.BigEndianUnicode/VB/bigendianunicode.vb" id="Snippet1"::: + + The following example determines the number of bytes required to encode a character array, encodes the characters, and displays the resulting bytes. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArr/CPP/getbytes_chararr.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/BigEndianUnicode/getbytes_chararr.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArr/VB/getbytes_chararr.vb" id="Snippet1"::: + ]]> @@ -489,26 +489,26 @@ The following example demonstrates the effect of the ASCII encoding on character When overridden in a derived class, gets a name for the current encoding that can be used with mail agent body tags. - A name for the current that can be used with mail agent body tags. - - -or- - + A name for the current that can be used with mail agent body tags. + + -or- + An empty string (""), if the current cannot be used. - with the property. Often the method retrieves a different encoding from the test encoding furnished in the call. Generally only email applications need to retrieve such an encoding; most other applications that need to describe an encoding should use its . - - In some cases, the value of the property corresponds to the international standard that defines that encoding. This doesn't mean that the implementation complies in full with that standard. - -## Examples - The following example retrieves the different names for each encoding and displays the encodings with one or more names that are different from . It displays but does not compare against it. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.Names/CPP/names.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/BodyName/names.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.Names/VB/names.vb" id="Snippet1"::: - + with the property. Often the method retrieves a different encoding from the test encoding furnished in the call. Generally only email applications need to retrieve such an encoding; most other applications that need to describe an encoding should use its . + + In some cases, the value of the property corresponds to the international standard that defines that encoding. This doesn't mean that the implementation complies in full with that standard. + +## Examples + The following example retrieves the different names for each encoding and displays the encodings with one or more names that are different from . It displays but does not compare against it. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.Names/CPP/names.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/BodyName/names.cs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.Names/VB/names.vb" id="Snippet1"::: + ]]> @@ -572,13 +572,13 @@ The following example demonstrates the effect of the ASCII encoding on character When overridden in a derived class, creates a shallow copy of the current object. A copy of the current object. - object is read-only. Therefore, the properties of the clone can be modified. - - A shallow copy of an object is a copy of the object only. If the object contains references to other objects, the shallow copy does not create copies of the referred objects. It refers to the original objects instead. In contrast, a deep copy of an object creates a copy of the object and a copy of everything directly or indirectly referenced by that object. - + object is read-only. Therefore, the properties of the clone can be modified. + + A shallow copy of an object is a copy of the object only. If the object contains references to other objects, the shallow copy does not create copies of the referred objects. It refers to the original objects instead. In contrast, a deep copy of an object creates a copy of the object and a copy of everything directly or indirectly referenced by that object. + ]]> @@ -625,15 +625,15 @@ The following example demonstrates the effect of the ASCII encoding on character When overridden in a derived class, gets the code page identifier of the current . The code page identifier of the current . - . It displays but does not compare against it. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.Names/CPP/names.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/BodyName/names.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.Names/VB/names.vb" id="Snippet1"::: - + . It displays but does not compare against it. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.Names/CPP/names.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/BodyName/names.cs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.Names/VB/names.vb" id="Snippet1"::: + ]]> @@ -701,36 +701,36 @@ The following example demonstrates the effect of the ASCII encoding on character Converts an entire byte array from one encoding to another. An array of type containing the results of converting from to . - property uses replacement fallback and the Pi character is not part of the ASCII character set, the Pi character is replaced with a question mark, as the output from the example shows. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.Convert Example/CPP/convert.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/Overview/convert.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.Convert Example/VB/convert.vb" id="Snippet1"::: - + property uses replacement fallback and the Pi character is not part of the ASCII character set, the Pi character is replaced with a question mark, as the output from the example shows. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.Convert Example/CPP/convert.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/Overview/convert.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.Convert Example/VB/convert.vb" id="Snippet1"::: + ]]> - is . - - -or- - - is . - - -or- - + is . + + -or- + + is . + + -or- + is . - A fallback occurred (for more information, see Character Encoding in .NET) - - -and- - + A fallback occurred (for more information, see Character Encoding in .NET) + + -and- + **srcEncoding.** is set to . - A fallback occurred (for more information, see Character Encoding in .NET) - - -and- - + A fallback occurred (for more information, see Character Encoding in .NET) + + -and- + **dstEncoding.** is set to . @@ -790,26 +790,26 @@ The following example demonstrates the effect of the ASCII encoding on character An array of type containing the result of converting a range of bytes in from to . To be added. - is . - - -or- - - is . - - -or- - + is . + + -or- + + is . + + -or- + is . and do not specify a valid range in the byte array. - A fallback occurred (for more information, see Character Encoding in .NET) - - -and- - + A fallback occurred (for more information, see Character Encoding in .NET) + + -and- + **srcEncoding.** is set to . - A fallback occurred (for more information, see Character Encoding in .NET) - - -and- - + A fallback occurred (for more information, see Character Encoding in .NET) + + -and- + **dstEncoding.** is set to . @@ -855,12 +855,12 @@ The following example demonstrates the effect of the ASCII encoding on character Creates a that serves to transcode data between an inner and an outer , similar to . A stream that transcodes the contents of as . - 's and properties will reflect whether `innerStream` is readable or writable. If `innerStream` is full-duplex, the returned will be as well. However, the returned is not seekable, even if `innerStream`'s property returns `true`. - + 's and properties will reflect whether `innerStream` is readable or writable. If `innerStream` is full-duplex, the returned will be as well. However, the returned is not seekable, even if `innerStream`'s property returns `true`. + ]]> @@ -916,17 +916,17 @@ The returned 's and Gets or sets the object for the current object. The decoder fallback object for the current object. - object represents an error handler that is invoked when an encoded byte sequence cannot be decoded into a character. Any one of the following handler types is supported: - -- A best-fit fallback handler, which replaces bytes that cannot be decoded with some suitable replacement character. - -- A replacement fallback handler, which replaces bytes that cannot be decoded with some arbitrary replacement character. .NET includes one replacement fallback handler, , which by default replaces bytes that cannot be decoded with a question mark ("?") character. - -- An exception fallback handler, which throws an exception when bytes cannot be decoded. .NET includes one exception fallback handler, , which throws a when bytes cannot be decoded. - + object represents an error handler that is invoked when an encoded byte sequence cannot be decoded into a character. Any one of the following handler types is supported: + +- A best-fit fallback handler, which replaces bytes that cannot be decoded with some suitable replacement character. + +- A replacement fallback handler, which replaces bytes that cannot be decoded with some arbitrary replacement character. .NET includes one replacement fallback handler, , which by default replaces bytes that cannot be decoded with a question mark ("?") character. + +- An exception fallback handler, which throws an exception when bytes cannot be decoded. .NET includes one exception fallback handler, , which throws a when bytes cannot be decoded. + ]]> The value in a set operation is . @@ -1040,17 +1040,17 @@ The returned 's and Gets or sets the object for the current object. The encoder fallback object for the current object. - object represents an error handler that is invoked when a character cannot be converted into an encoded byte sequence. Any one of the following handler types is supported: - -- A best-fit fallback handler, which replaces characters that cannot be encoded with some suitable replacement character. - -- A replacement fallback handler, which replaces characters that cannot be encoded with some arbitrary replacement character. .NET includes one replacement fallback handler, , which by default replaces characters that cannot be encoded with a question mark ("?") character. - -- An exception fallback handler, which throws an exception when characters cannot be encoded. .NET includes one exception fallback handler, , which throws an when characters cannot be decoded. - + object represents an error handler that is invoked when a character cannot be converted into an encoded byte sequence. Any one of the following handler types is supported: + +- A best-fit fallback handler, which replaces characters that cannot be encoded with some suitable replacement character. + +- A replacement fallback handler, which replaces characters that cannot be encoded with some arbitrary replacement character. .NET includes one replacement fallback handler, , which by default replaces characters that cannot be encoded with a question mark ("?") character. + +- An exception fallback handler, which throws an exception when characters cannot be encoded. .NET includes one exception fallback handler, , which throws an when characters cannot be decoded. + ]]> The value in a set operation is . @@ -1102,18 +1102,18 @@ The returned 's and When overridden in a derived class, gets the human-readable description of the current encoding. The human-readable description of the current . - property is intended for display. To find a name that can be passed to the method, use the property. - -## Examples - The following example retrieves the different names for each encoding and displays the encodings with one or more names that are different from . It displays but does not compare against it. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.Names/CPP/names.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/BodyName/names.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.Names/VB/names.vb" id="Snippet1"::: - + property is intended for display. To find a name that can be passed to the method, use the property. + +## Examples + The following example retrieves the different names for each encoding and displays the encodings with one or more names that are different from . It displays but does not compare against it. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.Names/CPP/names.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/BodyName/names.cs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.Names/VB/names.vb" id="Snippet1"::: + ]]> @@ -1184,18 +1184,18 @@ The returned 's and if is an instance of and is equal to the current instance; otherwise, . - are considered equal if they correspond to the same code page and their `EncoderFallback` and `DecoderFallback` objects are equal. In particular, derived code pages all have a code page of 0 and their fallbacks are normally `null` (`Nothing` in Visual Basic .NET). Thus they are all considered equal to one another. One consequence is that when is used to populate a hash table, all derived encodings compare equal and fall into the same hash table slot. - -## Examples - The following example gets two instances of the same encoding (one by codepage and another by name), and checks their equality. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.Equals/CPP/equals.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/Equals/equals.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.Equals/VB/equals.vb" id="Snippet1"::: - + are considered equal if they correspond to the same code page and their `EncoderFallback` and `DecoderFallback` objects are equal. In particular, derived code pages all have a code page of 0 and their fallbacks are normally `null` (`Nothing` in Visual Basic .NET). Thus they are all considered equal to one another. One consequence is that when is used to populate a hash table, all derived encodings compare equal and fall into the same hash table slot. + +## Examples + The following example gets two instances of the same encoding (one by codepage and another by name), and checks their equality. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.Equals/CPP/equals.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/Equals/equals.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.Equals/VB/equals.vb" id="Snippet1"::: + ]]> @@ -1259,40 +1259,40 @@ The returned 's and When overridden in a derived class, calculates the number of bytes produced by encoding all the characters in the specified character array. The number of bytes produced by encoding all the characters in the specified character array. - to store the resulting bytes, call the method. To calculate the maximum array size, call the method. The method generally allows allocation of less memory, while the method generally executes faster. - - The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. - - Several versions of and are supported. The following are some programming considerations for use of these methods: - -- Your app might need to encode many input characters to a code page and process the characters using multiple calls. In this case, you probably need to maintain state between calls, taking into account the state that is persisted by the object being used. - -- If your app handles string inputs, you should use the string versions of the method. - -- The Unicode character buffer version of allows some fast techniques, particularly with multiple calls using the object or inserting into existing buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. - -- If your app must convert a large amount of data, you should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. - -- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. - -## Examples - The following example determines the number of bytes required to encode a character array, encodes the characters, and displays the resulting bytes. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArr/CPP/getbytes_chararr.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/BigEndianUnicode/getbytes_chararr.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArr/VB/getbytes_chararr.vb" id="Snippet1"::: - + to store the resulting bytes, call the method. To calculate the maximum array size, call the method. The method generally allows allocation of less memory, while the method generally executes faster. + + The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. + + Several versions of and are supported. The following are some programming considerations for use of these methods: + +- Your app might need to encode many input characters to a code page and process the characters using multiple calls. In this case, you probably need to maintain state between calls, taking into account the state that is persisted by the object being used. + +- If your app handles string inputs, you should use the string versions of the method. + +- The Unicode character buffer version of allows some fast techniques, particularly with multiple calls using the object or inserting into existing buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. + +- If your app must convert a large amount of data, you should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. + +- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. + +## Examples + The following example determines the number of bytes required to encode a character array, encodes the characters, and displays the resulting bytes. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArr/CPP/getbytes_chararr.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/BigEndianUnicode/getbytes_chararr.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArr/VB/getbytes_chararr.vb" id="Snippet1"::: + ]]> is . - A fallback occurred (for more information, see Character Encoding in .NET) - - -and- - + A fallback occurred (for more information, see Character Encoding in .NET) + + -and- + is set to . @@ -1344,21 +1344,21 @@ The returned 's and When overridden in a derived class, calculates the number of bytes produced by encoding the characters in the specified character span. The number of bytes produced by encoding the specified character span. - to store the resulting bytes, call the method. To calculate the maximum span size, call the method. The method generally allows allocation of less memory, while the method generally executes faster. - - The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. - - Several versions of and are supported. The following are some programming considerations for use of these methods: - -- Your app might need to encode many input characters to a code page and process the characters using multiple calls. In this case, you probably need to maintain state between calls, taking into account the state that is persisted by the object being used. - -- If your app handles span of characters inputs, the span version of is recommended. - -- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output span buffer is too small. For continuous encoding of a stream, this method is often the best choice. - + to store the resulting bytes, call the method. To calculate the maximum span size, call the method. The method generally allows allocation of less memory, while the method generally executes faster. + + The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. + + Several versions of and are supported. The following are some programming considerations for use of these methods: + +- Your app might need to encode many input characters to a code page and process the characters using multiple calls. In this case, you probably need to maintain state between calls, taking into account the state that is persisted by the object being used. + +- If your app handles span of characters inputs, the span version of is recommended. + +- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output span buffer is too small. For continuous encoding of a stream, this method is often the best choice. + ]]> @@ -1410,40 +1410,40 @@ The returned 's and When overridden in a derived class, calculates the number of bytes produced by encoding the characters in the specified string. The number of bytes produced by encoding the specified characters. - to store the resulting bytes, call the method. To calculate the maximum array size, call the method. The method generally allows allocation of less memory, while the method generally executes faster. - - The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. - - Several versions of and are supported. The following are some programming considerations for use of these methods: - -- Your app might need to encode many input characters to a code page and process the characters using multiple calls. In this case, you probably need to maintain state between calls, taking into account the state that is persisted by the object being used. - -- If your app handles string inputs, the string version of is recommended. - -- The Unicode character buffer version of allows some fast techniques, particularly with multiple calls using the object or inserting into existing buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. - -- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. - -- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. - -## Examples - The following example determines the number of bytes required to encode a string or a range in the string, encodes the characters, and displays the resulting bytes. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_String/CPP/getbytes_string.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetByteCount/getbytes_string.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_String/VB/getbytes_string.vb" id="Snippet1"::: - + to store the resulting bytes, call the method. To calculate the maximum array size, call the method. The method generally allows allocation of less memory, while the method generally executes faster. + + The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. + + Several versions of and are supported. The following are some programming considerations for use of these methods: + +- Your app might need to encode many input characters to a code page and process the characters using multiple calls. In this case, you probably need to maintain state between calls, taking into account the state that is persisted by the object being used. + +- If your app handles string inputs, the string version of is recommended. + +- The Unicode character buffer version of allows some fast techniques, particularly with multiple calls using the object or inserting into existing buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. + +- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. + +- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. + +## Examples + The following example determines the number of bytes required to encode a string or a range in the string, encodes the characters, and displays the resulting bytes. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_String/CPP/getbytes_string.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetByteCount/getbytes_string.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_String/VB/getbytes_string.vb" id="Snippet1"::: + ]]> is . - A fallback occurred (for more information, see Character Encoding in .NET) - - -and- - + A fallback occurred (for more information, see Character Encoding in .NET) + + -and- + is set to . @@ -1514,35 +1514,35 @@ The returned 's and When overridden in a derived class, calculates the number of bytes produced by encoding a set of characters starting at the specified character pointer. The number of bytes produced by encoding the specified characters. - requires to store the resulting bytes, you should call the method. To calculate the maximum array size, call the method. The method generally allows allocation of less memory, while the method generally executes faster. - - The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. - - Several versions of and are supported. The following are some considerations for using these methods: - -- Your app may need to encode many input characters to a code page and process the characters using multiple calls. In this case, you probably need to maintain state between calls, taking into account the state that is persisted by the object being used. - -- If your app handles string inputs, you should use the string version of the method. - -- The Unicode character buffer version of allows some fast techniques, particularly with multiple calls using the object or inserting into existing buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. - -- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. - -- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. - + requires to store the resulting bytes, you should call the method. To calculate the maximum array size, call the method. The method generally allows allocation of less memory, while the method generally executes faster. + + The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. + + Several versions of and are supported. The following are some considerations for using these methods: + +- Your app may need to encode many input characters to a code page and process the characters using multiple calls. In this case, you probably need to maintain state between calls, taking into account the state that is persisted by the object being used. + +- If your app handles string inputs, you should use the string version of the method. + +- The Unicode character buffer version of allows some fast techniques, particularly with multiple calls using the object or inserting into existing buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. + +- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. + +- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. + ]]> is . is less than zero. - A fallback occurred (for more information, see Character Encoding in .NET) - - -and- - + A fallback occurred (for more information, see Character Encoding in .NET) + + -and- + is set to . @@ -1600,46 +1600,46 @@ The returned 's and When overridden in a derived class, calculates the number of bytes produced by encoding a set of characters from the specified character array. The number of bytes produced by encoding the specified characters. - to store the resulting bytes, call the method. To calculate the maximum array size, call the method. The method generally allows allocation of less memory, while the method generally executes faster. - - The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. - - Several versions of and are supported. The following are some programming considerations for use of these methods: - -- Your app might need to encode many input characters to a code page and process the characters using multiple calls. In this case, you probably need to maintain state between calls, taking into account the state that is persisted by the object being used. - -- If your app handles string inputs, the string version of is recommended. - -- The Unicode character buffer version of allows some fast techniques, particularly with multiple calls using the object or inserting into existing buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. - -- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. - -- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. - -## Examples - The following example determines the number of bytes required to encode three characters from a character array, encodes the characters, and displays the resulting bytes. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArrIC/CPP/getbytes_chararric.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetByteCount/getbytes_chararric.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArrIC/VB/getbytes_chararric.vb" id="Snippet1"::: - + to store the resulting bytes, call the method. To calculate the maximum array size, call the method. The method generally allows allocation of less memory, while the method generally executes faster. + + The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. + + Several versions of and are supported. The following are some programming considerations for use of these methods: + +- Your app might need to encode many input characters to a code page and process the characters using multiple calls. In this case, you probably need to maintain state between calls, taking into account the state that is persisted by the object being used. + +- If your app handles string inputs, the string version of is recommended. + +- The Unicode character buffer version of allows some fast techniques, particularly with multiple calls using the object or inserting into existing buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. + +- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. + +- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. + +## Examples + The following example determines the number of bytes required to encode three characters from a character array, encodes the characters, and displays the resulting bytes. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArrIC/CPP/getbytes_chararric.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetByteCount/getbytes_chararric.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArrIC/VB/getbytes_chararric.vb" id="Snippet1"::: + ]]> is . - or is less than zero. - - -or- - + or is less than zero. + + -or- + and do not denote a valid range in . - A fallback occurred (for more information, see Character Encoding in .NET) - - -and- - + A fallback occurred (for more information, see Character Encoding in .NET) + + -and- + is set to . @@ -1690,32 +1690,32 @@ The returned 's and When overridden in a derived class, calculates the number of bytes produced by encoding a set of characters from the specified string. The number of bytes produced by encoding the string. - to store the resulting bytes, call the method. To calculate the maximum array size, call the method. The method generally allows allocation of less memory, while the method generally executes faster. - - The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. - - Several versions of and are supported. The following are some programming considerations for use of these methods: - -- Your app might need to encode many input characters to a code page and process the characters using multiple calls. In this case, you probably need to maintain state between calls, taking into account the state that is persisted by the object being used. - -- If your app handles string inputs, the string version of is recommended. - -- The Unicode character buffer version of allows some fast techniques, particularly with multiple calls using the object or inserting into existing buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. - -- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. - -- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. - -## Examples - The following example determines the number of bytes required to encode three characters from a character array, encodes the characters, and displays the resulting bytes. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArrIC/CPP/getbytes_chararric.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetByteCount/getbytes_chararric.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArrIC/VB/getbytes_chararric.vb" id="Snippet1"::: - + to store the resulting bytes, call the method. To calculate the maximum array size, call the method. The method generally allows allocation of less memory, while the method generally executes faster. + + The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. + + Several versions of and are supported. The following are some programming considerations for use of these methods: + +- Your app might need to encode many input characters to a code page and process the characters using multiple calls. In this case, you probably need to maintain state between calls, taking into account the state that is persisted by the object being used. + +- If your app handles string inputs, the string version of is recommended. + +- The Unicode character buffer version of allows some fast techniques, particularly with multiple calls using the object or inserting into existing buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. + +- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. + +- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. + +## Examples + The following example determines the number of bytes required to encode three characters from a character array, encodes the characters, and displays the resulting bytes. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArrIC/CPP/getbytes_chararric.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetByteCount/getbytes_chararric.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArrIC/VB/getbytes_chararric.vb" id="Snippet1"::: + ]]> @@ -1777,40 +1777,40 @@ The returned 's and When overridden in a derived class, encodes all the characters in the specified character array into a sequence of bytes. A byte array containing the results of encoding the specified set of characters. - or the provided by the method or the method, respectively, of a derived class. - - The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. - - Several versions of and are supported. The following are some programming considerations for use of these methods: - -- Your app might need to encode many input characters to a code page and process the characters using multiple calls. In this case, you probably need to maintain state between calls, taking into account the state that is persisted by the object being used. (For example, a character sequence that includes surrogate pairs might end with a high surrogate. The will remember that high surrogate so that it can be combined with a low surrogate at the beginning of a following call. won't be able to maintain the state, so the character will be sent to the .) - -- If your app handles string inputs, you should call the string version of the method. - -- The Unicode character buffer version of allows some fast techniques, particularly with multiple calls using the object or inserting into existing buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. - -- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. - -- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. - -## Examples - The following example determines the number of bytes required to encode a character array, encodes the characters, and displays the resulting bytes. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArr/CPP/getbytes_chararr.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/BigEndianUnicode/getbytes_chararr.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArr/VB/getbytes_chararr.vb" id="Snippet1"::: - + or the provided by the method or the method, respectively, of a derived class. + + The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. + + Several versions of and are supported. The following are some programming considerations for use of these methods: + +- Your app might need to encode many input characters to a code page and process the characters using multiple calls. In this case, you probably need to maintain state between calls, taking into account the state that is persisted by the object being used. (For example, a character sequence that includes surrogate pairs might end with a high surrogate. The will remember that high surrogate so that it can be combined with a low surrogate at the beginning of a following call. won't be able to maintain the state, so the character will be sent to the .) + +- If your app handles string inputs, you should call the string version of the method. + +- The Unicode character buffer version of allows some fast techniques, particularly with multiple calls using the object or inserting into existing buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. + +- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. + +- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. + +## Examples + The following example determines the number of bytes required to encode a character array, encodes the characters, and displays the resulting bytes. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArr/CPP/getbytes_chararr.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/BigEndianUnicode/getbytes_chararr.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArr/VB/getbytes_chararr.vb" id="Snippet1"::: + ]]> is . - A fallback occurred (for more information, see Character Encoding in .NET) - - -and- - + A fallback occurred (for more information, see Character Encoding in .NET) + + -and- + is set to . @@ -1864,40 +1864,40 @@ The returned 's and When overridden in a derived class, encodes all the characters in the specified string into a sequence of bytes. A byte array containing the results of encoding the specified set of characters. - or the provided by the method or the method, respectively, of a derived class. - - The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. - - Several versions of and are supported. The following are some programming considerations for use of these methods: - -- Your app might need to encode many input characters to a code page and process the characters using multiple calls. In this case, you probably need to maintain state between calls, taking into account the state that is persisted by the object being used. (For example, a character sequence that includes surrogate pairs might end with a high surrogate. The will remember that high surrogate so that it can be combined with a low surrogate at the beginning of a following call. won't be able to maintain the state, so the character will be sent to the .) - -- If your app handles string inputs, you should use the string version of . - -- The Unicode character buffer version of allows some fast techniques, particularly with multiple calls using the object or inserting into existing buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. - -- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. - -- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. - -## Examples - The following example determines the number of bytes required to encode a string or a range in the string, encodes the characters, and displays the resulting bytes. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_String/CPP/getbytes_string.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetByteCount/getbytes_string.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_String/VB/getbytes_string.vb" id="Snippet1"::: - + or the provided by the method or the method, respectively, of a derived class. + + The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. + + Several versions of and are supported. The following are some programming considerations for use of these methods: + +- Your app might need to encode many input characters to a code page and process the characters using multiple calls. In this case, you probably need to maintain state between calls, taking into account the state that is persisted by the object being used. (For example, a character sequence that includes surrogate pairs might end with a high surrogate. The will remember that high surrogate so that it can be combined with a low surrogate at the beginning of a following call. won't be able to maintain the state, so the character will be sent to the .) + +- If your app handles string inputs, you should use the string version of . + +- The Unicode character buffer version of allows some fast techniques, particularly with multiple calls using the object or inserting into existing buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. + +- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. + +- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. + +## Examples + The following example determines the number of bytes required to encode a string or a range in the string, encodes the characters, and displays the resulting bytes. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_String/CPP/getbytes_string.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetByteCount/getbytes_string.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_String/VB/getbytes_string.vb" id="Snippet1"::: + ]]> is . - A fallback occurred (for more information, see Character Encoding in .NET) - - -and- - + A fallback occurred (for more information, see Character Encoding in .NET) + + -and- + is set to . @@ -1951,23 +1951,23 @@ The returned 's and When overridden in a derived class, encodes into a span of bytes a set of characters from the specified read-only span. The number of encoded bytes. - or the provided by the method or the method, respectively, of a derived class. - - The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. - - Several versions of and are supported. The following are some programming considerations for use of these methods: - -- Your app might need to encode many input characters to a code page and process the characters using multiple calls. In this case, you probably need to maintain state between calls, taking into account the state that is persisted by the object being used. (For example, a character sequence that includes surrogate pairs might end with a high surrogate. The will remember that high surrogate so that it can be combined with a low surrogate at the beginning of a following call. won't be able to maintain the state, so the character will be sent to the .) - -- If your app handles string inputs, you should use the string version of . - -- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. - -- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. - + or the provided by the method or the method, respectively, of a derived class. + + The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. + + Several versions of and are supported. The following are some programming considerations for use of these methods: + +- Your app might need to encode many input characters to a code page and process the characters using multiple calls. In this case, you probably need to maintain state between calls, taking into account the state that is persisted by the object being used. (For example, a character sequence that includes surrogate pairs might end with a high surrogate. The will remember that high surrogate so that it can be combined with a low surrogate at the beginning of a following call. won't be able to maintain the state, so the character will be sent to the .) + +- If your app handles string inputs, you should use the string version of . + +- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. + +- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. + ]]> @@ -2029,46 +2029,46 @@ The returned 's and When overridden in a derived class, encodes a set of characters from the specified character array into a sequence of bytes. A byte array containing the results of encoding the specified set of characters. - or the provided by the method or the method, respectively, of a derived class. - - The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. - - Several versions of and are supported. The following are some programming considerations for use of these methods: - -- Your app might need to encode many input characters to a code page and process the characters using multiple calls. In this case, you probably need to maintain state between calls, taking into account the state that is persisted by the object being used. (For example, a character sequence that includes surrogate pairs might end with a high surrogate. The will remember that high surrogate so that it can be combined with a low surrogate at the beginning of a following call. won't be able to maintain the state, so the character will be sent to the .) - -- If your app handles string inputs, you should use the string version of . - -- The Unicode character buffer version of allows some fast techniques, particularly with multiple calls using the object or inserting into existing buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. - -- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. - -- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. - -## Examples - The following example determines the number of bytes required to encode three characters from a character array, encodes the characters, and displays the resulting bytes. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArrIC/CPP/getbytes_chararric.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetByteCount/getbytes_chararric.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArrIC/VB/getbytes_chararric.vb" id="Snippet1"::: - + or the provided by the method or the method, respectively, of a derived class. + + The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. + + Several versions of and are supported. The following are some programming considerations for use of these methods: + +- Your app might need to encode many input characters to a code page and process the characters using multiple calls. In this case, you probably need to maintain state between calls, taking into account the state that is persisted by the object being used. (For example, a character sequence that includes surrogate pairs might end with a high surrogate. The will remember that high surrogate so that it can be combined with a low surrogate at the beginning of a following call. won't be able to maintain the state, so the character will be sent to the .) + +- If your app handles string inputs, you should use the string version of . + +- The Unicode character buffer version of allows some fast techniques, particularly with multiple calls using the object or inserting into existing buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. + +- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. + +- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. + +## Examples + The following example determines the number of bytes required to encode three characters from a character array, encodes the characters, and displays the resulting bytes. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArrIC/CPP/getbytes_chararric.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetByteCount/getbytes_chararric.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArrIC/VB/getbytes_chararric.vb" id="Snippet1"::: + ]]> is . - or is less than zero. - - -or- - + or is less than zero. + + -or- + and do not denote a valid range in . - A fallback occurred (for more information, see Character Encoding in .NET) - - -and- - + A fallback occurred (for more information, see Character Encoding in .NET) + + -and- + is set to . @@ -2119,32 +2119,32 @@ The returned 's and When overridden in a derived class, encodes into an array of bytes the number of characters specified by in the specified string, starting from the specified . A byte array containing the results of encoding the specified set of characters. - or the provided by the method or the method, respectively, of a derived class. - - The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. - - Several versions of and are supported. The following are some programming considerations for use of these methods: - -- Your app might need to encode many input characters to a code page and process the characters using multiple calls. In this case, you probably need to maintain state between calls, taking into account the state that is persisted by the object being used. (For example, a character sequence that includes surrogate pairs might end with a high surrogate. The will remember that high surrogate so that it can be combined with a low surrogate at the beginning of a following call. won't be able to maintain the state, so the character will be sent to the .) - -- If your app handles string inputs, you should use the string version of . - -- The Unicode character buffer version of allows some fast techniques, particularly with multiple calls using the object or inserting into existing buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. - -- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. - -- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. - -## Examples - The following example determines the number of bytes required to encode a string or a range in the string, encodes the characters, and displays the resulting bytes. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_String/CPP/getbytes_string.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetByteCount/getbytes_string.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_String/VB/getbytes_string.vb" id="Snippet1"::: - + or the provided by the method or the method, respectively, of a derived class. + + The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. + + Several versions of and are supported. The following are some programming considerations for use of these methods: + +- Your app might need to encode many input characters to a code page and process the characters using multiple calls. In this case, you probably need to maintain state between calls, taking into account the state that is persisted by the object being used. (For example, a character sequence that includes surrogate pairs might end with a high surrogate. The will remember that high surrogate so that it can be combined with a low surrogate at the beginning of a following call. won't be able to maintain the state, so the character will be sent to the .) + +- If your app handles string inputs, you should use the string version of . + +- The Unicode character buffer version of allows some fast techniques, particularly with multiple calls using the object or inserting into existing buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. + +- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. + +- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. + +## Examples + The following example determines the number of bytes required to encode a string or a range in the string, encodes the characters, and displays the resulting bytes. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_String/CPP/getbytes_string.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetByteCount/getbytes_string.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_String/VB/getbytes_string.vb" id="Snippet1"::: + ]]> @@ -2217,43 +2217,43 @@ The returned 's and When overridden in a derived class, encodes a set of characters starting at the specified character pointer into a sequence of bytes that are stored starting at the specified byte pointer. The actual number of bytes written at the location indicated by the parameter. - requires to store the resulting bytes, call the method. To calculate the maximum array size, call the method. The method generally allows allocation of less memory, while the method generally executes faster. - - If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the or the object provided by the or the method, respectively, of a derived class. - - The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. - - Several versions of and are supported. The following are some programming considerations for use of these methods: - -- Your app might need to encode many input characters to a code page and process the characters using multiple calls. In this case, you probably need to maintain state between calls, taking into account the state that is persisted by the object being used. (For example, a character sequence that includes surrogate pairs might end with a high surrogate. The will remember that high surrogate so that it can be combined with a low surrogate at the beginning of a following call. won't be able to maintain the state, so the character will be sent to the .) - -- If your app handles string inputs, you should use the string version of . - -- The Unicode character buffer version of allows some fast techniques, particularly with multiple calls using the object or inserting into existing buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. - -- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. - -- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. - + requires to store the resulting bytes, call the method. To calculate the maximum array size, call the method. The method generally allows allocation of less memory, while the method generally executes faster. + + If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the or the object provided by the or the method, respectively, of a derived class. + + The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. + + Several versions of and are supported. The following are some programming considerations for use of these methods: + +- Your app might need to encode many input characters to a code page and process the characters using multiple calls. In this case, you probably need to maintain state between calls, taking into account the state that is persisted by the object being used. (For example, a character sequence that includes surrogate pairs might end with a high surrogate. The will remember that high surrogate so that it can be combined with a low surrogate at the beginning of a following call. won't be able to maintain the state, so the character will be sent to the .) + +- If your app handles string inputs, you should use the string version of . + +- The Unicode character buffer version of allows some fast techniques, particularly with multiple calls using the object or inserting into existing buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. + +- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. + +- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. + ]]> - is . - - -or- - + is . + + -or- + is . or is less than zero. is less than the resulting number of bytes. - A fallback occurred (for more information, see Character Encoding in .NET) - - -and- - + A fallback occurred (for more information, see Character Encoding in .NET) + + -and- + is set to . @@ -2315,58 +2315,58 @@ The returned 's and When overridden in a derived class, encodes a set of characters from the specified character array into the specified byte array. The actual number of bytes written into . - to store the resulting bytes, you should call the method. To calculate the maximum array size, call the method. The method generally allows allocation of less memory, while the method generally executes faster. - - If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the or the provided by the method or the method, respectively, of a derived class. - - The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. - - Several versions of and are supported. The following are some programming considerations for use of these methods: - -- Your app might need to encode many input characters to a code page and process the characters using multiple calls. In this case, you probably need to maintain state between calls, taking into account the state that is persisted by the object being used. (For example, a character sequence that includes surrogate pairs might end with a high surrogate. The will remember that high surrogate so that it can be combined with a low surrogate at the beginning of a following call. won't be able to maintain the state, so the character will be sent to the .) - -- If your app handles string inputs, you should use the string version of . - -- The Unicode character buffer version of allows some fast techniques, particularly with multiple calls using the object or inserting into existing buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. - -- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. - -- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. - -## Examples - The following example determines the number of bytes required to encode three characters from a character array, encodes the characters, and displays the resulting bytes. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArrIC/CPP/getbytes_chararric.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetByteCount/getbytes_chararric.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArrIC/VB/getbytes_chararric.vb" id="Snippet1"::: - + to store the resulting bytes, you should call the method. To calculate the maximum array size, call the method. The method generally allows allocation of less memory, while the method generally executes faster. + + If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the or the provided by the method or the method, respectively, of a derived class. + + The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. + + Several versions of and are supported. The following are some programming considerations for use of these methods: + +- Your app might need to encode many input characters to a code page and process the characters using multiple calls. In this case, you probably need to maintain state between calls, taking into account the state that is persisted by the object being used. (For example, a character sequence that includes surrogate pairs might end with a high surrogate. The will remember that high surrogate so that it can be combined with a low surrogate at the beginning of a following call. won't be able to maintain the state, so the character will be sent to the .) + +- If your app handles string inputs, you should use the string version of . + +- The Unicode character buffer version of allows some fast techniques, particularly with multiple calls using the object or inserting into existing buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. + +- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. + +- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. + +## Examples + The following example determines the number of bytes required to encode three characters from a character array, encodes the characters, and displays the resulting bytes. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArrIC/CPP/getbytes_chararric.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetByteCount/getbytes_chararric.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArrIC/VB/getbytes_chararric.vb" id="Snippet1"::: + ]]> - is . - - -or- - + is . + + -or- + is . - or or is less than zero. - - -or- - - and do not denote a valid range in . - - -or- - + or or is less than zero. + + -or- + + and do not denote a valid range in . + + -or- + is not a valid index in . does not have enough capacity from to the end of the array to accommodate the resulting bytes. - A fallback occurred (for more information, see Character Encoding in .NET) - - -and- - + A fallback occurred (for more information, see Character Encoding in .NET) + + -and- + is set to . @@ -2428,58 +2428,58 @@ The returned 's and When overridden in a derived class, encodes a set of characters from the specified string into the specified byte array. The actual number of bytes written into . - to store the resulting bytes, you should call the method. To calculate the maximum array size, call the method. The method generally allows allocation of less memory, while the method generally executes faster. - - If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the or the provided by the method or the method, respectively, of a derived class. - - The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. - - Several versions of and are supported. The following are some programming considerations for use of these methods: - -- Your app might need to encode many input characters to a code page and process the characters using multiple calls. In this case, you probably need to maintain state between calls, taking into account the state that is persisted by the object being used. (For example, a character sequence that includes surrogate pairs might end with a high surrogate. The will remember that high surrogate so that it can be combined with a low surrogate at the beginning of a following call. won't be able to maintain the state, so the character will be sent to the .) - -- If your app handles string inputs, you should use the string version of . - -- The Unicode character buffer version of allows some fast techniques, particularly with multiple calls using the object or inserting into existing buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. - -- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. - -- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. - -## Examples - The following example determines the number of bytes required to encode a string or a range in the string, encodes the characters, and displays the resulting bytes. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_String/CPP/getbytes_string.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetByteCount/getbytes_string.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_String/VB/getbytes_string.vb" id="Snippet1"::: - + to store the resulting bytes, you should call the method. To calculate the maximum array size, call the method. The method generally allows allocation of less memory, while the method generally executes faster. + + If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the or the provided by the method or the method, respectively, of a derived class. + + The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. + + Several versions of and are supported. The following are some programming considerations for use of these methods: + +- Your app might need to encode many input characters to a code page and process the characters using multiple calls. In this case, you probably need to maintain state between calls, taking into account the state that is persisted by the object being used. (For example, a character sequence that includes surrogate pairs might end with a high surrogate. The will remember that high surrogate so that it can be combined with a low surrogate at the beginning of a following call. won't be able to maintain the state, so the character will be sent to the .) + +- If your app handles string inputs, you should use the string version of . + +- The Unicode character buffer version of allows some fast techniques, particularly with multiple calls using the object or inserting into existing buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. + +- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. + +- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. + +## Examples + The following example determines the number of bytes required to encode a string or a range in the string, encodes the characters, and displays the resulting bytes. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_String/CPP/getbytes_string.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetByteCount/getbytes_string.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_String/VB/getbytes_string.vb" id="Snippet1"::: + ]]> - is . - - -or- - + is . + + -or- + is . - or or is less than zero. - - -or- - - and do not denote a valid range in . - - -or- - + or or is less than zero. + + -or- + + and do not denote a valid range in . + + -or- + is not a valid index in . does not have enough capacity from to the end of the array to accommodate the resulting bytes. - A fallback occurred (for more information, see Character Encoding in .NET) - - -and- - + A fallback occurred (for more information, see Character Encoding in .NET) + + -and- + is set to . @@ -2543,40 +2543,40 @@ The returned 's and When overridden in a derived class, calculates the number of characters produced by decoding all the bytes in the specified byte array. The number of characters produced by decoding the specified sequence of bytes. - to store the resulting characters, you should use the method. To calculate the maximum array size, you should use the method. The method generally allows allocation of less memory, while the method generally executes faster. - - The method determines how many characters result in decoding a sequence of bytes, and the method performs the actual decoding. The method expects discrete conversions, in contrast to the method, which handles multiple passes on a single input stream. - - Several versions of and are supported. The following are some programming considerations for use of these methods: - -- Your app might need to decode multiple input bytes from a code page and process the bytes using multiple calls. In this case, you probably need to maintain state between calls. - -- If your app handles string outputs, you should use the method. Since this method must check string length and allocate a buffer, it is slightly slower, but the resulting type is to be preferred. - -- The byte version of allows some fast techniques, particularly with multiple calls to large buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. - -- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports output character buffers is the best choice. - -- Consider using the method instead of . The conversion method converts as much data as possible and throws an exception if the output buffer is too small. For continuous decoding of a stream, this method is often the best choice. - -## Examples - The following example encodes a string into an array of bytes, and then decodes the bytes into an array of characters. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetChars/CPP/getchars.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetCharCount/getchars.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetChars/VB/getchars.vb" id="Snippet1"::: - + to store the resulting characters, you should use the method. To calculate the maximum array size, you should use the method. The method generally allows allocation of less memory, while the method generally executes faster. + + The method determines how many characters result in decoding a sequence of bytes, and the method performs the actual decoding. The method expects discrete conversions, in contrast to the method, which handles multiple passes on a single input stream. + + Several versions of and are supported. The following are some programming considerations for use of these methods: + +- Your app might need to decode multiple input bytes from a code page and process the bytes using multiple calls. In this case, you probably need to maintain state between calls. + +- If your app handles string outputs, you should use the method. Since this method must check string length and allocate a buffer, it is slightly slower, but the resulting type is to be preferred. + +- The byte version of allows some fast techniques, particularly with multiple calls to large buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. + +- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports output character buffers is the best choice. + +- Consider using the method instead of . The conversion method converts as much data as possible and throws an exception if the output buffer is too small. For continuous decoding of a stream, this method is often the best choice. + +## Examples + The following example encodes a string into an array of bytes, and then decodes the bytes into an array of characters. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetChars/CPP/getchars.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetCharCount/getchars.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetChars/VB/getchars.vb" id="Snippet1"::: + ]]> is . - A fallback occurred (for more information, see Character Encoding in .NET) - - -and- - + A fallback occurred (for more information, see Character Encoding in .NET) + + -and- + is set to . @@ -2628,23 +2628,23 @@ The returned 's and When overridden in a derived class, calculates the number of characters produced by decoding the provided read-only byte span. The number of characters produced by decoding the byte span. - requires to store the resulting characters, you should use the method. To calculate the maximum array size, use the method. The method generally allows allocation of less memory, while the method generally executes faster. - - The method determines how many characters result in decoding a sequence of bytes, and the method performs the actual decoding. The method expects discrete conversions, in contrast to the method, which handles multiple passes on a single input stream. - - Several versions of and are supported. The following are some programming considerations for use of these methods: - -- Your app might need to decode multiple input bytes from a code page and process the bytes using multiple calls. In this case, you probably need to maintain state between calls. - -- If your app handles string outputs, it is recommended to use the method. Since this method must check string length and allocate a buffer, it is slightly slower, but the resulting type is to be preferred. - -- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports output character buffers is the best choice. - -- Consider using the method instead of . The conversion method converts as much data as possible and throws an exception if the output buffer is too small. For continuous decoding of a stream, this method is often the best choice. - + requires to store the resulting characters, you should use the method. To calculate the maximum array size, use the method. The method generally allows allocation of less memory, while the method generally executes faster. + + The method determines how many characters result in decoding a sequence of bytes, and the method performs the actual decoding. The method expects discrete conversions, in contrast to the method, which handles multiple passes on a single input stream. + + Several versions of and are supported. The following are some programming considerations for use of these methods: + +- Your app might need to decode multiple input bytes from a code page and process the bytes using multiple calls. In this case, you probably need to maintain state between calls. + +- If your app handles string outputs, it is recommended to use the method. Since this method must check string length and allocate a buffer, it is slightly slower, but the resulting type is to be preferred. + +- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports output character buffers is the best choice. + +- Consider using the method instead of . The conversion method converts as much data as possible and throws an exception if the output buffer is too small. For continuous decoding of a stream, this method is often the best choice. + ]]> @@ -2713,35 +2713,35 @@ The returned 's and When overridden in a derived class, calculates the number of characters produced by decoding a sequence of bytes starting at the specified byte pointer. The number of characters produced by decoding the specified sequence of bytes. - requires to store the resulting characters, you should use the method. To calculate the maximum array size, use the method. The method generally allows allocation of less memory, while the method generally executes faster. - - The method determines how many characters result in decoding a sequence of bytes, and the method performs the actual decoding. The method expects discrete conversions, in contrast to the method, which handles multiple passes on a single input stream. - - Several versions of and are supported. The following are some programming considerations for use of these methods: - -- Your app might need to decode multiple input bytes from a code page and process the bytes using multiple calls. In this case, you probably need to maintain state between calls. - -- If your app handles string outputs, it is recommended to use the method. Since this method must check string length and allocate a buffer, it is slightly slower, but the resulting type is to be preferred. - -- The byte version of allows some fast techniques, particularly with multiple calls to large buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. - -- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports output character buffers is the best choice. - -- Consider using the method instead of . The conversion method converts as much data as possible and throws an exception if the output buffer is too small. For continuous decoding of a stream, this method is often the best choice. - + requires to store the resulting characters, you should use the method. To calculate the maximum array size, use the method. The method generally allows allocation of less memory, while the method generally executes faster. + + The method determines how many characters result in decoding a sequence of bytes, and the method performs the actual decoding. The method expects discrete conversions, in contrast to the method, which handles multiple passes on a single input stream. + + Several versions of and are supported. The following are some programming considerations for use of these methods: + +- Your app might need to decode multiple input bytes from a code page and process the bytes using multiple calls. In this case, you probably need to maintain state between calls. + +- If your app handles string outputs, it is recommended to use the method. Since this method must check string length and allocate a buffer, it is slightly slower, but the resulting type is to be preferred. + +- The byte version of allows some fast techniques, particularly with multiple calls to large buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. + +- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports output character buffers is the best choice. + +- Consider using the method instead of . The conversion method converts as much data as possible and throws an exception if the output buffer is too small. For continuous decoding of a stream, this method is often the best choice. + ]]> is . is less than zero. - A fallback occurred (for more information, see Character Encoding in .NET) - - -and- - + A fallback occurred (for more information, see Character Encoding in .NET) + + -and- + is set to . @@ -2799,52 +2799,52 @@ The returned 's and When overridden in a derived class, calculates the number of characters produced by decoding a sequence of bytes from the specified byte array. The number of characters produced by decoding the specified sequence of bytes. - to store the resulting characters, you should use the method. To calculate the maximum array size, use the method. The method generally allows allocation of less memory, while the method generally executes faster. - - The method determines how many characters result in decoding a sequence of bytes, and the method performs the actual decoding. The method expects discrete conversions, in contrast to the method, which handles multiple passes on a single input stream. - - Several versions of and are supported. The following are some programming considerations for use of these methods: - -- Your app might need to decode multiple input bytes from a code page and process the bytes using multiple calls. In this case, you probably need to maintain state between calls. - -- If your app handles string outputs, it is recommended to use the method. Since this method must check string length and allocate a buffer, it is slightly slower, but the resulting type is to be preferred. - -- The byte version of allows some fast techniques, particularly with multiple calls to large buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. - -- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports output character buffers is the best choice. - -- Consider using the method instead of . The conversion method converts as much data as possible and throws an exception if the output buffer is too small. For continuous decoding of a stream, this method is often the best choice. - -## Examples - The following example converts a string from one encoding to another. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.Convert Example/CPP/convert.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/Overview/convert.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.Convert Example/VB/convert.vb" id="Snippet1"::: - - The following example encodes a string into an array of bytes, and then decodes a range of the bytes into an array of characters. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetCharsIC/CPP/getcharsic.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetCharCount/getcharsic.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetCharsIC/VB/getcharsic.vb" id="Snippet1"::: - + to store the resulting characters, you should use the method. To calculate the maximum array size, use the method. The method generally allows allocation of less memory, while the method generally executes faster. + + The method determines how many characters result in decoding a sequence of bytes, and the method performs the actual decoding. The method expects discrete conversions, in contrast to the method, which handles multiple passes on a single input stream. + + Several versions of and are supported. The following are some programming considerations for use of these methods: + +- Your app might need to decode multiple input bytes from a code page and process the bytes using multiple calls. In this case, you probably need to maintain state between calls. + +- If your app handles string outputs, it is recommended to use the method. Since this method must check string length and allocate a buffer, it is slightly slower, but the resulting type is to be preferred. + +- The byte version of allows some fast techniques, particularly with multiple calls to large buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. + +- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports output character buffers is the best choice. + +- Consider using the method instead of . The conversion method converts as much data as possible and throws an exception if the output buffer is too small. For continuous decoding of a stream, this method is often the best choice. + +## Examples + The following example converts a string from one encoding to another. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.Convert Example/CPP/convert.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/Overview/convert.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.Convert Example/VB/convert.vb" id="Snippet1"::: + + The following example encodes a string into an array of bytes, and then decodes a range of the bytes into an array of characters. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetCharsIC/CPP/getcharsic.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetCharCount/getcharsic.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetCharsIC/VB/getcharsic.vb" id="Snippet1"::: + ]]> is . - or is less than zero. - - -or- - + or is less than zero. + + -or- + and do not denote a valid range in . - A fallback occurred (for more information, see Character Encoding in .NET) - - -and- - + A fallback occurred (for more information, see Character Encoding in .NET) + + -and- + is set to . @@ -2908,45 +2908,45 @@ The returned 's and When overridden in a derived class, decodes all the bytes in the specified byte array into a set of characters. A character array containing the results of decoding the specified sequence of bytes. - gets characters from an input byte sequence. is different than because expects discrete conversions, while is designed for multiple passes on a single input stream. - - If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the or the provided by the method or the method, respectively, of a derived class. - - > [!NOTE] - > This method is intended to operate on Unicode characters, not on arbitrary binary data, such as byte arrays. If you need to encode arbitrary binary data into text, you should use a protocol such as uuencode, which is implemented by methods such as . - - The method determines how many characters result in decoding a sequence of bytes, and the method performs the actual decoding. The method expects discrete conversions, in contrast to the method, which handles multiple passes on a single input stream. - - Several versions of and are supported. The following are some programming considerations for use of these methods: - -- Your app might need to decode multiple input bytes from a code page and process the bytes using multiple calls. In this case, you probably need to maintain state between calls, because byte sequences can be interrupted when processed in batches. (For example, part of an ISO-2022 shift sequence may end one call and continue at the beginning of the next call. will call the fallback for those incomplete sequences, but will remember those sequences for the next call.) - -- If your app handles string outputs, it is recommended to use the method. Since this method must check string length and allocate a buffer, it is slightly slower, but the resulting type is to be preferred. - -- The byte version of allows some fast techniques, particularly with multiple calls to large buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. - -- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports output character buffers is the best choice. - -- Consider using the method instead of . The conversion method converts as much data as possible and throws an exception if the output buffer is too small. For continuous decoding of a stream, this method is often the best choice. - -## Examples - The following example encodes a string into an array of bytes, and then decodes the bytes into an array of characters. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetChars/CPP/getchars.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetCharCount/getchars.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetChars/VB/getchars.vb" id="Snippet1"::: - + gets characters from an input byte sequence. is different than because expects discrete conversions, while is designed for multiple passes on a single input stream. + + If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the or the provided by the method or the method, respectively, of a derived class. + + > [!NOTE] + > This method is intended to operate on Unicode characters, not on arbitrary binary data, such as byte arrays. If you need to encode arbitrary binary data into text, you should use a protocol such as uuencode, which is implemented by methods such as . + + The method determines how many characters result in decoding a sequence of bytes, and the method performs the actual decoding. The method expects discrete conversions, in contrast to the method, which handles multiple passes on a single input stream. + + Several versions of and are supported. The following are some programming considerations for use of these methods: + +- Your app might need to decode multiple input bytes from a code page and process the bytes using multiple calls. In this case, you probably need to maintain state between calls, because byte sequences can be interrupted when processed in batches. (For example, part of an ISO-2022 shift sequence may end one call and continue at the beginning of the next call. will call the fallback for those incomplete sequences, but will remember those sequences for the next call.) + +- If your app handles string outputs, it is recommended to use the method. Since this method must check string length and allocate a buffer, it is slightly slower, but the resulting type is to be preferred. + +- The byte version of allows some fast techniques, particularly with multiple calls to large buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. + +- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports output character buffers is the best choice. + +- Consider using the method instead of . The conversion method converts as much data as possible and throws an exception if the output buffer is too small. For continuous decoding of a stream, this method is often the best choice. + +## Examples + The following example encodes a string into an array of bytes, and then decodes the bytes into an array of characters. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetChars/CPP/getchars.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetCharCount/getchars.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetChars/VB/getchars.vb" id="Snippet1"::: + ]]> is . - A fallback occurred (for more information, see Character Encoding in .NET) - - -and- - + A fallback occurred (for more information, see Character Encoding in .NET) + + -and- + is set to . @@ -3001,27 +3001,27 @@ The returned 's and When overridden in a derived class, decodes all the bytes in the specified read-only byte span into a character span. The actual number of characters written at the span indicated by the parameter. - gets characters from an input byte span. is different than because expects discrete conversions, while is designed for multiple passes on a single input stream. - - If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the or the provided by the method or the method, respectively, of a derived class. - - The method determines how many characters result in decoding a sequence of bytes, and the method performs the actual decoding. The method expects discrete conversions, in contrast to the method, which handles multiple passes on a single input stream. - - Several versions of and are supported. The following are some programming considerations for use of these methods: - -- Your app might need to decode multiple input bytes from a code page and process the bytes using multiple calls. In this case, you probably need to maintain state between calls, because byte sequences can be interrupted when processed in batches. (For example, part of an ISO-2022 shift sequence may end one call and continue at the beginning of the next call. will call the fallback for those incomplete sequences, but will remember those sequences for the next call.) - -- If your app handles string outputs, it is recommended to use the method. Since this method must check string length and allocate a buffer, it is slightly slower, but the resulting type is to be preferred. - -- The byte version of allows some fast techniques, particularly with multiple calls to large buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. - -- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports output character buffers is the best choice. - -- Consider using the method instead of . The conversion method converts as much data as possible and throws an exception if the output buffer is too small. For continuous decoding of a stream, this method is often the best choice. - + gets characters from an input byte span. is different than because expects discrete conversions, while is designed for multiple passes on a single input stream. + + If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the or the provided by the method or the method, respectively, of a derived class. + + The method determines how many characters result in decoding a sequence of bytes, and the method performs the actual decoding. The method expects discrete conversions, in contrast to the method, which handles multiple passes on a single input stream. + + Several versions of and are supported. The following are some programming considerations for use of these methods: + +- Your app might need to decode multiple input bytes from a code page and process the bytes using multiple calls. In this case, you probably need to maintain state between calls, because byte sequences can be interrupted when processed in batches. (For example, part of an ISO-2022 shift sequence may end one call and continue at the beginning of the next call. will call the fallback for those incomplete sequences, but will remember those sequences for the next call.) + +- If your app handles string outputs, it is recommended to use the method. Since this method must check string length and allocate a buffer, it is slightly slower, but the resulting type is to be preferred. + +- The byte version of allows some fast techniques, particularly with multiple calls to large buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. + +- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports output character buffers is the best choice. + +- Consider using the method instead of . The conversion method converts as much data as possible and throws an exception if the output buffer is too small. For continuous decoding of a stream, this method is often the best choice. + ]]> @@ -3077,51 +3077,51 @@ The returned 's and When overridden in a derived class, decodes a sequence of bytes from the specified byte array into a set of characters. A character array containing the results of decoding the specified sequence of bytes. - gets characters from an input byte sequence. is different than because expects discrete conversions, while is designed for multiple passes on a single input stream. - - If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the or the provided by the method or the method, respectively, of a derived class. - - > [!NOTE] - > This method is intended to operate on Unicode characters, not on arbitrary binary data, such as byte arrays. If you need to encode arbitrary binary data into text, you should use a protocol such as uuencode, which is implemented by methods such as . - - The method determines how many characters result in decoding a sequence of bytes, and the method performs the actual decoding. The method expects discrete conversions, in contrast to the method, which handles multiple passes on a single input stream. - - Several versions of and are supported. The following are some programming considerations for use of these methods: - -- Your app might need to decode multiple input bytes from a code page and process the bytes using multiple calls. In this case, you probably need to maintain state between calls, because byte sequences can be interrupted when processed in batches. (For example, part of an ISO-2022 shift sequence may end one call and continue at the beginning of the next call. will call the fallback for those incomplete sequences, but will remember those sequences for the next call.) - -- If your app handles string outputs, it is recommended to use the method. Since this method must check string length and allocate a buffer, it is slightly slower, but the resulting type is to be preferred. - -- The byte version of allows some fast techniques, particularly with multiple calls to large buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. - -- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports output character buffers is the best choice. - -- Consider using the method instead of . The conversion method converts as much data as possible and throws an exception if the output buffer is too small. For continuous decoding of a stream, this method is often the best choice. - -## Examples - The following example encodes a string into an array of bytes, and then decodes a range of the bytes into an array of characters. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetCharsIC/CPP/getcharsic.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetCharCount/getcharsic.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetCharsIC/VB/getcharsic.vb" id="Snippet1"::: - + gets characters from an input byte sequence. is different than because expects discrete conversions, while is designed for multiple passes on a single input stream. + + If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the or the provided by the method or the method, respectively, of a derived class. + + > [!NOTE] + > This method is intended to operate on Unicode characters, not on arbitrary binary data, such as byte arrays. If you need to encode arbitrary binary data into text, you should use a protocol such as uuencode, which is implemented by methods such as . + + The method determines how many characters result in decoding a sequence of bytes, and the method performs the actual decoding. The method expects discrete conversions, in contrast to the method, which handles multiple passes on a single input stream. + + Several versions of and are supported. The following are some programming considerations for use of these methods: + +- Your app might need to decode multiple input bytes from a code page and process the bytes using multiple calls. In this case, you probably need to maintain state between calls, because byte sequences can be interrupted when processed in batches. (For example, part of an ISO-2022 shift sequence may end one call and continue at the beginning of the next call. will call the fallback for those incomplete sequences, but will remember those sequences for the next call.) + +- If your app handles string outputs, it is recommended to use the method. Since this method must check string length and allocate a buffer, it is slightly slower, but the resulting type is to be preferred. + +- The byte version of allows some fast techniques, particularly with multiple calls to large buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. + +- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports output character buffers is the best choice. + +- Consider using the method instead of . The conversion method converts as much data as possible and throws an exception if the output buffer is too small. For continuous decoding of a stream, this method is often the best choice. + +## Examples + The following example encodes a string into an array of bytes, and then decodes a range of the bytes into an array of characters. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetCharsIC/CPP/getcharsic.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetCharCount/getcharsic.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetCharsIC/VB/getcharsic.vb" id="Snippet1"::: + ]]> is . - or is less than zero. - - -or- - + or is less than zero. + + -or- + and do not denote a valid range in . - A fallback occurred (for more information, see Character Encoding in .NET) - - -and- - + A fallback occurred (for more information, see Character Encoding in .NET) + + -and- + is set to . @@ -3197,48 +3197,48 @@ The returned 's and When overridden in a derived class, decodes a sequence of bytes starting at the specified byte pointer into a set of characters that are stored starting at the specified character pointer. The actual number of characters written at the location indicated by the parameter. - requires to store the resulting characters, you should use the method. To calculate the maximum array size, use the method. The method generally allows allocation of less memory, while the method generally executes faster. - - gets characters from an input byte sequence. is different than because expects discrete conversions, while is designed for multiple passes on a single input stream. - - If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the or the object provided by the or the method, respectively, of a derived class. - - > [!NOTE] - > This method is intended to operate on Unicode characters, not on arbitrary binary data, such as byte arrays. If you need to encode arbitrary binary data into text, you should use a protocol such as uuencode, which is implemented by methods such as . - - The method determines how many characters result in decoding a sequence of bytes, and the method performs the actual decoding. The method expects discrete conversions, in contrast to the method, which handles multiple passes on a single input stream. - - Several versions of and are supported. The following are some programming considerations for use of these methods: - -- Your app might need to decode multiple input bytes from a code page and process the bytes using multiple calls. In this case, you probably need to maintain state between calls, because byte sequences can be interrupted when processed in batches. (For example, part of an ISO-2022 shift sequence may end one call and continue at the beginning of the next call. will call the fallback for those incomplete sequences, but will remember those sequences for the next call.) - -- If your app handles string outputs, the method is recommended. Since this method must check string length and allocate a buffer, it is slightly slower, but the resulting type is to be preferred. - -- The byte version of allows some fast techniques, particularly with multiple calls to large buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. - -- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports output character buffers is the best choice. - -- Consider using the method instead of . The conversion method converts as much data as possible and throws an exception if the output buffer is too small. For continuous decoding of a stream, this method is often the best choice. - + requires to store the resulting characters, you should use the method. To calculate the maximum array size, use the method. The method generally allows allocation of less memory, while the method generally executes faster. + + gets characters from an input byte sequence. is different than because expects discrete conversions, while is designed for multiple passes on a single input stream. + + If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the or the object provided by the or the method, respectively, of a derived class. + + > [!NOTE] + > This method is intended to operate on Unicode characters, not on arbitrary binary data, such as byte arrays. If you need to encode arbitrary binary data into text, you should use a protocol such as uuencode, which is implemented by methods such as . + + The method determines how many characters result in decoding a sequence of bytes, and the method performs the actual decoding. The method expects discrete conversions, in contrast to the method, which handles multiple passes on a single input stream. + + Several versions of and are supported. The following are some programming considerations for use of these methods: + +- Your app might need to decode multiple input bytes from a code page and process the bytes using multiple calls. In this case, you probably need to maintain state between calls, because byte sequences can be interrupted when processed in batches. (For example, part of an ISO-2022 shift sequence may end one call and continue at the beginning of the next call. will call the fallback for those incomplete sequences, but will remember those sequences for the next call.) + +- If your app handles string outputs, the method is recommended. Since this method must check string length and allocate a buffer, it is slightly slower, but the resulting type is to be preferred. + +- The byte version of allows some fast techniques, particularly with multiple calls to large buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. + +- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports output character buffers is the best choice. + +- Consider using the method instead of . The conversion method converts as much data as possible and throws an exception if the output buffer is too small. For continuous decoding of a stream, this method is often the best choice. + ]]> - is . - - -or- - + is . + + -or- + is . or is less than zero. is less than the resulting number of characters. - A fallback occurred (for more information, see Character Encoding in .NET) - - -and- - + A fallback occurred (for more information, see Character Encoding in .NET) + + -and- + is set to . @@ -3301,69 +3301,69 @@ The returned 's and When overridden in a derived class, decodes a sequence of bytes from the specified byte array into the specified character array. The actual number of characters written into . - to store the resulting characters, you should use the method. To calculate the maximum array size, use the method. The method generally allows allocation of less memory, while the method generally executes faster. - - gets characters from an input byte sequence. is different than because expects discrete conversions, while is designed for multiple passes on a single input stream. - - If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the or the provided by the method or the method, respectively, of a derived class. - - > [!NOTE] - > This method is intended to operate on Unicode characters, not on arbitrary binary data, such as byte arrays. If you need to encode arbitrary binary data into text, you should use a protocol such as uuencode, which is implemented by methods such as . - - The method determines how many characters result in decoding a sequence of bytes, and the method performs the actual decoding. The method expects discrete conversions, in contrast to the method, which handles multiple passes on a single input stream. - - Several versions of and are supported. The following are some programming considerations for use of these methods: - -- Your app might need to decode multiple input bytes from a code page and process the bytes using multiple calls. In this case, you probably need to maintain state between calls, because byte sequences can be interrupted when processed in batches. (For example, part of an ISO-2022 shift sequence may end one call and continue at the beginning of the next call. will call the fallback for those incomplete sequences, but will remember those sequences for the next call.) - -- If your app handles string outputs, the method is recommended. Since this method must check string length and allocate a buffer, it is slightly slower, but the resulting type is to be preferred. - -- The byte version of allows some fast techniques, particularly with multiple calls to large buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. - -- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports output character buffers is the best choice. - -- Consider using the method instead of . The conversion method converts as much data as possible and throws an exception if the output buffer is too small. For continuous decoding of a stream, this method is often the best choice. - -## Examples - The following example converts a string from one encoding to another. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.Convert Example/CPP/convert.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/Overview/convert.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.Convert Example/VB/convert.vb" id="Snippet1"::: - - The following example encodes a string into an array of bytes, and then decodes a range of the bytes into an array of characters. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetCharsIC/CPP/getcharsic.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetCharCount/getcharsic.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetCharsIC/VB/getcharsic.vb" id="Snippet1"::: - + to store the resulting characters, you should use the method. To calculate the maximum array size, use the method. The method generally allows allocation of less memory, while the method generally executes faster. + + gets characters from an input byte sequence. is different than because expects discrete conversions, while is designed for multiple passes on a single input stream. + + If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the or the provided by the method or the method, respectively, of a derived class. + + > [!NOTE] + > This method is intended to operate on Unicode characters, not on arbitrary binary data, such as byte arrays. If you need to encode arbitrary binary data into text, you should use a protocol such as uuencode, which is implemented by methods such as . + + The method determines how many characters result in decoding a sequence of bytes, and the method performs the actual decoding. The method expects discrete conversions, in contrast to the method, which handles multiple passes on a single input stream. + + Several versions of and are supported. The following are some programming considerations for use of these methods: + +- Your app might need to decode multiple input bytes from a code page and process the bytes using multiple calls. In this case, you probably need to maintain state between calls, because byte sequences can be interrupted when processed in batches. (For example, part of an ISO-2022 shift sequence may end one call and continue at the beginning of the next call. will call the fallback for those incomplete sequences, but will remember those sequences for the next call.) + +- If your app handles string outputs, the method is recommended. Since this method must check string length and allocate a buffer, it is slightly slower, but the resulting type is to be preferred. + +- The byte version of allows some fast techniques, particularly with multiple calls to large buffers. Bear in mind, however, that this method version is sometimes unsafe, since pointers are required. + +- If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports output character buffers is the best choice. + +- Consider using the method instead of . The conversion method converts as much data as possible and throws an exception if the output buffer is too small. For continuous decoding of a stream, this method is often the best choice. + +## Examples + The following example converts a string from one encoding to another. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.Convert Example/CPP/convert.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/Overview/convert.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.Convert Example/VB/convert.vb" id="Snippet1"::: + + The following example encodes a string into an array of bytes, and then decodes a range of the bytes into an array of characters. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetCharsIC/CPP/getcharsic.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetCharCount/getcharsic.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetCharsIC/VB/getcharsic.vb" id="Snippet1"::: + ]]> - is . - - -or- - + is . + + -or- + is . - or or is less than zero. - - -or- - - and do not denote a valid range in . - - -or- - + or or is less than zero. + + -or- + + and do not denote a valid range in . + + -or- + is not a valid index in . does not have enough capacity from to the end of the array to accommodate the resulting characters. - A fallback occurred (for more information, see Character Encoding in .NET) - - -and- - + A fallback occurred (for more information, see Character Encoding in .NET) + + -and- + is set to . @@ -3415,11 +3415,11 @@ The returned 's and When overridden in a derived class, obtains a decoder that converts an encoded sequence of bytes into a sequence of characters. A that converts an encoded sequence of bytes into a sequence of characters. - method converts sequential blocks of bytes into sequential blocks of characters, in a manner similar to the method of this class. However, a maintains state information between calls so it correctly decodes byte sequences that span blocks. The also preserves trailing bytes at the end of data blocks and uses the trailing bytes in the next decoding operation. Therefore, and are useful for network transmission and file operations, because those operations often deal with blocks of data instead of a complete data stream. - + method converts sequential blocks of bytes into sequential blocks of characters, in a manner similar to the method of this class. However, a maintains state information between calls so it correctly decodes byte sequences that span blocks. The also preserves trailing bytes at the end of data blocks and uses the trailing bytes in the next decoding operation. Therefore, and are useful for network transmission and file operations, because those operations often deal with blocks of data instead of a complete data stream. + ]]> @@ -3477,11 +3477,11 @@ The returned 's and When overridden in a derived class, obtains an encoder that converts a sequence of Unicode characters into an encoded sequence of bytes. A that converts a sequence of Unicode characters into an encoded sequence of bytes. - method converts sequential blocks of characters into sequential blocks of bytes, in a manner similar to the method of this class. However, a maintains state information between calls so it correctly encodes character sequences that span blocks. The also preserves trailing characters at the end of data blocks and uses the trailing characters in the next encoding operation. For example, a data block might end with an unmatched high surrogate, and the matching low surrogate might be in the next data block. Therefore, and are useful for network transmission and file operations, because those operations often deal with blocks of data instead of a complete data stream. - + method converts sequential blocks of characters into sequential blocks of bytes, in a manner similar to the method of this class. However, a maintains state information between calls so it correctly encodes character sequences that span blocks. The also preserves trailing characters at the end of data blocks and uses the trailing characters in the next encoding operation. For example, a data block might end with an unmatched high surrogate, and the matching low surrogate might be in the next data block. Therefore, and are useful for network transmission and file operations, because those operations often deal with blocks of data instead of a complete data stream. + ]]> @@ -3551,47 +3551,47 @@ The returned 's and - The code page identifier of the preferred encoding. For a list of possible values, see . - - -or- - + The code page identifier of the preferred encoding. For a list of possible values, see . + + -or- + 0 (zero), to use the default encoding. Returns the encoding associated with the specified code page identifier. The encoding that is associated with the specified code page. - overload. - - In .NET Framework, the method relies on the underlying platform to support most code pages. However, .NET Framework natively supports some encodings. For a list of code pages, see [List of encodings](/dotnet/api/system.text.encoding#list-of-encodings). In .NET Core, the method returns the encodings natively supported by .NET Core. On both .NET implementations, you can call the method to get an array of objects that contains information about all available encodings. - - In addition to the encodings that are natively available on .NET Core or that are intrinsically supported on a specific platform version of .NET Framework, the method returns any additional encodings that are made available by registering an object. If the same encoding has been registered by multiple objects, this method returns the last one registered. - -You can also supply a value of 0 for the `codepage` argument. Its precise behavior depends on whether any encodings have been made available by registering an object: - -- If one or more encoding providers have been registered, it returns the encoding of the last registered provider that has chosen to return a encoding when the method is passed a `codepage` argument of 0. - -- On .NET Framework, if no encoding provider has been registered, if the is the registered encoding provider, or if no registered encoding provider handles a `codepage` value of 0, it returns the operating system's active code page. To determine the active code page on Windows systems, call the Windows [GetACP](/windows/win32/api/winnls/nf-winnls-getacp) function from .NET Framework. - -- On .NET Core, if no encoding provider has been registered or if no registered encoding provider handles a `codepage` value of 0, it returns the . - -> [!NOTE] -> - Some unsupported code pages cause an to be thrown, whereas others cause a . Therefore, your code must catch all exceptions indicated in the Exceptions section. -> - In .NET 5 and later versions, the code page identifier `65000`, which represents UTF-7, is not supported. - -> [!NOTE] -> The ANSI code pages can be different on different computers and can change on a single computer, leading to data corruption. For this reason, if the active code page is an ANSI code page, encoding and decoding data using the default code page returned by `Encoding.GetEncoding(0)` is not recommended. For the most consistent results, you should use a Unicode encoding, such as UTF-8 (code page 65001) or UTF-16, instead of a specific code page. - - returns a cached instance with default settings. You should use the constructors of derived classes to get an instance with different settings. For example, the class provides a constructor that lets you enable error detection. - -## Examples - The following example gets two instances of the same encoding (one by code page and another by name), and checks their equality. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.Equals/CPP/equals.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/Equals/equals.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.Equals/VB/equals.vb" id="Snippet1"::: - + overload. + + In .NET Framework, the method relies on the underlying platform to support most code pages. However, .NET Framework natively supports some encodings. For a list of code pages, see [List of encodings](/dotnet/api/system.text.encoding#list-of-encodings). In .NET Core, the method returns the encodings natively supported by .NET Core. On both .NET implementations, you can call the method to get an array of objects that contains information about all available encodings. + + In addition to the encodings that are natively available on .NET Core or that are intrinsically supported on a specific platform version of .NET Framework, the method returns any additional encodings that are made available by registering an object. If the same encoding has been registered by multiple objects, this method returns the last one registered. + +You can also supply a value of 0 for the `codepage` argument. Its precise behavior depends on whether any encodings have been made available by registering an object: + +- If one or more encoding providers have been registered, it returns the encoding of the last registered provider that has chosen to return a encoding when the method is passed a `codepage` argument of 0. + +- On .NET Framework, if no encoding provider has been registered, if the is the registered encoding provider, or if no registered encoding provider handles a `codepage` value of 0, it returns the operating system's active code page. To determine the active code page on Windows systems, call the Windows [GetACP](/windows/win32/api/winnls/nf-winnls-getacp) function from .NET Framework. + +- On .NET Core, if no encoding provider has been registered or if no registered encoding provider handles a `codepage` value of 0, it returns the . + +> [!NOTE] +> - Some unsupported code pages cause an to be thrown, whereas others cause a . Therefore, your code must catch all exceptions indicated in the Exceptions section. +> - In .NET 5 and later versions, the code page identifier `65000`, which represents UTF-7, is not supported. + +> [!NOTE] +> The ANSI code pages can be different on different computers and can change on a single computer, leading to data corruption. For this reason, if the active code page is an ANSI code page, encoding and decoding data using the default code page returned by `Encoding.GetEncoding(0)` is not recommended. For the most consistent results, you should use a Unicode encoding, such as UTF-8 (code page 65001) or UTF-16, instead of a specific code page. + + returns a cached instance with default settings. You should use the constructors of derived classes to get an instance with different settings. For example, the class provides a constructor that lets you enable error detection. + +## Examples + The following example gets two instances of the same encoding (one by code page and another by name), and checks their equality. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.Equals/CPP/equals.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/Equals/equals.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.Equals/VB/equals.vb" id="Snippet1"::: + ]]> @@ -3660,36 +3660,36 @@ You can also supply a value of 0 for the `codepage` argument. Its precise behavi Returns the encoding associated with the specified code page name. The encoding associated with the specified code page. - overload. - -In .NET Framework, the method relies on the underlying platform to support most code pages. However, .NET Framework natively supports some encodings. For a list of code pages, see [List of encodings](/dotnet/api/system.text.encoding#list-of-encodings). In .NET Core, the method returns the encodings natively supported by .NET Core. On both .NET implementations, you can call the method to get an array of objects that contains information about all available encodings. - - In addition to the encodings that are natively available on .NET Core or that are intrinsically supported on a specific platform version of .NET Framework, the method returns any additional encodings that are made available by registering an object. If the same encoding has been registered by multiple objects, this method returns the last one registered. - -In .NET 5 and later versions, the code page name `utf-7` is not supported. - -> [!NOTE] -> The ANSI code pages can be different on different computers, or they can be changed for a single computer, leading to data corruption. For the most consistent results, use Unicode, such as UTF-8 (code page 65001) or UTF-16, instead of a specific code page. - - returns a cached instance with default settings. You should use the constructors of derived classes to get an instance with different settings. For example, the class provides a constructor that lets you enable error detection. - -## Examples - The following example gets two instances of the same encoding (one by code page and another by name), and checks their equality. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.Equals/CPP/equals.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/Equals/equals.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.Equals/VB/equals.vb" id="Snippet1"::: - + overload. + +In .NET Framework, the method relies on the underlying platform to support most code pages. However, .NET Framework natively supports some encodings. For a list of code pages, see [List of encodings](/dotnet/api/system.text.encoding#list-of-encodings). In .NET Core, the method returns the encodings natively supported by .NET Core. On both .NET implementations, you can call the method to get an array of objects that contains information about all available encodings. + + In addition to the encodings that are natively available on .NET Core or that are intrinsically supported on a specific platform version of .NET Framework, the method returns any additional encodings that are made available by registering an object. If the same encoding has been registered by multiple objects, this method returns the last one registered. + +In .NET 5 and later versions, the code page name `utf-7` is not supported. + +> [!NOTE] +> The ANSI code pages can be different on different computers, or they can be changed for a single computer, leading to data corruption. For the most consistent results, use Unicode, such as UTF-8 (code page 65001) or UTF-16, instead of a specific code page. + + returns a cached instance with default settings. You should use the constructors of derived classes to get an instance with different settings. For example, the class provides a constructor that lets you enable error detection. + +## Examples + The following example gets two instances of the same encoding (one by code page and another by name), and checks their equality. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.Equals/CPP/equals.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/Equals/equals.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.Equals/VB/equals.vb" id="Snippet1"::: + ]]> - is not a valid code page name. - - -or- - + is not a valid code page name. + + -or- + The code page indicated by is not supported by the underlying platform. @@ -3746,50 +3746,50 @@ In .NET 5 and later versions, the code page name `utf-7` is not supported. - The code page identifier of the preferred encoding. For a list of possible values, see . - - -or- - + The code page identifier of the preferred encoding. For a list of possible values, see . + + -or- + 0 (zero), to use the default encoding. An object that provides an error-handling procedure when a character cannot be encoded with the current encoding. An object that provides an error-handling procedure when a byte sequence cannot be decoded with the current encoding. Returns the encoding associated with the specified code page identifier. Parameters specify an error handler for characters that cannot be encoded and byte sequences that cannot be decoded. The encoding that is associated with the specified code page. - [!NOTE] -> - Some unsupported code pages cause the exception to be thrown, whereas others cause . Therefore, your code must catch all exceptions indicated in the Exceptions section. -> - In .NET 5 and later versions, the code page identifier `65000`, which represents UTF-7, is not supported. - -In .NET Framework, the method relies on the underlying platform to support most code pages. However, .NET Framework natively supports some encodings. For a list of code pages, see [List of encodings](/dotnet/api/system.text.encoding#list-of-encodings). In .NET Core, the method returns the encodings natively supported by .NET Core. On both .NET implementations, you can call the method to get an array of objects that contains information about all available encodings. - - In addition to the encodings that are natively available on .NET Core or that are intrinsically supported on a specific platform version of .NET Framework, the method returns any additional encodings that are made available by registering an object. If the same encoding has been registered by multiple objects, this method returns the last one registered. - -You can also supply a value of 0 for the `codepage` argument. Its precise behavior depends on whether any encodings have been made available by registering an object: - -- If one or more encoding providers have been registered, it returns the encoding of the last registered provider that has chosen to return a encoding when the method is passed a `codepage` argument of 0. - -- On .NET Framework, if no encoding provider has been registered, if the is the registered encoding provider, or if no registered encoding provider handles a `codepage` value of 0, it returns the active code page. - -- On .NET Core, if no encoding provider has been registered or if no registered encoding provider handles a `codepage` value of 0, it returns the encoding. - -> [!NOTE] -> The ANSI code pages can be different on different computers and can change on a single computer, leading to data corruption. For this reason, if the active code page is an ANSI code page, encoding and decoding data using the default code page returned by `Encoding.GetEncoding(0)` is not recommended. For the most consistent results, you should use Unicode, such as UTF-8 (code page 65001) or UTF-16, instead of a specific code page. - - To get the encoding associated with the active code page, you can either supply a value of 0 for the `codepage` argument or, if your code is running on .NET Framework, retrieve the value of the property. To determine the current active code page, call the Windows [GetACP](/windows/win32/api/winnls/nf-winnls-getacp) function from .NET Framework. - - returns a cached instance with default settings. You should use the constructors of derived classes to get an instance with different settings. For example, the class provides a constructor that lets you enable error detection. - -## Examples - The following example demonstrates the method. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/sys.txt.fallbackEncRpl/cpp/fallEncRpl.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/EncoderReplacementFallback/Overview/fallEncRpl.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/sys.txt.fallbackEncRpl/vb/fallEncRpl.vb" id="Snippet1"::: - + [!NOTE] +> - Some unsupported code pages cause the exception to be thrown, whereas others cause . Therefore, your code must catch all exceptions indicated in the Exceptions section. +> - In .NET 5 and later versions, the code page identifier `65000`, which represents UTF-7, is not supported. + +In .NET Framework, the method relies on the underlying platform to support most code pages. However, .NET Framework natively supports some encodings. For a list of code pages, see [List of encodings](/dotnet/api/system.text.encoding#list-of-encodings). In .NET Core, the method returns the encodings natively supported by .NET Core. On both .NET implementations, you can call the method to get an array of objects that contains information about all available encodings. + + In addition to the encodings that are natively available on .NET Core or that are intrinsically supported on a specific platform version of .NET Framework, the method returns any additional encodings that are made available by registering an object. If the same encoding has been registered by multiple objects, this method returns the last one registered. + +You can also supply a value of 0 for the `codepage` argument. Its precise behavior depends on whether any encodings have been made available by registering an object: + +- If one or more encoding providers have been registered, it returns the encoding of the last registered provider that has chosen to return a encoding when the method is passed a `codepage` argument of 0. + +- On .NET Framework, if no encoding provider has been registered, if the is the registered encoding provider, or if no registered encoding provider handles a `codepage` value of 0, it returns the active code page. + +- On .NET Core, if no encoding provider has been registered or if no registered encoding provider handles a `codepage` value of 0, it returns the encoding. + +> [!NOTE] +> The ANSI code pages can be different on different computers and can change on a single computer, leading to data corruption. For this reason, if the active code page is an ANSI code page, encoding and decoding data using the default code page returned by `Encoding.GetEncoding(0)` is not recommended. For the most consistent results, you should use Unicode, such as UTF-8 (code page 65001) or UTF-16, instead of a specific code page. + + To get the encoding associated with the active code page, you can either supply a value of 0 for the `codepage` argument or, if your code is running on .NET Framework, retrieve the value of the property. To determine the current active code page, call the Windows [GetACP](/windows/win32/api/winnls/nf-winnls-getacp) function from .NET Framework. + + returns a cached instance with default settings. You should use the constructors of derived classes to get an instance with different settings. For example, the class provides a constructor that lets you enable error detection. + +## Examples + The following example demonstrates the method. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/sys.txt.fallbackEncRpl/cpp/fallEncRpl.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/EncoderReplacementFallback/Overview/fallEncRpl.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/sys.txt.fallbackEncRpl/vb/fallEncRpl.vb" id="Snippet1"::: + ]]> @@ -3860,35 +3860,35 @@ You can also supply a value of 0 for the `codepage` argument. Its precise behavi Returns the encoding associated with the specified code page name. Parameters specify an error handler for characters that cannot be encoded and byte sequences that cannot be decoded. The encoding that is associated with the specified code page. - method relies on the underlying platform to support most code pages. However, .NET Framework natively supports some encodings. For a list of code pages, see [List of encodings](/dotnet/api/system.text.encoding#list-of-encodings). In .NET Core, the method returns the encodings natively supported by .NET Core. On both .NET implementations, you can call the method to get an array of objects that contains information about all available encodings. - - In addition to the encodings that are natively available on .NET Core or that are intrinsically supported on a specific platform version of .NET Framework, the method returns any additional encodings that are made available by registering an object. If the same encoding has been registered by multiple objects, this method returns the last one registered. - -In .NET 5 and later versions, the code page name `utf-7` is not supported. - -> [!NOTE] -> The ANSI code pages can be different on different computers and can change on a single computer, leading to data corruption. For the most consistent results, you should use a Unicode encoding, such as UTF-8 (code page 65001) or UTF-16, instead of a specific code page. - - returns a cached instance with default settings. You should use the constructors of derived classes to get an instance with different settings. For example, the class provides a constructor that lets you enable error detection. - -## Examples - The following example demonstrates the method. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/sys.txt.fallbackEncRpl/cpp/fallEncRpl.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/EncoderReplacementFallback/Overview/fallEncRpl.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/sys.txt.fallbackEncRpl/vb/fallEncRpl.vb" id="Snippet1"::: - + method relies on the underlying platform to support most code pages. However, .NET Framework natively supports some encodings. For a list of code pages, see [List of encodings](/dotnet/api/system.text.encoding#list-of-encodings). In .NET Core, the method returns the encodings natively supported by .NET Core. On both .NET implementations, you can call the method to get an array of objects that contains information about all available encodings. + + In addition to the encodings that are natively available on .NET Core or that are intrinsically supported on a specific platform version of .NET Framework, the method returns any additional encodings that are made available by registering an object. If the same encoding has been registered by multiple objects, this method returns the last one registered. + +In .NET 5 and later versions, the code page name `utf-7` is not supported. + +> [!NOTE] +> The ANSI code pages can be different on different computers and can change on a single computer, leading to data corruption. For the most consistent results, you should use a Unicode encoding, such as UTF-8 (code page 65001) or UTF-16, instead of a specific code page. + + returns a cached instance with default settings. You should use the constructors of derived classes to get an instance with different settings. For example, the class provides a constructor that lets you enable error detection. + +## Examples + The following example demonstrates the method. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/sys.txt.fallbackEncRpl/cpp/fallEncRpl.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/EncoderReplacementFallback/Overview/fallEncRpl.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/sys.txt.fallbackEncRpl/vb/fallEncRpl.vb" id="Snippet1"::: + ]]> - is not a valid code page name. - - -or- - + is not a valid code page name. + + -or- + The code page indicated by is not supported by the underlying platform. @@ -3937,33 +3937,33 @@ In .NET 5 and later versions, the code page name `utf-7` is not supported. Returns an array that contains all encodings. An array that contains all encodings. - . - -> [!NOTE] -> In .NET 5 and later versions, the list of supported encodings that returns includes any additional encodings made available by any implementations that were registered by calling . -> -> In .NET Framework and .NET Core, the returned list of supported encodings *does not* include these additional encodings. -> -> Therefore, if running on .NET Framework or .NET 5+ with the code pages encoding provider registered via `Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);`, you'll get a result similar to the list in the previous code example. If running on .NET Core versions up to version 3.x, you'll get the basic list. - - On .NET Framework, encodings 50220 and 50222 are both associated with the name "iso-2022-jp", but they are not identical. Encoding 50220 converts half-width Katakana characters to full-width Katakana characters, whereas encoding 50222 uses a shift-in/shift-out sequence to encode half-width Katakana characters. The display name for encoding 50222 is "Japanese (JIS-Allow 1 byte Kana - SO/SI)" to distinguish it from encoding 50220, which has the display name "Japanese (JIS)". - - If you request the encoding name "iso-2022-jp", .NET Framework returns encoding 50220. However, the encoding that is appropriate for your app depends on the preferred treatment of the half-width Katakana characters. - - To get a specific encoding, use the method. - - is sometimes used to present the user with a list of encodings in a File **Save as** dialog box. However, many non-Unicode encodings are either incomplete and translate many characters to "?", or have subtly different behavior on different platforms. Consider using UTF-8 or UTF-16 as the default. - -## Examples - The following example checks the values of the Boolean properties of each encoding. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.IsProps/CPP/isprops.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetEncodings/isprops.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.IsProps/VB/isprops.vb" id="Snippet1"::: - + . + +> [!NOTE] +> In .NET 5 and later versions, the list of supported encodings that returns includes any additional encodings made available by any implementations that were registered by calling . +> +> In .NET Framework and .NET Core, the returned list of supported encodings *does not* include these additional encodings. +> +> Therefore, if running on .NET Framework or .NET 5+ with the code pages encoding provider registered via `Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);`, you'll get a result similar to the list in the previous code example. If running on .NET Core versions up to version 3.x, you'll get the basic list. + + On .NET Framework, encodings 50220 and 50222 are both associated with the name "iso-2022-jp", but they are not identical. Encoding 50220 converts half-width Katakana characters to full-width Katakana characters, whereas encoding 50222 uses a shift-in/shift-out sequence to encode half-width Katakana characters. The display name for encoding 50222 is "Japanese (JIS-Allow 1 byte Kana - SO/SI)" to distinguish it from encoding 50220, which has the display name "Japanese (JIS)". + + If you request the encoding name "iso-2022-jp", .NET Framework returns encoding 50220. However, the encoding that is appropriate for your app depends on the preferred treatment of the half-width Katakana characters. + + To get a specific encoding, use the method. + + is sometimes used to present the user with a list of encodings in a File **Save as** dialog box. However, many non-Unicode encodings are either incomplete and translate many characters to "?", or have subtly different behavior on different platforms. Consider using UTF-8 or UTF-16 as the default. + +## Examples + The following example checks the values of the Boolean properties of each encoding. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.IsProps/CPP/isprops.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetEncodings/isprops.cs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.IsProps/VB/isprops.vb" id="Snippet1"::: + ]]> @@ -4064,39 +4064,39 @@ In .NET 5 and later versions, the code page name `utf-7` is not supported. When overridden in a derived class, calculates the maximum number of bytes produced by encoding the specified number of characters. The maximum number of bytes produced by encoding the specified number of characters. - objects that represent the Unicode characters to encode, because .NET internally uses UTF-16 to represent Unicode characters. Consequently, most Unicode characters can be represented by one object, but a Unicode character represented by a surrogate pair, for example, requires two objects. - - To calculate the exact array size required by to store the resulting bytes, you should use the method. To calculate the maximum array size, use the method. The method generally allows allocation of less memory, while the method generally executes faster. - - retrieves a worst-case number, including the worst case for the currently selected . If a fallback is chosen with a potentially large string, retrieves large values, particularly in cases where the worst case for the encoding involves switching modes for every character. For example, this can happen for ISO-2022-JP. For more information, see the blog post "[What's with Encoding.GetMaxByteCount() and Encoding.GetMaxCharCount()?](https://blogs.msdn.microsoft.com/shawnste/2005/03/02/whats-with-encoding-getmaxbytecount-and-encoding-getmaxcharcount/). - - In most cases, this method retrieves reasonable values for small strings. For large strings, you might have to choose between using very large buffers and catching errors in the rare case when a more reasonable buffer is too small. You might also want to consider a different approach using or . - - When using , you should allocate the output buffer based on the maximum size of the input buffer. If the output buffer is constrained in size, you might use the method. - - Note that considers potential leftover surrogates from a previous decoder operation. Because of the decoder, passing a value of 1 to the method retrieves 2 for a single-byte encoding, such as ASCII. You should use the property if this information is necessary. - -> [!NOTE] -> `GetMaxByteCount(N)` is not necessarily the same value as `N* GetMaxByteCount(1)`. - -## Examples - The following example determines the number of bytes required to encode a character array, encodes the characters, and displays the resulting bytes. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArr/CPP/getbytes_chararr.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/BigEndianUnicode/getbytes_chararr.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArr/VB/getbytes_chararr.vb" id="Snippet1"::: - + objects that represent the Unicode characters to encode, because .NET internally uses UTF-16 to represent Unicode characters. Consequently, most Unicode characters can be represented by one object, but a Unicode character represented by a surrogate pair, for example, requires two objects. + + To calculate the exact array size required by to store the resulting bytes, you should use the method. To calculate the maximum array size, use the method. The method generally allows allocation of less memory, while the method generally executes faster. + + retrieves a worst-case number, including the worst case for the currently selected . If a fallback is chosen with a potentially large string, retrieves large values, particularly in cases where the worst case for the encoding involves switching modes for every character. For example, this can happen for ISO-2022-JP. For more information, see the blog post "[What's with Encoding.GetMaxByteCount() and Encoding.GetMaxCharCount()?](https://blogs.msdn.microsoft.com/shawnste/2005/03/02/whats-with-encoding-getmaxbytecount-and-encoding-getmaxcharcount/). + + In most cases, this method retrieves reasonable values for small strings. For large strings, you might have to choose between using very large buffers and catching errors in the rare case when a more reasonable buffer is too small. You might also want to consider a different approach using or . + + When using , you should allocate the output buffer based on the maximum size of the input buffer. If the output buffer is constrained in size, you might use the method. + + Note that considers potential leftover surrogates from a previous decoder operation. Because of the decoder, passing a value of 1 to the method retrieves 2 for a single-byte encoding, such as ASCII. You should use the property if this information is necessary. + +> [!NOTE] +> `GetMaxByteCount(N)` is not necessarily the same value as `N* GetMaxByteCount(1)`. + +## Examples + The following example determines the number of bytes required to encode a character array, encodes the characters, and displays the resulting bytes. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArr/CPP/getbytes_chararr.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/BigEndianUnicode/getbytes_chararr.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArr/VB/getbytes_chararr.vb" id="Snippet1"::: + ]]> is less than zero. - A fallback occurred (for more information, see Character Encoding in .NET) - - -and- - + A fallback occurred (for more information, see Character Encoding in .NET) + + -and- + is set to . All implementations must guarantee that no buffer overflow exceptions occur if buffers are sized according to the results of this method's calculations. @@ -4153,39 +4153,39 @@ In .NET 5 and later versions, the code page name `utf-7` is not supported. When overridden in a derived class, calculates the maximum number of characters produced by decoding the specified number of bytes. The maximum number of characters produced by decoding the specified number of bytes. - to store the resulting characters, you should use the method. To calculate the maximum array size, use the method. The method generally allows allocation of less memory, while the method generally executes faster. - - retrieves a worst-case number, including the worst case for the currently selected . If a fallback is chosen with a potentially large string, retrieves large values. - - In most cases, this method retrieves reasonable numbers for small strings. For large strings, you might have to choose between using very large buffers and catching errors in the rare case that a more reasonable buffer is too small. You might also want to consider a different approach using or . - - has no relation to . If you needs a similar function to use with , you should use . - - When using , you should allocate the output buffer based on the maximum size of the input buffer. If the output buffer is constrained in size, you might use the method. - - Note that considers the worst case for leftover bytes from a previous encoder operation. For most code pages, passing a value of 0 to this method retrieves values greater than or equal to 1. - -> [!NOTE] -> `GetMaxCharCount(N)` is not necessarily the same value as `N* GetMaxCharCount(1)`. - -## Examples - The following example encodes a string into an array of bytes, and then decodes the bytes into an array of characters. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetChars/CPP/getchars.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetCharCount/getchars.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetChars/VB/getchars.vb" id="Snippet1"::: - + to store the resulting characters, you should use the method. To calculate the maximum array size, use the method. The method generally allows allocation of less memory, while the method generally executes faster. + + retrieves a worst-case number, including the worst case for the currently selected . If a fallback is chosen with a potentially large string, retrieves large values. + + In most cases, this method retrieves reasonable numbers for small strings. For large strings, you might have to choose between using very large buffers and catching errors in the rare case that a more reasonable buffer is too small. You might also want to consider a different approach using or . + + has no relation to . If you needs a similar function to use with , you should use . + + When using , you should allocate the output buffer based on the maximum size of the input buffer. If the output buffer is constrained in size, you might use the method. + + Note that considers the worst case for leftover bytes from a previous encoder operation. For most code pages, passing a value of 0 to this method retrieves values greater than or equal to 1. + +> [!NOTE] +> `GetMaxCharCount(N)` is not necessarily the same value as `N* GetMaxCharCount(1)`. + +## Examples + The following example encodes a string into an array of bytes, and then decodes the bytes into an array of characters. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetChars/CPP/getchars.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetCharCount/getchars.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetChars/VB/getchars.vb" id="Snippet1"::: + ]]> is less than zero. - A fallback occurred (for more information, see Character Encoding in .NET) - - -and- - + A fallback occurred (for more information, see Character Encoding in .NET) + + -and- + is set to . All implementations must guarantee that no buffer overflow exceptions occur if buffers are sized according to the results of this method's calculations. @@ -4238,47 +4238,47 @@ In .NET 5 and later versions, the code page name `utf-7` is not supported. When overridden in a derived class, returns a sequence of bytes that specifies the encoding used. - A byte array containing a sequence of bytes that specifies the encoding used. - - -or- - + A byte array containing a sequence of bytes that specifies the encoding used. + + -or- + A byte array of length zero, if a preamble is not required. - object provides a preamble that is an array of bytes that can be prefixed to the sequence of bytes resulting from the encoding process. If the preamble contains a byte order mark (in Unicode, code point U+FEFF), it helps the decoder determine the byte order and the transformation format or UTF. - - The Unicode byte order mark (BOM) is serialized as follows (in hexadecimal): - -- UTF-8: EF BB BF - -- UTF-16 big endian byte order: FE FF - -- UTF-16 little endian byte order: FF FE - -- UTF-32 big endian byte order: 00 00 FE FF - -- UTF-32 little endian byte order: FF FE 00 00 - - You should use the BOM, because it provides nearly certain identification of an encoding for files that otherwise have lost reference to the object, for example, untagged or improperly tagged web data or random text files stored when a business did not have international concerns or other data. Often user problems might be avoided if data is consistently and properly tagged, preferably in UTF-8 or UTF-16. - - For standards that provide an encoding type, a BOM is somewhat redundant. However, it can be used to help a server send the correct encoding header. Alternatively, it can be used as a fallback in case the encoding is otherwise lost. - - There are some disadvantages to using a BOM. For example, knowing how to limit the database fields that use a BOM can be difficult. Concatenation of files can be a problem also, for example, when files are merged in such a way that an unnecessary character can end up in the middle of data. In spite of the few disadvantages, however, the use of a BOM is highly recommended. - - For more information on byte order and the byte order mark, see The Unicode Standard at the [Unicode home page](https://home.unicode.org/). - -> [!CAUTION] -> To ensure that the encoded bytes are decoded properly, you should prefix encoded bytes with a preamble. However, most encodings do not provide a preamble. To ensure that the encoded bytes are decoded properly, you should use a Unicode encoding, that is, , , or , with a preamble. - -## Examples - The following example determines the byte order of the encoding based on the preamble. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetPreamble Example/CPP/preamble.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetPreamble/preamble.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetPreamble Example/VB/preamble.vb" id="Snippet1"::: - + object provides a preamble that is an array of bytes that can be prefixed to the sequence of bytes resulting from the encoding process. If the preamble contains a byte order mark (in Unicode, code point U+FEFF), it helps the decoder determine the byte order and the transformation format or UTF. + + The Unicode byte order mark (BOM) is serialized as follows (in hexadecimal): + +- UTF-8: EF BB BF + +- UTF-16 big endian byte order: FE FF + +- UTF-16 little endian byte order: FF FE + +- UTF-32 big endian byte order: 00 00 FE FF + +- UTF-32 little endian byte order: FF FE 00 00 + + You should use the BOM, because it provides nearly certain identification of an encoding for files that otherwise have lost reference to the object, for example, untagged or improperly tagged web data or random text files stored when a business did not have international concerns or other data. Often user problems might be avoided if data is consistently and properly tagged, preferably in UTF-8 or UTF-16. + + For standards that provide an encoding type, a BOM is somewhat redundant. However, it can be used to help a server send the correct encoding header. Alternatively, it can be used as a fallback in case the encoding is otherwise lost. + + There are some disadvantages to using a BOM. For example, knowing how to limit the database fields that use a BOM can be difficult. Concatenation of files can be a problem also, for example, when files are merged in such a way that an unnecessary character can end up in the middle of data. In spite of the few disadvantages, however, the use of a BOM is highly recommended. + + For more information on byte order and the byte order mark, see The Unicode Standard at the [Unicode home page](https://home.unicode.org/). + +> [!CAUTION] +> To ensure that the encoded bytes are decoded properly, you should prefix encoded bytes with a preamble. However, most encodings do not provide a preamble. To ensure that the encoded bytes are decoded properly, you should use a Unicode encoding, that is, , , or , with a preamble. + +## Examples + The following example determines the byte order of the encoding based on the preamble. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetPreamble Example/CPP/preamble.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetPreamble/preamble.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetPreamble Example/VB/preamble.vb" id="Snippet1"::: + ]]> @@ -4338,43 +4338,43 @@ In .NET 5 and later versions, the code page name `utf-7` is not supported. When overridden in a derived class, decodes all the bytes in the specified byte array into a string. A string that contains the results of decoding the specified sequence of bytes. - object returned by the method of a derived class. - - See the Remarks section of the reference topic for a discussion of decoding techniques and considerations. - - Note that the precise behavior of the method for a particular implementation depends on the fallback strategy defined for that object. For more information, see the "Choosing a Fallback Strategy" section of the [Character Encoding in .NET](/dotnet/standard/base-types/character-encoding) topic. - -## Examples - The following example reads a UTF-8 encoded string from a binary file represented by a object. For files that are smaller than 2,048 bytes, it reads the contents of the entire file into a byte array and calls the method to perform the decoding. For larger files, it reads 2,048 bytes at a time into a byte array, calls the method to determine how many characters are contained in the array, and then calls the method to perform the decoding. - - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetString/getstring1.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetString/VB/getstring1.vb" id="Snippet2"::: - - The example uses the following text, which should be saved to a UTF-8 encoded file named Utf8Example.txt. - -```txt - -This is a UTF-8-encoded file that contains primarily Latin text, although it -does list the first twelve letters of the Russian (Cyrillic) alphabet: - -А б в г д е ё ж з и й к - -The goal is to save this file, then open and decode it as a binary stream. - -``` - + object returned by the method of a derived class. + + See the Remarks section of the reference topic for a discussion of decoding techniques and considerations. + + Note that the precise behavior of the method for a particular implementation depends on the fallback strategy defined for that object. For more information, see the "Choosing a Fallback Strategy" section of the [Character Encoding in .NET](/dotnet/standard/base-types/character-encoding) topic. + +## Examples + The following example reads a UTF-8 encoded string from a binary file represented by a object. For files that are smaller than 2,048 bytes, it reads the contents of the entire file into a byte array and calls the method to perform the decoding. For larger files, it reads 2,048 bytes at a time into a byte array, calls the method to determine how many characters are contained in the array, and then calls the method to perform the decoding. + + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetString/getstring1.cs" id="Snippet2"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetString/VB/getstring1.vb" id="Snippet2"::: + + The example uses the following text, which should be saved to a UTF-8 encoded file named Utf8Example.txt. + +```txt + +This is a UTF-8-encoded file that contains primarily Latin text, although it +does list the first twelve letters of the Russian (Cyrillic) alphabet: + +А б в г д е ё ж з и й к + +The goal is to save this file, then open and decode it as a binary stream. + +``` + ]]> The byte array contains invalid Unicode code points. is . - A fallback occurred (for more information, see Character Encoding in .NET) - - -and- - + A fallback occurred (for more information, see Character Encoding in .NET) + + -and- + is set to . @@ -4427,17 +4427,17 @@ The goal is to save this file, then open and decode it as a binary stream. When overridden in a derived class, decodes all the bytes in the specified byte span into a string. A string that contains the decoded bytes from the provided read-only span. - method is designed to optimize performance. Instead of creating a managed byte array and then decoding it, you can instead call this method without having to create any intermediate objects. - - If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the object returned by the method of a derived class. - - See the Remarks section of the reference topic for a discussion of decoding techniques and considerations. - - Note that the precise behavior of the method for a particular implementation depends on the fallback strategy defined for that object. For more information, see the "Choosing a Fallback Strategy" section of the [Character Encoding in .NET](/dotnet/standard/base-types/character-encoding) topic. - + method is designed to optimize performance. Instead of creating a managed byte array and then decoding it, you can instead call this method without having to create any intermediate objects. + + If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the object returned by the method of a derived class. + + See the Remarks section of the reference topic for a discussion of decoding techniques and considerations. + + Note that the precise behavior of the method for a particular implementation depends on the fallback strategy defined for that object. For more information, see the "Choosing a Fallback Strategy" section of the [Character Encoding in .NET](/dotnet/standard/base-types/character-encoding) topic. + ]]> @@ -4505,27 +4505,27 @@ The goal is to save this file, then open and decode it as a binary stream. When overridden in a derived class, decodes a specified number of bytes starting at a specified address into a string. A string that contains the results of decoding the specified sequence of bytes. - method is designed to optimize performance when you have a native pointer to a byte array. Instead of creating a managed byte array and then decoding it, you can instead call this method without having to create any intermediate objects. - - If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the object returned by the method of a derived class. - - See the Remarks section of the reference topic for a discussion of decoding techniques and considerations. - - Note that the precise behavior of the method for a particular implementation depends on the fallback strategy defined for that object. For more information, see the "Choosing a Fallback Strategy" section of the [Character Encoding in .NET](/dotnet/standard/base-types/character-encoding) topic. - + method is designed to optimize performance when you have a native pointer to a byte array. Instead of creating a managed byte array and then decoding it, you can instead call this method without having to create any intermediate objects. + + If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the object returned by the method of a derived class. + + See the Remarks section of the reference topic for a discussion of decoding techniques and considerations. + + Note that the precise behavior of the method for a particular implementation depends on the fallback strategy defined for that object. For more information, see the "Choosing a Fallback Strategy" section of the [Character Encoding in .NET](/dotnet/standard/base-types/character-encoding) topic. + ]]> is a null pointer. is less than zero. - A fallback occurred (see Character Encoding in .NET) for a complete explanation) - - -and- - + A fallback occurred (see Character Encoding in .NET) for a complete explanation) + + -and- + is set to . @@ -4584,47 +4584,47 @@ The goal is to save this file, then open and decode it as a binary stream. When overridden in a derived class, decodes a sequence of bytes from the specified byte array into a string. A string that contains the results of decoding the specified sequence of bytes. - or the provided by the method or the method, respectively, of a derived class. - - See the Remarks section of the reference topic for a discussion of decoding techniques and considerations. - -## Examples - The following example reads a UTF-8 encoded string from a binary file that is represented by a object. For files that are smaller than 2,048 bytes, it reads the contents of the entire file into a byte array and calls the method to perform the decoding. For larger files, it reads 2,048 bytes at a time into a byte array, calls the method to determine how many characters are contained in the array, and then calls the method to perform the decoding. - - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetString/getstring2.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetString/VB/getstring2.vb" id="Snippet3"::: - - The example uses the following text, which should be saved to a UTF-8 encoded file named Utf8Example.txt. - -```txt - -This is a UTF-8-encoded file that contains primarily Latin text, although it -does list the first twelve letters of the Russian (Cyrillic) alphabet: - -А б в г д е ё ж з и й к - -The goal is to save this file, then open and decode it as a binary stream. - -``` - + or the provided by the method or the method, respectively, of a derived class. + + See the Remarks section of the reference topic for a discussion of decoding techniques and considerations. + +## Examples + The following example reads a UTF-8 encoded string from a binary file that is represented by a object. For files that are smaller than 2,048 bytes, it reads the contents of the entire file into a byte array and calls the method to perform the decoding. For larger files, it reads 2,048 bytes at a time into a byte array, calls the method to determine how many characters are contained in the array, and then calls the method to perform the decoding. + + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetString/getstring2.cs" id="Snippet3"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetString/VB/getstring2.vb" id="Snippet3"::: + + The example uses the following text, which should be saved to a UTF-8 encoded file named Utf8Example.txt. + +```txt + +This is a UTF-8-encoded file that contains primarily Latin text, although it +does list the first twelve letters of the Russian (Cyrillic) alphabet: + +А б в г д е ё ж з и й к + +The goal is to save this file, then open and decode it as a binary stream. + +``` + ]]> The byte array contains invalid Unicode code points. is . - or is less than zero. - - -or- - + or is less than zero. + + -or- + and do not denote a valid range in . - A fallback occurred (for more information, see Character Encoding in .NET) - - -and- - + A fallback occurred (for more information, see Character Encoding in .NET) + + -and- + is set to . @@ -4671,28 +4671,28 @@ The goal is to save this file, then open and decode it as a binary stream. When overridden in a derived class, gets a name for the current encoding that can be used with mail agent header tags. - A name for the current to use with mail agent header tags. - - -or- - + A name for the current to use with mail agent header tags. + + -or- + An empty string (""), if the current cannot be used. - method with the property. Often the method retrieves a different encoding from the test encoding furnished in the call. Generally only email applications need to retrieve such an encoding. - - In some cases, the value of the property corresponds to the international standard that defines that encoding. This doesn't mean that the implementation complies in full with that standard. - - Note that returns the name to use to describe an encoding. The property defines a different encoding that might work better for an email application, for example. However, use of the property to define the encoding is not recommended. - -## Examples - The following example retrieves the different names for each encoding and displays the encodings with one or more names that are different from . It displays but does not compare against it. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.Names/CPP/names.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/BodyName/names.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.Names/VB/names.vb" id="Snippet1"::: - + method with the property. Often the method retrieves a different encoding from the test encoding furnished in the call. Generally only email applications need to retrieve such an encoding. + + In some cases, the value of the property corresponds to the international standard that defines that encoding. This doesn't mean that the implementation complies in full with that standard. + + Note that returns the name to use to describe an encoding. The property defines a different encoding that might work better for an email application, for example. However, use of the property to define the encoding is not recommended. + +## Examples + The following example retrieves the different names for each encoding and displays the encodings with one or more names that are different from . It displays but does not compare against it. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.Names/CPP/names.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/BodyName/names.cs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.Names/VB/names.vb" id="Snippet1"::: + ]]> @@ -4759,11 +4759,11 @@ The goal is to save this file, then open and decode it as a binary stream. if the current is always normalized; otherwise, . The default is . - , which uses full canonical decomposition, followed by the replacement of sequences with their primary composites, if possible. - + , which uses full canonical decomposition, followed by the replacement of sequences with their primary composites, if possible. + ]]> @@ -4812,7 +4812,7 @@ The goal is to save this file, then open and decode it as a binary stream. System.Boolean - + One of the values. @@ -4820,11 +4820,11 @@ The goal is to save this file, then open and decode it as a binary stream. if the current object is always normalized using the specified value; otherwise, . The default is . - , which uses full canonical decomposition, followed by the replacement of sequences with their primary composites, if possible. - + , which uses full canonical decomposition, followed by the replacement of sequences with their primary composites, if possible. + ]]> @@ -4872,15 +4872,15 @@ The goal is to save this file, then open and decode it as a binary stream. if the current can be used by browser clients for displaying content; otherwise, . - @@ -4928,15 +4928,15 @@ The goal is to save this file, then open and decode it as a binary stream. if the current can be used by browser clients for saving content; otherwise, . - @@ -4984,15 +4984,15 @@ The goal is to save this file, then open and decode it as a binary stream. if the current can be used by mail and news clients for displaying content; otherwise, . - @@ -5040,15 +5040,15 @@ The goal is to save this file, then open and decode it as a binary stream. if the current can be used by mail and news clients for saving content; otherwise, . - @@ -5151,21 +5151,21 @@ The goal is to save this file, then open and decode it as a binary stream. if the current uses single-byte code points; otherwise, . - , this property retrieves `true`. - -> [!CAUTION] -> You should be careful in what your application does with the value for . An assumption of how an Encoding will proceed may still be wrong. For example, Windows-1252 has a value of `true` for , but Encoding.GetMaxByteCount(1) returns 2. This is because the method considers potential leftover surrogates from a previous decoder operation. - -## Examples - The following example checks the values of the Boolean properties of each encoding. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.IsProps/CPP/isprops.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetEncodings/isprops.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.IsProps/VB/isprops.vb" id="Snippet1"::: - + , this property retrieves `true`. + +> [!CAUTION] +> You should be careful in what your application does with the value for . An assumption of how an Encoding will proceed may still be wrong. For example, Windows-1252 has a value of `true` for , but Encoding.GetMaxByteCount(1) returns 2. This is because the method considers potential leftover surrogates from a previous decoder operation. + +## Examples + The following example checks the values of the Boolean properties of each encoding. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.IsProps/CPP/isprops.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/GetEncodings/isprops.cs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.IsProps/VB/isprops.vb" id="Snippet1"::: + ]]> @@ -5249,34 +5249,34 @@ The goal is to save this file, then open and decode it as a binary stream. When overridden in a derived class, returns a span containing the sequence of bytes that specifies the encoding used. A byte span containing a sequence of bytes that specifies the encoding used, or a span of length zero, if a preamble is not required. - object provides a preamble that is an sequence of bytes that can be prefixed to the bytes resulting from the encoding process. If the preamble contains a byte order mark (in Unicode, code point U+FEFF), it helps the decoder determine the byte order and the transformation format or UTF. - - The Unicode byte order mark (BOM) is serialized as follows (in hexadecimal): - -- UTF-8: EF BB BF - -- UTF-16 big endian byte order: FE FF - -- UTF-16 little endian byte order: FF FE - -- UTF-32 big endian byte order: 00 00 FE FF - -- UTF-32 little endian byte order: FF FE 00 00 - - You should use the BOM, because it provides nearly certain identification of an encoding for files that otherwise have lost reference to the object, for example, untagged or improperly tagged web data or random text files stored when a business did not have international concerns or other data. Often user problems might be avoided if data is consistently and properly tagged, preferably in UTF-8 or UTF-16. - - For standards that provide an encoding type, a BOM is somewhat redundant. However, it can be used to help a server send the correct encoding header. Alternatively, it can be used as a fallback in case the encoding is otherwise lost. - - There are some disadvantages to using a BOM. For example, knowing how to limit the database fields that use a BOM can be difficult. Concatenation of files can be a problem also, for example, when files are merged in such a way that an unnecessary character can end up in the middle of data. Despite the few disadvantages, however, the use of a BOM is highly recommended. - - For more information on byte order and the byte order mark, see The Unicode Standard at the [Unicode home page](https://home.unicode.org/). - -> [!CAUTION] -> To ensure that the encoded bytes are decoded properly, you should prefix encoded bytes with a preamble. However, most encodings do not provide a preamble. To ensure that the encoded bytes are decoded properly, you should use a Unicode encoding, that is, , , or , with a preamble. - + object provides a preamble that is an sequence of bytes that can be prefixed to the bytes resulting from the encoding process. If the preamble contains a byte order mark (in Unicode, code point U+FEFF), it helps the decoder determine the byte order and the transformation format or UTF. + + The Unicode byte order mark (BOM) is serialized as follows (in hexadecimal): + +- UTF-8: EF BB BF + +- UTF-16 big endian byte order: FE FF + +- UTF-16 little endian byte order: FF FE + +- UTF-32 big endian byte order: 00 00 FE FF + +- UTF-32 little endian byte order: FF FE 00 00 + + You should use the BOM, because it provides nearly certain identification of an encoding for files that otherwise have lost reference to the object, for example, untagged or improperly tagged web data or random text files stored when a business did not have international concerns or other data. Often user problems might be avoided if data is consistently and properly tagged, preferably in UTF-8 or UTF-16. + + For standards that provide an encoding type, a BOM is somewhat redundant. However, it can be used to help a server send the correct encoding header. Alternatively, it can be used as a fallback in case the encoding is otherwise lost. + + There are some disadvantages to using a BOM. For example, knowing how to limit the database fields that use a BOM can be difficult. Concatenation of files can be a problem also, for example, when files are merged in such a way that an unnecessary character can end up in the middle of data. Despite the few disadvantages, however, the use of a BOM is highly recommended. + + For more information on byte order and the byte order mark, see The Unicode Standard at the [Unicode home page](https://home.unicode.org/). + +> [!CAUTION] +> To ensure that the encoded bytes are decoded properly, you should prefix encoded bytes with a preamble. However, most encodings do not provide a preamble. To ensure that the encoded bytes are decoded properly, you should use a Unicode encoding, that is, , , or , with a preamble. + ]]> @@ -5330,23 +5330,23 @@ The goal is to save this file, then open and decode it as a binary stream. A subclass of that provides access to additional character encodings. Registers an encoding provider. - method allows you to register a class derived from that makes character encodings available on a platform that does not otherwise support them. Once the encoding provider is registered, the encodings that it supports can be retrieved by calling any overload. If there are multiple encoding providers, the method attempts to retrieve a specified encoding from each provider starting with the one most recently registered. - -Registering an encoding provider by using the method also modifies the behavior of the [Encoding.GetEncoding(Int32)]() and [EncodingProvider.GetEncoding(Int32, EncoderFallback, DecoderFallback)](xref:System.Text.Encoding.GetEncoding(System.Int32,System.Text.EncoderFallback,System.Text.DecoderFallback)) methods when passed an argument of `0`: - -- If the registered provider is the , the method returns the encoding that matches the system active code page when running on the Windows operating system. - -- A custom encoding provider can choose which encoding to return when either of these method overloads is passed an argument of `0`. The provider can also choose to not return an encoding by having the method return `null`. - -Starting with .NET Framework 4.6, .NET Framework includes one encoding provider, , that makes the encodings available that are present in the full .NET Framework but are not available in the Universal Windows Platform. By default, the Universal Windows Platform only supports the Unicode encodings, ASCII, and code page 28591. - - If the same encoding provider is used in multiple calls to the method, only the first method call registers the provider. Subsequent calls are ignored. - - If the method is called to register multiple providers that handle the same encoding, the last registered provider is the used for all encoding and decoding operations. Any previously registered providers are ignored. - + method allows you to register a class derived from that makes character encodings available on a platform that does not otherwise support them. Once the encoding provider is registered, the encodings that it supports can be retrieved by calling any overload. If there are multiple encoding providers, the method attempts to retrieve a specified encoding from each provider starting with the one most recently registered. + +Registering an encoding provider by using the method also modifies the behavior of the [Encoding.GetEncoding(Int32)]() and [EncodingProvider.GetEncoding(Int32, EncoderFallback, DecoderFallback)](xref:System.Text.Encoding.GetEncoding(System.Int32,System.Text.EncoderFallback,System.Text.DecoderFallback)) methods when passed an argument of `0`: + +- If the registered provider is the , the method returns the encoding that matches the system active code page when running on the Windows operating system. + +- A custom encoding provider can choose which encoding to return when either of these method overloads is passed an argument of `0`. The provider can also choose to not return an encoding by having the method return `null`. + +Starting with .NET Framework 4.6, .NET Framework includes one encoding provider, , that makes the encodings available that are present in the full .NET Framework but are not available in the Universal Windows Platform. By default, the Universal Windows Platform only supports the Unicode encodings, ASCII, and code page 28591. + + If the same encoding provider is used in multiple calls to the method, only the first method call registers the provider. Subsequent calls are ignored. + + If the method is called to register multiple providers that handle the same encoding, the last registered provider is the used for all encoding and decoding operations. Any previously registered providers are ignored. + ]]> @@ -5496,23 +5496,23 @@ Starting with .NET Framework 4.6, .NET Framework includes one encoding provider, Gets an encoding for the UTF-16 format using the little endian byte order. An encoding for the UTF-16 format using the little endian byte order. - object that is returned by this property may not have the appropriate behavior for your app. It uses replacement fallback to replace each string that it cannot encode and each byte that it cannot decode with a question mark ("?") character. Instead, you can call the constructor to instantiate a little endian object whose fallback is either an or a , as the following example illustrates. - - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/Unicode/unicode1.cs" interactive="try-dotnet" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.encoding.unicode/vb/unicode1.vb" id="Snippet2"::: - -## Examples - The following example determines the number of bytes required to encode a character array, encodes the characters, and displays the resulting bytes. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArr/CPP/getbytes_chararr.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/BigEndianUnicode/getbytes_chararr.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArr/VB/getbytes_chararr.vb" id="Snippet1"::: - + object that is returned by this property may not have the appropriate behavior for your app. It uses replacement fallback to replace each string that it cannot encode and each byte that it cannot decode with a question mark ("?") character. Instead, you can call the constructor to instantiate a little endian object whose fallback is either an or a , as the following example illustrates. + + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/Unicode/unicode1.cs" interactive="try-dotnet" id="Snippet2"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.encoding.unicode/vb/unicode1.vb" id="Snippet2"::: + +## Examples + The following example determines the number of bytes required to encode a character array, encodes the characters, and displays the resulting bytes. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArr/CPP/getbytes_chararr.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/BigEndianUnicode/getbytes_chararr.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArr/VB/getbytes_chararr.vb" id="Snippet1"::: + ]]> @@ -5562,25 +5562,25 @@ Starting with .NET Framework 4.6, .NET Framework includes one encoding provider, Gets an encoding for the UTF-32 format using the little endian byte order. An encoding object for the UTF-32 format using the little endian byte order. - object that is returned by this property may not have the appropriate behavior for your app. It uses replacement fallback to replace each string that it cannot encode and each byte that it cannot decode with the Unicode REPLACEMENT CHARACTER (U+FFFE). Instead, you can call the constructor to instantiate a object whose fallback is either an or a , as the following example illustrates. - - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/UTF32/encoding.utf32.1.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.encoding.utf32/vb/encoding.utf32.1.vb" id="Snippet1"::: - - For a discussion of little endian byte order, see . - - For information about the encodings supported by .NET and a discussion of which Unicode encoding to use, see [Character Encoding in .NET](/dotnet/standard/base-types/character-encoding). - -## Examples - The following example determines the number of bytes required to encode a character array, encodes the characters, and displays the resulting bytes. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArr/CPP/getbytes_chararr.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/BigEndianUnicode/getbytes_chararr.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArr/VB/getbytes_chararr.vb" id="Snippet1"::: - + object that is returned by this property may not have the appropriate behavior for your app. It uses replacement fallback to replace each string that it cannot encode and each byte that it cannot decode with the Unicode REPLACEMENT CHARACTER (U+FFFE). Instead, you can call the constructor to instantiate a object whose fallback is either an or a , as the following example illustrates. + + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/UTF32/encoding.utf32.1.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.encoding.utf32/vb/encoding.utf32.1.vb" id="Snippet1"::: + + For a discussion of little endian byte order, see . + + For information about the encodings supported by .NET and a discussion of which Unicode encoding to use, see [Character Encoding in .NET](/dotnet/standard/base-types/character-encoding). + +## Examples + The following example determines the number of bytes required to encode a character array, encodes the characters, and displays the resulting bytes. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArr/CPP/getbytes_chararr.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/BigEndianUnicode/getbytes_chararr.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetBytes_CharArr/VB/getbytes_chararr.vb" id="Snippet1"::: + ]]> @@ -5638,18 +5638,18 @@ Starting with .NET Framework 4.6, .NET Framework includes one encoding provider, Gets an encoding for the UTF-7 format. An encoding for the UTF-7 format. - @@ -5706,40 +5706,40 @@ Starting with .NET Framework 4.6, .NET Framework includes one encoding provider, Gets an encoding for the UTF-8 format. An encoding for the UTF-8 format. - object that encodes Unicode (UTF-16-encoded) characters into a sequence of one to four bytes per character, and that decodes a UTF-8-encoded byte array to Unicode (UTF-16-encoded) characters. For information about the character encodings supported by .NET and a discussion of which Unicode encoding to use, see [Character Encoding in .NET](/dotnet/standard/base-types/character-encoding). - - The object that is returned by this property might not have the appropriate behavior for your app. - -- It returns a object that provides a Unicode byte order mark (BOM). To instantiate a UTF8 encoding that doesn't provide a BOM, call any overload of the constructor. - -- It returns a object that uses replacement fallback to replace each string that it can't encode and each byte that it can't decode with a question mark ("?") character. Instead, you can call the constructor to instantiate a object whose fallback is either an or a , as the following example illustrates. - - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/UTF8/encoding.utf8.1.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.encoding.utf8/vb/encoding.utf8.1.vb" id="Snippet1"::: - -## Examples - The following example defines an array that consists of the following characters: - -- LATIN SMALL LETTER Z (U+007A) - -- LATIN SMALL LETTER A (U+0061) - -- COMBINING BREVE (U+0306) - -- LATIN SMALL LETTER AE WITH ACUTE (U+01FD) - -- GREEK SMALL LETTER BETA (U+03B2) - -- A surrogate pair (U+D800 U+DD54) that forms GREEK ACROPHONIC ATTIC ONE THOUSAND STATERS (U+10154). - - It displays the UTF-16 code units of each character and determines the number of bytes required by a UTF-8 encoder to encode the character array. It then encodes the characters and displays the resulting UTF-8-encoded bytes. - - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/UTF8/example1.cs" interactive="try-dotnet" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.encoding.utf8/vb/example1.vb" id="Snippet2"::: - + object that encodes Unicode (UTF-16-encoded) characters into a sequence of one to four bytes per character, and that decodes a UTF-8-encoded byte array to Unicode (UTF-16-encoded) characters. For information about the character encodings supported by .NET and a discussion of which Unicode encoding to use, see [Character Encoding in .NET](/dotnet/standard/base-types/character-encoding). + + The object that is returned by this property might not have the appropriate behavior for your app. + +- It returns a object that provides a Unicode byte order mark (BOM). To instantiate a UTF8 encoding that doesn't provide a BOM, call any overload of the constructor. + +- It returns a object that uses replacement fallback to replace each string that it can't encode and each byte that it can't decode with a question mark ("?") character. Instead, you can call the constructor to instantiate a object whose fallback is either an or a , as the following example illustrates. + + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/UTF8/encoding.utf8.1.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.encoding.utf8/vb/encoding.utf8.1.vb" id="Snippet1"::: + +## Examples + The following example defines an array that consists of the following characters: + +- LATIN SMALL LETTER Z (U+007A) + +- LATIN SMALL LETTER A (U+0061) + +- COMBINING BREVE (U+0306) + +- LATIN SMALL LETTER AE WITH ACUTE (U+01FD) + +- GREEK SMALL LETTER BETA (U+03B2) + +- A surrogate pair (U+D800 U+DD54) that forms GREEK ACROPHONIC ATTIC ONE THOUSAND STATERS (U+10154). + + It displays the UTF-16 code units of each character and determines the number of bytes required by a UTF-8 encoder to encode the character array. It then encodes the characters and displays the resulting UTF-8-encoded bytes. + + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/UTF8/example1.cs" interactive="try-dotnet" id="Snippet2"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.encoding.utf8/vb/example1.vb" id="Snippet2"::: + ]]> @@ -5800,30 +5800,30 @@ Starting with .NET Framework 4.6, .NET Framework includes one encoding provider, When overridden in a derived class, gets the name registered with the Internet Assigned Numbers Authority (IANA) for the current encoding. The IANA name for the current . - property is the same as the property. - - Note that returns an IANA-registered name for the encoding. When its value is the name of a standard, the implementation of the encoding might not conform in full to that standard. The property defines a different encoding that might work better for email headers. However, most apps should use instead. - - For more information on the IANA, go to [www.iana.org](https://www.iana.org/). - - The is the same as the returned by . Some of the web names are duplicates; see the remarks for for more information. - -## Examples - The following example includes the in an HTML header. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.WebName/CPP/webname.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/WebName/webname.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.WebName/VB/webname.vb" id="Snippet1"::: - - The following example retrieves the different names for each encoding and displays the encodings with one or more names that are different from . It displays but does not compare against it. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.Names/CPP/names.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/BodyName/names.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.Names/VB/names.vb" id="Snippet1"::: - + property is the same as the property. + + Note that returns an IANA-registered name for the encoding. When its value is the name of a standard, the implementation of the encoding might not conform in full to that standard. The property defines a different encoding that might work better for email headers. However, most apps should use instead. + + For more information on the IANA, go to [www.iana.org](https://www.iana.org/). + + The is the same as the returned by . Some of the web names are duplicates; see the remarks for for more information. + +## Examples + The following example includes the in an HTML header. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.WebName/CPP/webname.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/WebName/webname.cs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.WebName/VB/webname.vb" id="Snippet1"::: + + The following example retrieves the different names for each encoding and displays the encodings with one or more names that are different from . It displays but does not compare against it. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.Names/CPP/names.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/BodyName/names.cs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.Names/VB/names.vb" id="Snippet1"::: + ]]> @@ -5873,18 +5873,18 @@ Starting with .NET Framework 4.6, .NET Framework includes one encoding provider, When overridden in a derived class, gets the Windows operating system code page that most closely corresponds to the current encoding. The Windows operating system code page that most closely corresponds to the current . - instead of to identify the code page. - -## Examples - The following example determines the Windows code page that most closely corresponds to each encoding. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.CodePage/CPP/codepage.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/WindowsCodePage/codepage.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.CodePage/VB/codepage.vb" id="Snippet1"::: - + instead of to identify the code page. + +## Examples + The following example determines the Windows code page that most closely corresponds to each encoding. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.CodePage/CPP/codepage.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/WindowsCodePage/codepage.cs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.CodePage/VB/codepage.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.Text/StringBuilder.xml b/xml/System.Text/StringBuilder.xml index efea27f2bcb..3f40a7fb926 100644 --- a/xml/System.Text/StringBuilder.xml +++ b/xml/System.Text/StringBuilder.xml @@ -77,13 +77,13 @@ Represents a mutable string of characters. This class cannot be inherited. For more information about this API, see Supplemental API remarks for StringBuilder. - class. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/StringBuilder/cpp/StringBuilder.cpp" id="Snippet1"::: -:::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Overview/StringBuilder.cs" interactive="try-dotnet" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Overview/StringBuilder.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/StringBuilder/VB/StringBuilder.vb" id="Snippet1"::: + class. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/StringBuilder/cpp/StringBuilder.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Overview/StringBuilder.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Overview/StringBuilder.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/StringBuilder/VB/StringBuilder.vb" id="Snippet1"::: ]]> @@ -149,21 +149,21 @@ The following example shows how to call many of the methods defined by the Initializes a new instance of the class. - , and the capacity is set to the implementation-specific default capacity. - - - -## Examples - The following example demonstrates how to call the constructor with no parameters. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.StringBuilder.Constructors/CPP/constructors.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/.ctor/constructors.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/.ctor/constructors.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Constructors/VB/Form1.vb" id="Snippet1"::: - + , and the capacity is set to the implementation-specific default capacity. + + + +## Examples + The following example demonstrates how to call the constructor with no parameters. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.StringBuilder.Constructors/CPP/constructors.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/.ctor/constructors.cs" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/.ctor/constructors.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Constructors/VB/Form1.vb" id="Snippet1"::: + ]]> @@ -216,23 +216,23 @@ The following example shows how to call many of the methods defined by the The suggested starting size of this instance. Initializes a new instance of the class using the specified capacity. - property. If the number of characters to be stored in the current instance exceeds this `capacity` value, the object allocates additional memory to store them. - - The string value of this instance is set to . If `capacity` is zero, the implementation-specific default capacity is used. - - - -## Examples - The following example demonstrates how to call the constructor with a specified capacity. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.StringBuilder.Constructors/CPP/constructors.cpp" id="Snippet3"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/.ctor/constructors.cs" id="Snippet3"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/.ctor/constructors.fs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Constructors/VB/Form1.vb" id="Snippet3"::: - + property. If the number of characters to be stored in the current instance exceeds this `capacity` value, the object allocates additional memory to store them. + + The string value of this instance is set to . If `capacity` is zero, the implementation-specific default capacity is used. + + + +## Examples + The following example demonstrates how to call the constructor with a specified capacity. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.StringBuilder.Constructors/CPP/constructors.cpp" id="Snippet3"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/.ctor/constructors.cs" id="Snippet3"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/.ctor/constructors.fs" id="Snippet3"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Constructors/VB/Form1.vb" id="Snippet3"::: + ]]> @@ -289,21 +289,21 @@ The following example shows how to call many of the methods defined by the The string used to initialize the value of the instance. If is , the new will contain the empty string (that is, it contains ). Initializes a new instance of the class using the specified string. - will contain the empty string (that is, it contains ). - - - -## Examples - The following example demonstrates how to call the constructor with the specified string. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.StringBuilder.Constructors/CPP/constructors.cpp" id="Snippet4"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/.ctor/constructors.cs" id="Snippet4"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/.ctor/constructors.fs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Constructors/VB/Form1.vb" id="Snippet4"::: - + will contain the empty string (that is, it contains ). + + + +## Examples + The following example demonstrates how to call the constructor with the specified string. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.StringBuilder.Constructors/CPP/constructors.cpp" id="Snippet4"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/.ctor/constructors.cs" id="Snippet4"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/.ctor/constructors.fs" id="Snippet4"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Constructors/VB/Form1.vb" id="Snippet4"::: + ]]> @@ -358,25 +358,25 @@ The following example shows how to call many of the methods defined by the The maximum number of characters the current string can contain. Initializes a new instance of the class that starts with a specified capacity and can grow to a specified maximum. - property. If the number of characters to be stored in the current instance exceeds this `capacity` value, the object allocates additional memory to store them. - - If `capacity` is zero, the implementation-specific default capacity is used. - - The `maxCapacity` property defines the maximum number of characters that the current instance can hold. Its value is assigned to the property. If the number of characters to be stored in the current instance exceeds this `maxCapacity` value, the object does not allocate additional memory, but instead throws an exception. - - - -## Examples - The following example demonstrates how to call the constructor with a specified capacity and maximum capacity. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.StringBuilder.Constructors/CPP/constructors.cpp" id="Snippet5"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/.ctor/constructors.cs" id="Snippet5"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/.ctor/constructors.fs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Constructors/VB/Form1.vb" id="Snippet5"::: - + property. If the number of characters to be stored in the current instance exceeds this `capacity` value, the object allocates additional memory to store them. + + If `capacity` is zero, the implementation-specific default capacity is used. + + The `maxCapacity` property defines the maximum number of characters that the current instance can hold. Its value is assigned to the property. If the number of characters to be stored in the current instance exceeds this `maxCapacity` value, the object does not allocate additional memory, but instead throws an exception. + + + +## Examples + The following example demonstrates how to call the constructor with a specified capacity and maximum capacity. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.StringBuilder.Constructors/CPP/constructors.cpp" id="Snippet5"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/.ctor/constructors.cs" id="Snippet5"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/.ctor/constructors.fs" id="Snippet5"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Constructors/VB/Form1.vb" id="Snippet5"::: + ]]> @@ -443,23 +443,23 @@ The following example shows how to call many of the methods defined by the The suggested starting size of the . Initializes a new instance of the class using the specified string and capacity. - property. If the number of characters to be stored in the current instance exceeds this `capacity` value, the object allocates additional memory to store them. - - If `capacity` is zero, the implementation-specific default capacity is used. - - - -## Examples - The following example demonstrates how to call the constructor with an initial string and a specified capacity. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.StringBuilder.Constructors/CPP/constructors.cpp" id="Snippet7"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/.ctor/constructors.cs" id="Snippet7"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/.ctor/constructors.fs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Constructors/VB/Form1.vb" id="Snippet7"::: - + property. If the number of characters to be stored in the current instance exceeds this `capacity` value, the object allocates additional memory to store them. + + If `capacity` is zero, the implementation-specific default capacity is used. + + + +## Examples + The following example demonstrates how to call the constructor with an initial string and a specified capacity. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.StringBuilder.Constructors/CPP/constructors.cpp" id="Snippet7"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/.ctor/constructors.cs" id="Snippet7"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/.ctor/constructors.fs" id="Snippet7"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Constructors/VB/Form1.vb" id="Snippet7"::: + ]]> @@ -526,30 +526,30 @@ The following example shows how to call many of the methods defined by the The suggested starting size of the . Initializes a new instance of the class from the specified substring and capacity. - property. If the number of characters to be stored in the current instance exceeds this `capacity` value, the object allocates additional memory to store them. - - If `capacity` is zero, the implementation-specific default capacity is used. - - - -## Examples - The following example demonstrates how to call the constructor with the specified string. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.StringBuilder.Constructors/CPP/constructors.cpp" id="Snippet6"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/.ctor/constructors.cs" id="Snippet6"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/.ctor/constructors.fs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Constructors/VB/Form1.vb" id="Snippet6"::: - + property. If the number of characters to be stored in the current instance exceeds this `capacity` value, the object allocates additional memory to store them. + + If `capacity` is zero, the implementation-specific default capacity is used. + + + +## Examples + The following example demonstrates how to call the constructor with the specified string. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.StringBuilder.Constructors/CPP/constructors.cpp" id="Snippet6"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/.ctor/constructors.cs" id="Snippet6"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/.ctor/constructors.fs" id="Snippet6"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Constructors/VB/Form1.vb" id="Snippet6"::: + ]]> - is less than zero. - - -or- - + is less than zero. + + -or- + plus is not a position within . @@ -613,17 +613,17 @@ The following example shows how to call many of the methods defined by the Appends the string representation of a specified Boolean value to this instance. A reference to this instance after the append operation has completed. - method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. - - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append2.cs" interactive="try-dotnet-method" id="Snippet2"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append2.fs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append2.vb" id="Snippet2"::: - - The method calls the method to get the string representation of `value`. The capacity of this instance is adjusted as needed. - + method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. + + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append2.cs" interactive="try-dotnet-method" id="Snippet2"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append2.fs" id="Snippet2"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append2.vb" id="Snippet2"::: + + The method calls the method to get the string representation of `value`. The capacity of this instance is adjusted as needed. + ]]> Enlarging the value of this instance would exceed . @@ -679,19 +679,19 @@ The following example shows how to call many of the methods defined by the Appends the string representation of a specified 8-bit unsigned integer to this instance. A reference to this instance after the append operation has completed. - method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. - - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append2.cs" interactive="try-dotnet-method" id="Snippet3"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append2.fs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append2.vb" id="Snippet3"::: - - The method calls the method to get the string representation of `value` for the current culture. To control the formatting of `value`, call the method. - - The capacity of this instance is adjusted as needed. - + method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. + + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append2.cs" interactive="try-dotnet-method" id="Snippet3"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append2.fs" id="Snippet3"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append2.vb" id="Snippet3"::: + + The method calls the method to get the string representation of `value` for the current culture. To control the formatting of `value`, call the method. + + The capacity of this instance is adjusted as needed. + ]]> Enlarging the value of this instance would exceed . @@ -753,17 +753,17 @@ The following example shows how to call many of the methods defined by the Appends the string representation of a specified object to this instance. A reference to this instance after the append operation has completed. - method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. - - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append2.cs" interactive="try-dotnet-method" id="Snippet4"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append2.fs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append2.vb" id="Snippet4"::: - - The capacity of this instance is adjusted as needed. - + method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. + + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append2.cs" interactive="try-dotnet-method" id="Snippet4"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append2.fs" id="Snippet4"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append2.vb" id="Snippet4"::: + + The capacity of this instance is adjusted as needed. + ]]> Enlarging the value of this instance would exceed . @@ -833,19 +833,19 @@ The following example shows how to call many of the methods defined by the Appends the string representation of the Unicode characters in a specified array to this instance. A reference to this instance after the append operation has completed. - method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. - - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append2.cs" interactive="try-dotnet-method" id="Snippet6"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append2.fs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append2.vb" id="Snippet6"::: - - The capacity of this instance is adjusted as needed. - + method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. + + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append2.cs" interactive="try-dotnet-method" id="Snippet6"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append2.fs" id="Snippet6"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append2.vb" id="Snippet6"::: + + The capacity of this instance is adjusted as needed. + ]]> Enlarging the value of this instance would exceed . @@ -900,19 +900,19 @@ The following example shows how to call many of the methods defined by the Appends the string representation of a specified decimal number to this instance. A reference to this instance after the append operation has completed. - method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. - - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append2.cs" interactive="try-dotnet-method" id="Snippet8"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append2.fs" id="Snippet8"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append2.vb" id="Snippet8"::: - - The method calls the method to get the string representation of `value` for the current culture. To control the formatting of `value`, call the method. - - The capacity of this instance is adjusted as needed. - + method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. + + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append2.cs" interactive="try-dotnet-method" id="Snippet8"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append2.fs" id="Snippet8"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append2.vb" id="Snippet8"::: + + The method calls the method to get the string representation of `value` for the current culture. To control the formatting of `value`, call the method. + + The capacity of this instance is adjusted as needed. + ]]> Enlarging the value of this instance would exceed . @@ -968,19 +968,19 @@ The following example shows how to call many of the methods defined by the Appends the string representation of a specified double-precision floating-point number to this instance. A reference to this instance after the append operation has completed. - method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. - - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append2.cs" interactive="try-dotnet-method" id="Snippet9"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append2.fs" id="Snippet9"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append2.vb" id="Snippet9"::: - - The method calls the method to get the string representation of `value` for the current culture. To control the formatting of `value`, call the method. - - The capacity of this instance is adjusted as needed. - + method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. + + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append2.cs" interactive="try-dotnet-method" id="Snippet9"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append2.fs" id="Snippet9"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append2.vb" id="Snippet9"::: + + The method calls the method to get the string representation of `value` for the current culture. To control the formatting of `value`, call the method. + + The capacity of this instance is adjusted as needed. + ]]> Enlarging the value of this instance would exceed . @@ -1036,19 +1036,19 @@ The following example shows how to call many of the methods defined by the Appends the string representation of a specified 16-bit signed integer to this instance. A reference to this instance after the append operation has completed. - method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. - - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append3.cs" interactive="try-dotnet-method" id="Snippet10"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append3.fs" id="Snippet10"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append3.vb" id="Snippet10"::: - - The method calls the method to get the string representation of `value` for the current culture. To control the formatting of `value`, call the method. - - The capacity of this instance is adjusted as needed. - + method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. + + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append3.cs" interactive="try-dotnet-method" id="Snippet10"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append3.fs" id="Snippet10"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append3.vb" id="Snippet10"::: + + The method calls the method to get the string representation of `value` for the current culture. To control the formatting of `value`, call the method. + + The capacity of this instance is adjusted as needed. + ]]> Enlarging the value of this instance would exceed . @@ -1110,19 +1110,19 @@ The following example shows how to call many of the methods defined by the Appends the string representation of a specified 32-bit signed integer to this instance. A reference to this instance after the append operation has completed. - method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. - - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append3.cs" interactive="try-dotnet-method" id="Snippet11"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append3.fs" id="Snippet11"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append3.vb" id="Snippet11"::: - - The method calls the method to get the string representation of `value` for the current culture. To control the formatting of `value`, call the method. - - The capacity of this instance is adjusted as needed. - + method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. + + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append3.cs" interactive="try-dotnet-method" id="Snippet11"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append3.fs" id="Snippet11"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append3.vb" id="Snippet11"::: + + The method calls the method to get the string representation of `value` for the current culture. To control the formatting of `value`, call the method. + + The capacity of this instance is adjusted as needed. + ]]> Enlarging the value of this instance would exceed . @@ -1178,19 +1178,19 @@ The following example shows how to call many of the methods defined by the Appends the string representation of a specified 64-bit signed integer to this instance. A reference to this instance after the append operation has completed. - method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. - - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append3.cs" interactive="try-dotnet-method" id="Snippet12"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append3.fs" id="Snippet12"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append3.vb" id="Snippet12"::: - - The method calls the to get the string representation of `value` for the current culture. To control the formatting of `value`, call the method. - - The capacity of this instance is adjusted as needed. - + method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. + + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append3.cs" interactive="try-dotnet-method" id="Snippet12"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append3.fs" id="Snippet12"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append3.vb" id="Snippet12"::: + + The method calls the to get the string representation of `value` for the current culture. To control the formatting of `value`, call the method. + + The capacity of this instance is adjusted as needed. + ]]> Enlarging the value of this instance would exceed . @@ -1260,19 +1260,19 @@ The following example shows how to call many of the methods defined by the Appends the string representation of a specified object to this instance. A reference to this instance after the append operation has completed. - method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. It defines a `Dog` class, creates a `Dog` object, and makes three calls to the method to create a string that contains the dog's name and breed. - - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append4.cs" interactive="try-dotnet" id="Snippet18"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append4.fs" id="Snippet18"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append4.vb" id="Snippet18"::: - - The method calls the method to get the string representation of `value`. If `value` is `null`, no changes are made to the object. - - The capacity of this instance is adjusted as needed. - + method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. It defines a `Dog` class, creates a `Dog` object, and makes three calls to the method to create a string that contains the dog's name and breed. + + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append4.cs" interactive="try-dotnet" id="Snippet18"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append4.fs" id="Snippet18"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append4.vb" id="Snippet18"::: + + The method calls the method to get the string representation of `value`. If `value` is `null`, no changes are made to the object. + + The capacity of this instance is adjusted as needed. + ]]> Enlarging the value of this instance would exceed . @@ -1421,19 +1421,19 @@ The following example shows how to call many of the methods defined by the Appends the string representation of a specified 8-bit signed integer to this instance. A reference to this instance after the append operation has completed. - method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. - - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append3.cs" interactive="try-dotnet-method" id="Snippet13"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append3.fs" id="Snippet13"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append3.vb" id="Snippet13"::: - - The method calls the method to get the string representation of `value` for the current culture. To control the formatting of `value`, call the method. - - The capacity of this instance is adjusted as needed. - + method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. + + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append3.cs" interactive="try-dotnet-method" id="Snippet13"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append3.fs" id="Snippet13"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append3.vb" id="Snippet13"::: + + The method calls the method to get the string representation of `value` for the current culture. To control the formatting of `value`, call the method. + + The capacity of this instance is adjusted as needed. + ]]> Enlarging the value of this instance would exceed . @@ -1489,19 +1489,19 @@ The following example shows how to call many of the methods defined by the Appends the string representation of a specified single-precision floating-point number to this instance. A reference to this instance after the append operation has completed. - method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. - - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append3.cs" id="Snippet14"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append3.fs" id="Snippet14"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append3.vb" id="Snippet14"::: - - The method calls the method to get the string representation of `value` for the current culture. To control the formatting of `value`, call the method. - - The capacity of this instance is adjusted as needed. - + method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. + + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append3.cs" id="Snippet14"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append3.fs" id="Snippet14"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append3.vb" id="Snippet14"::: + + The method calls the method to get the string representation of `value` for the current culture. To control the formatting of `value`, call the method. + + The capacity of this instance is adjusted as needed. + ]]> Enlarging the value of this instance would exceed . @@ -1571,19 +1571,19 @@ The following example shows how to call many of the methods defined by the Appends a copy of the specified string to this instance. A reference to this instance after the append operation has completed. - method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. - - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append2.cs" interactive="try-dotnet-method" id="Snippet2"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append2.fs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append2.vb" id="Snippet2"::: - - If `value` is `null`, no changes are made. - - The capacity of this instance is adjusted as needed. - + method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. + + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append2.cs" interactive="try-dotnet-method" id="Snippet2"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append2.fs" id="Snippet2"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append2.vb" id="Snippet2"::: + + If `value` is `null`, no changes are made. + + The capacity of this instance is adjusted as needed. + ]]> Enlarging the value of this instance would exceed . @@ -1732,19 +1732,19 @@ The following example shows how to call many of the methods defined by the Appends the string representation of a specified 16-bit unsigned integer to this instance. A reference to this instance after the append operation has completed. - method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. - - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append3.cs" interactive="try-dotnet-method" id="Snippet15"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append3.fs" id="Snippet15"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append3.vb" id="Snippet15"::: - - The method calls the method to get the string representation of `value`. To control the formatting of `value`, call the method. - - The capacity of this instance is adjusted as needed. - + method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. + + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append3.cs" interactive="try-dotnet-method" id="Snippet15"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append3.fs" id="Snippet15"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append3.vb" id="Snippet15"::: + + The method calls the method to get the string representation of `value`. To control the formatting of `value`, call the method. + + The capacity of this instance is adjusted as needed. + ]]> Enlarging the value of this instance would exceed . @@ -1806,19 +1806,19 @@ The following example shows how to call many of the methods defined by the Appends the string representation of a specified 32-bit unsigned integer to this instance. A reference to this instance after the append operation has completed. - method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. - - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append3.cs" interactive="try-dotnet-method" id="Snippet16"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append3.fs" id="Snippet16"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append3.vb" id="Snippet16"::: - - The calls the method to get the string representation of `value` for the current culture. To control the formatting of `value`, call the method. - - The capacity of this instance is adjusted as needed. - + method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. + + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append3.cs" interactive="try-dotnet-method" id="Snippet16"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append3.fs" id="Snippet16"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append3.vb" id="Snippet16"::: + + The calls the method to get the string representation of `value` for the current culture. To control the formatting of `value`, call the method. + + The capacity of this instance is adjusted as needed. + ]]> Enlarging the value of this instance would exceed . @@ -1880,19 +1880,19 @@ The following example shows how to call many of the methods defined by the Appends the string representation of a specified 64-bit unsigned integer to this instance. A reference to this instance after the append operation has completed. - method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. - - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append3.cs" interactive="try-dotnet-method" id="Snippet17"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append3.fs" id="Snippet17"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append3.vb" id="Snippet17"::: - - The method calls the method to get the string representation of `value` for the current culture. To control the formatting of `value`, call the method. - - The capacity of this instance is adjusted as needed. - + method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. + + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append3.cs" interactive="try-dotnet-method" id="Snippet17"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append3.fs" id="Snippet17"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append3.vb" id="Snippet17"::: + + The method calls the method to get the string representation of `value` for the current culture. To control the formatting of `value`, call the method. + + The capacity of this instance is adjusted as needed. + ]]> Enlarging the value of this instance would exceed . @@ -1956,24 +1956,24 @@ The following example shows how to call many of the methods defined by the Appends a specified number of copies of the string representation of a Unicode character to this instance. A reference to this instance after the append operation has completed. - method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. - - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append2.cs" id="Snippet5"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append2.fs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append2.vb" id="Snippet5"::: - - The capacity of this instance is adjusted as needed. - + method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. + + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append2.cs" id="Snippet5"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append2.fs" id="Snippet5"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append2.vb" id="Snippet5"::: + + The capacity of this instance is adjusted as needed. + ]]> - is less than zero. - - -or- - + is less than zero. + + -or- + Enlarging the value of this instance would exceed . Out of memory. @@ -2039,23 +2039,23 @@ The following example shows how to call many of the methods defined by the Appends an array of Unicode characters starting at a specified address to this instance. A reference to this instance after the append operation has completed. - method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object. - - The capacity of this instance is adjusted as needed. - + method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object. + + The capacity of this instance is adjusted as needed. + ]]> - is less than zero. - - -or- - + is less than zero. + + -or- + Enlarging the value of this instance would exceed . is a null pointer. @@ -2178,36 +2178,36 @@ The following example shows how to call many of the methods defined by the Appends the string representation of a specified subarray of Unicode characters to this instance. A reference to this instance after the append operation has completed. - method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. - - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append2.cs" interactive="try-dotnet-method" id="Snippet7"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append2.fs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append2.vb" id="Snippet7"::: - - The capacity of this instance is adjusted as needed. - + method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. + + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append2.cs" interactive="try-dotnet-method" id="Snippet7"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append2.fs" id="Snippet7"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append2.vb" id="Snippet7"::: + + The capacity of this instance is adjusted as needed. + ]]> is , and and are not zero. - is less than zero. - - -or- - - is less than zero. - - -or- - - + is greater than the length of . - - -or- - + is less than zero. + + -or- + + is less than zero. + + -or- + + + is greater than the length of . + + -or- + Enlarging the value of this instance would exceed . In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. @@ -2279,36 +2279,36 @@ The following example shows how to call many of the methods defined by the Appends a copy of a specified substring to this instance. A reference to this instance after the append operation has completed. - method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. - - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append3.cs" interactive="try-dotnet-method" id="Snippet19"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append3.fs" id="Snippet19"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append3.vb" id="Snippet19"::: - - The capacity of this instance is adjusted as needed. - + method modifies the existing instance of this class; it does not return a new class instance. Because of this, you can call a method or property on the existing reference and you do not have to assign the return value to a object, as the following example illustrates. + + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Append/append3.cs" interactive="try-dotnet-method" id="Snippet19"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Append/append3.fs" id="Snippet19"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append3.vb" id="Snippet19"::: + + The capacity of this instance is adjusted as needed. + ]]> is , and and are not zero. - less than zero. - - -or- - - less than zero. - - -or- - - + is greater than the length of . - - -or- - + less than zero. + + -or- + + less than zero. + + -or- + + + is greater than the length of . + + -or- + Enlarging the value of this instance would exceed . In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. @@ -2452,51 +2452,51 @@ The following example shows how to call many of the methods defined by the Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. Each format item is replaced by the string representation of a single argument. A reference to this instance with appended. Each format item in is replaced by the string representation of . - object. - - The `format` parameter consists of zero or more runs of text intermixed with zero or more indexed placeholders, called format items. The index of the format items must be 0, to correspond to `arg0`, the single object in the parameter list of this method. The formatting process replaces each format item with the string representation of `arg0`. - - The syntax of a format item is as follows: - - {*index*[,*length*][:*formatString*]} - - Elements in square brackets are optional. The following table describes each element. - -|Element|Description| -|-------------|-----------------| -|*index*|The zero-based position in the parameter list of the object to be formatted. If the object specified by *index* is `null`, the format item is replaced by . If there is no parameter in the *index* position, a is thrown.| -|,*length*|The minimum number of characters in the string representation of the parameter. If positive, the parameter is right-aligned; if negative, it is left-aligned.| -|:*formatString*|A standard or custom format string that is supported by the parameter.| - -> [!NOTE] -> For the standard and custom format strings used with date and time values, see [Standard Date and Time Format Strings](/dotnet/standard/base-types/standard-date-and-time-format-strings) and [Custom Date and Time Format Strings](/dotnet/standard/base-types/custom-date-and-time-format-strings). For the standard and custom format strings used with numeric values, see [Standard Numeric Format Strings](/dotnet/standard/base-types/standard-numeric-format-strings) and [Custom Numeric Format Strings](/dotnet/standard/base-types/custom-numeric-format-strings). For the standard format strings used with enumerations, see [Enumeration Format Strings](/dotnet/standard/base-types/enumeration-format-strings). - - `arg0` represents the object to be formatted. Each format item in `format` is replaced with the string representation of `arg0`. If the format item includes `formatString` and `arg0` implements the interface, then `arg0.ToString(formatString, null)` defines the formatting. Otherwise, `arg0.ToString()` defines the formatting. - - If the string assigned to `format` is "Thank you for your donation of {0:####} cans of food to our charitable organization." and `arg0` is an integer with the value 10, the return value will be "Thank you for your donation of 10 cans of food to our charitable organization." - - - -## Examples - The following example demonstrates the method. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringbuilder.appendformat/CPP/appfmt.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/AppendFormat/appfmt.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/AppendFormat/appfmt.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringbuilder.appendformat/VB/appfmt.vb" id="Snippet1"::: - + object. + + The `format` parameter consists of zero or more runs of text intermixed with zero or more indexed placeholders, called format items. The index of the format items must be 0, to correspond to `arg0`, the single object in the parameter list of this method. The formatting process replaces each format item with the string representation of `arg0`. + + The syntax of a format item is as follows: + + {*index*[,*length*][:*formatString*]} + + Elements in square brackets are optional. The following table describes each element. + +|Element|Description| +|-------------|-----------------| +|*index*|The zero-based position in the parameter list of the object to be formatted. If the object specified by *index* is `null`, the format item is replaced by . If there is no parameter in the *index* position, a is thrown.| +|,*length*|The minimum number of characters in the string representation of the parameter. If positive, the parameter is right-aligned; if negative, it is left-aligned.| +|:*formatString*|A standard or custom format string that is supported by the parameter.| + +> [!NOTE] +> For the standard and custom format strings used with date and time values, see [Standard Date and Time Format Strings](/dotnet/standard/base-types/standard-date-and-time-format-strings) and [Custom Date and Time Format Strings](/dotnet/standard/base-types/custom-date-and-time-format-strings). For the standard and custom format strings used with numeric values, see [Standard Numeric Format Strings](/dotnet/standard/base-types/standard-numeric-format-strings) and [Custom Numeric Format Strings](/dotnet/standard/base-types/custom-numeric-format-strings). For the standard format strings used with enumerations, see [Enumeration Format Strings](/dotnet/standard/base-types/enumeration-format-strings). + + `arg0` represents the object to be formatted. Each format item in `format` is replaced with the string representation of `arg0`. If the format item includes `formatString` and `arg0` implements the interface, then `arg0.ToString(formatString, null)` defines the formatting. Otherwise, `arg0.ToString()` defines the formatting. + + If the string assigned to `format` is "Thank you for your donation of {0:####} cans of food to our charitable organization." and `arg0` is an integer with the value 10, the return value will be "Thank you for your donation of 10 cans of food to our charitable organization." + + + +## Examples + The following example demonstrates the method. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringbuilder.appendformat/CPP/appfmt.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/AppendFormat/appfmt.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/AppendFormat/appfmt.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringbuilder.appendformat/VB/appfmt.vb" id="Snippet1"::: + ]]> is . - is invalid. - - -or- - + is invalid. + + -or- + The index of a format item is less than 0 (zero), or greater than or equal to 1. The length of the expanded string would exceed . @@ -2580,51 +2580,51 @@ The following example shows how to call many of the methods defined by the Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. Each format item is replaced by the string representation of a corresponding argument in a parameter array. A reference to this instance with appended. Each format item in is replaced by the string representation of the corresponding object argument. - object. - - The `format` parameter consists of zero or more runs of text intermixed with zero or more indexed placeholders, called format items, that correspond to objects in the parameter list of this method. The formatting process replaces each format item with the string representation of the corresponding object. - - The syntax of a format item is as follows: - - {*index*[,*length*][:*formatString*]} - - Elements in square brackets are optional. The following table describes each element. - -|Element|Description| -|-------------|-----------------| -|*index*|The zero-based position in the parameter list of the object to be formatted. If the object specified by *index* is `null`, the format item is replaced by . If there is no parameter in the *index* position, a is thrown.| -|,*length*|The minimum number of characters in the string representation of the parameter. If positive, the parameter is right-aligned; if negative, it is left-aligned.| -|:*formatString*|A standard or custom format string that is supported by the parameter.| - -> [!NOTE] -> For the standard and custom format strings used with date and time values, see [Standard Date and Time Format Strings](/dotnet/standard/base-types/standard-date-and-time-format-strings) and [Custom Date and Time Format Strings](/dotnet/standard/base-types/custom-date-and-time-format-strings). For the standard and custom format strings used with numeric values, see [Standard Numeric Format Strings](/dotnet/standard/base-types/standard-numeric-format-strings) and [Custom Numeric Format Strings](/dotnet/standard/base-types/custom-numeric-format-strings). For the standard format strings used with enumerations, see [Enumeration Format Strings](/dotnet/standard/base-types/enumeration-format-strings). - - `args` represents the objects to be formatted. Each format item in `format` is replaced with the string representation of the corresponding object in `args`. If the format item includes `formatString` and the corresponding object in `args` implements the interface, then `args[index].ToString(formatString, provider)` defines the formatting. Otherwise, `args[index].ToString()` defines the formatting. - - If the string assigned to `format` is "Thank you for your donation of {0:####} cans of food to our charitable organization." and `arg0` is an integer with the value 10, the return value will be "Thank you for your donation of 10 cans of food to our charitable organization." - - - -## Examples - The following example demonstrates the method. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringbuilder.appendformat/CPP/appfmt.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/AppendFormat/appfmt.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/AppendFormat/appfmt.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringbuilder.appendformat/VB/appfmt.vb" id="Snippet1"::: - + object. + + The `format` parameter consists of zero or more runs of text intermixed with zero or more indexed placeholders, called format items, that correspond to objects in the parameter list of this method. The formatting process replaces each format item with the string representation of the corresponding object. + + The syntax of a format item is as follows: + + {*index*[,*length*][:*formatString*]} + + Elements in square brackets are optional. The following table describes each element. + +|Element|Description| +|-------------|-----------------| +|*index*|The zero-based position in the parameter list of the object to be formatted. If the object specified by *index* is `null`, the format item is replaced by . If there is no parameter in the *index* position, a is thrown.| +|,*length*|The minimum number of characters in the string representation of the parameter. If positive, the parameter is right-aligned; if negative, it is left-aligned.| +|:*formatString*|A standard or custom format string that is supported by the parameter.| + +> [!NOTE] +> For the standard and custom format strings used with date and time values, see [Standard Date and Time Format Strings](/dotnet/standard/base-types/standard-date-and-time-format-strings) and [Custom Date and Time Format Strings](/dotnet/standard/base-types/custom-date-and-time-format-strings). For the standard and custom format strings used with numeric values, see [Standard Numeric Format Strings](/dotnet/standard/base-types/standard-numeric-format-strings) and [Custom Numeric Format Strings](/dotnet/standard/base-types/custom-numeric-format-strings). For the standard format strings used with enumerations, see [Enumeration Format Strings](/dotnet/standard/base-types/enumeration-format-strings). + + `args` represents the objects to be formatted. Each format item in `format` is replaced with the string representation of the corresponding object in `args`. If the format item includes `formatString` and the corresponding object in `args` implements the interface, then `args[index].ToString(formatString, provider)` defines the formatting. Otherwise, `args[index].ToString()` defines the formatting. + + If the string assigned to `format` is "Thank you for your donation of {0:####} cans of food to our charitable organization." and `arg0` is an integer with the value 10, the return value will be "Thank you for your donation of 10 cans of food to our charitable organization." + + + +## Examples + The following example demonstrates the method. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringbuilder.appendformat/CPP/appfmt.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/AppendFormat/appfmt.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/AppendFormat/appfmt.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringbuilder.appendformat/VB/appfmt.vb" id="Snippet1"::: + ]]> or is . - is invalid. - - -or- - + is invalid. + + -or- + The index of a format item is less than 0 (zero), or greater than or equal to the length of the array. The length of the expanded string would exceed . @@ -2709,58 +2709,58 @@ The following example shows how to call many of the methods defined by the Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. Each format item is replaced by the string representation of a single argument using a specified format provider. A reference to this instance after the append operation has completed. After the append operation, this instance contains any data that existed before the operation, suffixed by a copy of in which any format specification is replaced by the string representation of . - object. - - The `format` parameter consists of zero or more runs of text intermixed with zero or more indexed placeholders, called format items. The index of each format item must be zero (0) since this method includes an argument list with a single argument. The formatting process replaces each format item with the string representation of `arg0`. - - The syntax of a format item is as follows: - - {*index*[,*length*][:*formatString*]} - - Elements in square brackets are optional. The following table describes each element. - -|Element|Description| -|-------------|-----------------| -|*index*|The zero-based position in the parameter list of the object to be formatted. If the object specified by *index* is `null`, the format item is replaced by . In this case, since the method has a single argument in the argument list, the value of *index* must always be 0. If it is not, a is thrown.| -|,*length*|The minimum number of characters in the string representation of the parameter. If positive, the parameter is right-aligned; if negative, it is left-aligned.| -|:*formatString*|A standard or custom format string that is supported by the parameter.| - -> [!NOTE] -> For the standard and custom format strings used with date and time values, see [Standard Date and Time Format Strings](/dotnet/standard/base-types/standard-date-and-time-format-strings) and [Custom Date and Time Format Strings](/dotnet/standard/base-types/custom-date-and-time-format-strings). For the standard and custom format strings used with numeric values, see [Standard Numeric Format Strings](/dotnet/standard/base-types/standard-numeric-format-strings) and [Custom Numeric Format Strings](/dotnet/standard/base-types/custom-numeric-format-strings). For the standard format strings used with enumerations, see [Enumeration Format Strings](/dotnet/standard/base-types/enumeration-format-strings). - - The `provider` parameter specifies an implementation that can provide formatting information for the objects in `args`. `provider` can be any of the following: - -- A object that provides culture-specific formatting information. - -- A object that provides culture-specific formatting information for `arg0` if it is a numeric value. - -- A object that provides culture-specific formatting information for `arg0` if it is a date and time value. - -- A custom implementation that provides formatting information for `arg0`. Typically, such an implementation also implements the interface. - - If the `provider` parameter is `null`, formatting information is obtained from the current culture. - - `arg0` represents the object to be formatted. Each format item in `format` is replaced with the string representation of `arg0`. If the format item includes `formatString` and `arg0` implements the interface, then `arg0.ToString(formatString, provider)` defines the formatting. Otherwise, `arg0.ToString()` defines the formatting. - -## Examples - The following includes two calls to the method. Both use the formatting conventions of the English-United Kingdom (en-GB) culture. The first inserts the string representation of a value currency in a result string. The second inserts a value in two places in a result string, the first including only the short date string and the second the short time string. - - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/AppendFormat/appendformat1.cs" id="Snippet2"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/AppendFormat/appendformat1.fs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.stringbuilder.appendformat/vb/appendformat1.vb" id="Snippet2"::: - + object. + + The `format` parameter consists of zero or more runs of text intermixed with zero or more indexed placeholders, called format items. The index of each format item must be zero (0) since this method includes an argument list with a single argument. The formatting process replaces each format item with the string representation of `arg0`. + + The syntax of a format item is as follows: + + {*index*[,*length*][:*formatString*]} + + Elements in square brackets are optional. The following table describes each element. + +|Element|Description| +|-------------|-----------------| +|*index*|The zero-based position in the parameter list of the object to be formatted. If the object specified by *index* is `null`, the format item is replaced by . In this case, since the method has a single argument in the argument list, the value of *index* must always be 0. If it is not, a is thrown.| +|,*length*|The minimum number of characters in the string representation of the parameter. If positive, the parameter is right-aligned; if negative, it is left-aligned.| +|:*formatString*|A standard or custom format string that is supported by the parameter.| + +> [!NOTE] +> For the standard and custom format strings used with date and time values, see [Standard Date and Time Format Strings](/dotnet/standard/base-types/standard-date-and-time-format-strings) and [Custom Date and Time Format Strings](/dotnet/standard/base-types/custom-date-and-time-format-strings). For the standard and custom format strings used with numeric values, see [Standard Numeric Format Strings](/dotnet/standard/base-types/standard-numeric-format-strings) and [Custom Numeric Format Strings](/dotnet/standard/base-types/custom-numeric-format-strings). For the standard format strings used with enumerations, see [Enumeration Format Strings](/dotnet/standard/base-types/enumeration-format-strings). + + The `provider` parameter specifies an implementation that can provide formatting information for the objects in `args`. `provider` can be any of the following: + +- A object that provides culture-specific formatting information. + +- A object that provides culture-specific formatting information for `arg0` if it is a numeric value. + +- A object that provides culture-specific formatting information for `arg0` if it is a date and time value. + +- A custom implementation that provides formatting information for `arg0`. Typically, such an implementation also implements the interface. + + If the `provider` parameter is `null`, formatting information is obtained from the current culture. + + `arg0` represents the object to be formatted. Each format item in `format` is replaced with the string representation of `arg0`. If the format item includes `formatString` and `arg0` implements the interface, then `arg0.ToString(formatString, provider)` defines the formatting. Otherwise, `arg0.ToString()` defines the formatting. + +## Examples + The following includes two calls to the method. Both use the formatting conventions of the English-United Kingdom (en-GB) culture. The first inserts the string representation of a value currency in a result string. The second inserts a value in two places in a result string, the first including only the short date string and the second the short time string. + + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/AppendFormat/appendformat1.cs" id="Snippet2"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/AppendFormat/appendformat1.fs" id="Snippet2"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.stringbuilder.appendformat/vb/appendformat1.vb" id="Snippet2"::: + ]]> is . - is invalid. - - -or- - + is invalid. + + -or- + The index of a format item is less than 0 (zero), or greater than or equal to one (1). The length of the expanded string would exceed . @@ -2860,67 +2860,67 @@ The following example shows how to call many of the methods defined by the Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. Each format item is replaced by the string representation of a corresponding argument in a parameter array using a specified format provider. A reference to this instance after the append operation has completed. After the append operation, this instance contains any data that existed before the operation, suffixed by a copy of where any format specification is replaced by the string representation of the corresponding object argument. - object. - - The `format` parameter consists of zero or more runs of text intermixed with zero or more indexed placeholders, called format items, that correspond to objects in the parameter list of this method. The formatting process replaces each format item with the string representation of the corresponding object. - - The syntax of a format item is as follows: - - {*index*[,*length*][:*formatString*]} - - Elements in square brackets are optional. The following table describes each element. - -|Element|Description| -|-------------|-----------------| -|*index*|The zero-based position in the parameter list of the object to be formatted. If the object specified by *index* is `null`, the format item is replaced by . If there is no parameter in the *index* position, a is thrown.| -|,*length*|The minimum number of characters in the string representation of the parameter. If positive, the parameter is right-aligned; if negative, it is left-aligned.| -|:*formatString*|A standard or custom format string that is supported by the parameter.| - -> [!NOTE] -> For the standard and custom format strings used with date and time values, see [Standard Date and Time Format Strings](/dotnet/standard/base-types/standard-date-and-time-format-strings) and [Custom Date and Time Format Strings](/dotnet/standard/base-types/custom-date-and-time-format-strings). For the standard and custom format strings used with numeric values, see [Standard Numeric Format Strings](/dotnet/standard/base-types/standard-numeric-format-strings) and [Custom Numeric Format Strings](/dotnet/standard/base-types/custom-numeric-format-strings). For the standard format strings used with enumerations, see [Enumeration Format Strings](/dotnet/standard/base-types/enumeration-format-strings). - - The `provider` parameter specifies an implementation that can provide formatting information for the objects in `args`. `provider` can be any of the following: - -- A object that provides culture-specific formatting information. - -- A object that provides culture-specific formatting information for numeric values in `args`. - -- A object that provides culture-specific formatting information for date and time values in `args`. - -- A custom implementation that provides formatting information for one or more of the objects in `args`. Typically, such an implementation also implements the interface. The second example in the next section illustrates an method call with a custom implementation. - - If the `provider` parameter is `null`, format provider information is obtained from the current culture. - - `args` represents the objects to be formatted. Each format item in `format` is replaced with the string representation of the corresponding object in `args`. If the format item includes `formatString` and the corresponding object in `args` implements the interface, then `args[index].ToString(formatString, provider)` defines the formatting. Otherwise, `args[index].ToString()` defines the formatting. - - - -## Examples - The following example demonstrates the method. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringbuilder.appendformat/CPP/appfmt.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/AppendFormat/appfmt.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/AppendFormat/appfmt.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringbuilder.appendformat/VB/appfmt.vb" id="Snippet1"::: - - The following example defines a custom implementation named `CustomerFormatter` that formats a 10-digit customer number with hyphens after the fourth and seventh digits. It is passed to the method to create a string that includes the formatted customer number and customer name. - - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/AppendFormat/customernumberformatter1.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/AppendFormat/customernumberformatter1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.stringbuilder.appendformat/vb/customernumberformatter1.vb" id="Snippet1"::: - + object. + + The `format` parameter consists of zero or more runs of text intermixed with zero or more indexed placeholders, called format items, that correspond to objects in the parameter list of this method. The formatting process replaces each format item with the string representation of the corresponding object. + + The syntax of a format item is as follows: + + {*index*[,*length*][:*formatString*]} + + Elements in square brackets are optional. The following table describes each element. + +|Element|Description| +|-------------|-----------------| +|*index*|The zero-based position in the parameter list of the object to be formatted. If the object specified by *index* is `null`, the format item is replaced by . If there is no parameter in the *index* position, a is thrown.| +|,*length*|The minimum number of characters in the string representation of the parameter. If positive, the parameter is right-aligned; if negative, it is left-aligned.| +|:*formatString*|A standard or custom format string that is supported by the parameter.| + +> [!NOTE] +> For the standard and custom format strings used with date and time values, see [Standard Date and Time Format Strings](/dotnet/standard/base-types/standard-date-and-time-format-strings) and [Custom Date and Time Format Strings](/dotnet/standard/base-types/custom-date-and-time-format-strings). For the standard and custom format strings used with numeric values, see [Standard Numeric Format Strings](/dotnet/standard/base-types/standard-numeric-format-strings) and [Custom Numeric Format Strings](/dotnet/standard/base-types/custom-numeric-format-strings). For the standard format strings used with enumerations, see [Enumeration Format Strings](/dotnet/standard/base-types/enumeration-format-strings). + + The `provider` parameter specifies an implementation that can provide formatting information for the objects in `args`. `provider` can be any of the following: + +- A object that provides culture-specific formatting information. + +- A object that provides culture-specific formatting information for numeric values in `args`. + +- A object that provides culture-specific formatting information for date and time values in `args`. + +- A custom implementation that provides formatting information for one or more of the objects in `args`. Typically, such an implementation also implements the interface. The second example in the next section illustrates an method call with a custom implementation. + + If the `provider` parameter is `null`, format provider information is obtained from the current culture. + + `args` represents the objects to be formatted. Each format item in `format` is replaced with the string representation of the corresponding object in `args`. If the format item includes `formatString` and the corresponding object in `args` implements the interface, then `args[index].ToString(formatString, provider)` defines the formatting. Otherwise, `args[index].ToString()` defines the formatting. + + + +## Examples + The following example demonstrates the method. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringbuilder.appendformat/CPP/appfmt.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/AppendFormat/appfmt.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/AppendFormat/appfmt.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringbuilder.appendformat/VB/appfmt.vb" id="Snippet1"::: + + The following example defines a custom implementation named `CustomerFormatter` that formats a 10-digit customer number with hyphens after the fourth and seventh digits. It is passed to the method to create a string that includes the formatted customer number and customer name. + + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/AppendFormat/customernumberformatter1.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/AppendFormat/customernumberformatter1.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.stringbuilder.appendformat/vb/customernumberformatter1.vb" id="Snippet1"::: + ]]> is . - is invalid. - - -or- - + is invalid. + + -or- + The index of a format item is less than 0 (zero), or greater than or equal to the length of the array. The length of the expanded string would exceed . @@ -2987,7 +2987,7 @@ The following example shows how to call many of the methods defined by the An object that supplies culture-specific formatting information. A . An array of objects to format. - Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. + Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. Each format item is replaced by the string representation of any of the arguments using a specified format provider. A reference to this instance after the append operation has completed. To be added. @@ -3041,7 +3041,7 @@ The following example shows how to call many of the methods defined by the An object that supplies culture-specific formatting information. A . A span of objects to format. - Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. + Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. Each format item is replaced by the string representation of any of the arguments using a specified format provider. A reference to this instance after the append operation has completed. To be added. @@ -3120,51 +3120,51 @@ The following example shows how to call many of the methods defined by the Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. Each format item is replaced by the string representation of either of two arguments. A reference to this instance with appended. Each format item in is replaced by the string representation of the corresponding object argument. - object. - - The `format` parameter consists of zero or more runs of text intermixed with zero or more indexed placeholders, called format items, that correspond to `arg0` and `arg1`, the two objects in the parameter list of this method. The formatting process replaces each format item with the string representation of the corresponding object. - - The syntax of a format item is as follows: - - {*index*[,*length*][:*formatString*]} - - Elements in square brackets are optional. The following table describes each element. - -|Element|Description| -|-------------|-----------------| -|*index*|The zero-based position in the parameter list of the object to be formatted. If the object specified by *index* is `null`, the format item is replaced by . If there is no parameter in the *index* position, a is thrown.| -|,*length*|The minimum number of characters in the string representation of the parameter. If positive, the parameter is right-aligned; if negative, it is left-aligned.| -|:*formatString*|A standard or custom format string that is supported by the parameter.| - -> [!NOTE] -> For the standard and custom format strings used with date and time values, see [Standard Date and Time Format Strings](/dotnet/standard/base-types/standard-date-and-time-format-strings) and [Custom Date and Time Format Strings](/dotnet/standard/base-types/custom-date-and-time-format-strings). For the standard and custom format strings used with numeric values, see [Standard Numeric Format Strings](/dotnet/standard/base-types/standard-numeric-format-strings) and [Custom Numeric Format Strings](/dotnet/standard/base-types/custom-numeric-format-strings). For the standard format strings used with enumerations, see [Enumeration Format Strings](/dotnet/standard/base-types/enumeration-format-strings). - - `arg0` and `arg1` represent the objects to be formatted. Each format item in `format` is replaced with the string representation of either `arg0` or `arg1`. If the format item includes `formatString` and the corresponding object implements the interface, then `arg`*x*`.ToString(formatString, provider)` defines the formatting, where *x* is the index of the argument. Otherwise, `arg`*x*`.ToString()` defines the formatting. - - If the string assigned to `format` is "Thank you for your donation of {0:####} cans of food to our charitable organization." and `arg0` is an integer with the value 10, the return value will be "Thank you for your donation of 10 cans of food to our charitable organization." - - - -## Examples - The following example demonstrates the method. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringbuilder.appendformat/CPP/appfmt.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/AppendFormat/appfmt.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/AppendFormat/appfmt.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringbuilder.appendformat/VB/appfmt.vb" id="Snippet1"::: - + object. + + The `format` parameter consists of zero or more runs of text intermixed with zero or more indexed placeholders, called format items, that correspond to `arg0` and `arg1`, the two objects in the parameter list of this method. The formatting process replaces each format item with the string representation of the corresponding object. + + The syntax of a format item is as follows: + + {*index*[,*length*][:*formatString*]} + + Elements in square brackets are optional. The following table describes each element. + +|Element|Description| +|-------------|-----------------| +|*index*|The zero-based position in the parameter list of the object to be formatted. If the object specified by *index* is `null`, the format item is replaced by . If there is no parameter in the *index* position, a is thrown.| +|,*length*|The minimum number of characters in the string representation of the parameter. If positive, the parameter is right-aligned; if negative, it is left-aligned.| +|:*formatString*|A standard or custom format string that is supported by the parameter.| + +> [!NOTE] +> For the standard and custom format strings used with date and time values, see [Standard Date and Time Format Strings](/dotnet/standard/base-types/standard-date-and-time-format-strings) and [Custom Date and Time Format Strings](/dotnet/standard/base-types/custom-date-and-time-format-strings). For the standard and custom format strings used with numeric values, see [Standard Numeric Format Strings](/dotnet/standard/base-types/standard-numeric-format-strings) and [Custom Numeric Format Strings](/dotnet/standard/base-types/custom-numeric-format-strings). For the standard format strings used with enumerations, see [Enumeration Format Strings](/dotnet/standard/base-types/enumeration-format-strings). + + `arg0` and `arg1` represent the objects to be formatted. Each format item in `format` is replaced with the string representation of either `arg0` or `arg1`. If the format item includes `formatString` and the corresponding object implements the interface, then `arg`*x*`.ToString(formatString, provider)` defines the formatting, where *x* is the index of the argument. Otherwise, `arg`*x*`.ToString()` defines the formatting. + + If the string assigned to `format` is "Thank you for your donation of {0:####} cans of food to our charitable organization." and `arg0` is an integer with the value 10, the return value will be "Thank you for your donation of 10 cans of food to our charitable organization." + + + +## Examples + The following example demonstrates the method. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringbuilder.appendformat/CPP/appfmt.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/AppendFormat/appfmt.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/AppendFormat/appfmt.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringbuilder.appendformat/VB/appfmt.vb" id="Snippet1"::: + ]]> is . - is invalid. - - -or- - + is invalid. + + -or- + The index of a format item is less than 0 (zero), or greater than or equal to 2. The length of the expanded string would exceed . @@ -3247,60 +3247,60 @@ The following example shows how to call many of the methods defined by the Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. Each format item is replaced by the string representation of either of two arguments using a specified format provider. A reference to this instance after the append operation has completed. After the append operation, this instance contains any data that existed before the operation, suffixed by a copy of where any format specification is replaced by the string representation of the corresponding object argument. - object. - - The `format` parameter consists of zero or more runs of text intermixed with zero or more indexed placeholders, called format items, that correspond to objects in the parameter list of this method. The formatting process replaces each format item with the string representation of the corresponding object. - - The syntax of a format item is as follows: - - {*index*[,*length*][:*formatString*]} - - Elements in square brackets are optional. The following table describes each element. - -|Element|Description| -|-------------|-----------------| -|*index*|The zero-based position in the parameter list of the object to be formatted. If the object specified by *index* is `null`, the format item is replaced by . If there is no parameter in the *index* position, a is thrown.| -|,*length*|The minimum number of characters in the string representation of the parameter. If positive, the parameter is right-aligned; if negative, it is left-aligned.| -|:*formatString*|A standard or custom format string that is supported by the parameter.| - -> [!NOTE] -> For the standard and custom format strings used with date and time values, see [Standard Date and Time Format Strings](/dotnet/standard/base-types/standard-date-and-time-format-strings) and [Custom Date and Time Format Strings](/dotnet/standard/base-types/custom-date-and-time-format-strings). For the standard and custom format strings used with numeric values, see [Standard Numeric Format Strings](/dotnet/standard/base-types/standard-numeric-format-strings) and [Custom Numeric Format Strings](/dotnet/standard/base-types/custom-numeric-format-strings). For the standard format strings used with enumerations, see [Enumeration Format Strings](/dotnet/standard/base-types/enumeration-format-strings). - - The `provider` parameter specifies an implementation that can provide formatting information for `arg0` and `arg1`. `provider` can be any of the following: - -- A object that provides culture-specific formatting information. - -- A object that provides culture-specific formatting information for `arg0` or `arg1` if they are numeric values. - -- A object that provides culture-specific formatting information for `arg0` or `arg1` if they are date and time values. - -- A custom implementation that provides formatting information for `arg0` and `arg1`. Typically, such an implementation also implements the interface. - - If the `provider` parameter is `null`, format provider information is obtained from the current culture. - - `arg0` and `arg1` represent the objects to be formatted. Each format item in `format` is replaced with the string representation of the object that has the corresponding index. If the format item includes `formatString` and the corresponding argument implements the interface, then the argument's `ToString(formatString, provider)` method defines the formatting. Otherwise, the argument's `ToString()` method defines the formatting. - - - -## Examples - The following example uses the method to display time and temperature data stored in a generic object. Note that the format string has three format items, although there are only to objects to format. This is because the first object in the list (a date and time value) is used by two format items: The first format item displays the time, and the second displays the date. - - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/AppendFormat/appendformat2.cs" interactive="try-dotnet" id="Snippet3"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/AppendFormat/appendformat2.fs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.stringbuilder.appendformat/vb/appendformat2.vb" id="Snippet3"::: - + object. + + The `format` parameter consists of zero or more runs of text intermixed with zero or more indexed placeholders, called format items, that correspond to objects in the parameter list of this method. The formatting process replaces each format item with the string representation of the corresponding object. + + The syntax of a format item is as follows: + + {*index*[,*length*][:*formatString*]} + + Elements in square brackets are optional. The following table describes each element. + +|Element|Description| +|-------------|-----------------| +|*index*|The zero-based position in the parameter list of the object to be formatted. If the object specified by *index* is `null`, the format item is replaced by . If there is no parameter in the *index* position, a is thrown.| +|,*length*|The minimum number of characters in the string representation of the parameter. If positive, the parameter is right-aligned; if negative, it is left-aligned.| +|:*formatString*|A standard or custom format string that is supported by the parameter.| + +> [!NOTE] +> For the standard and custom format strings used with date and time values, see [Standard Date and Time Format Strings](/dotnet/standard/base-types/standard-date-and-time-format-strings) and [Custom Date and Time Format Strings](/dotnet/standard/base-types/custom-date-and-time-format-strings). For the standard and custom format strings used with numeric values, see [Standard Numeric Format Strings](/dotnet/standard/base-types/standard-numeric-format-strings) and [Custom Numeric Format Strings](/dotnet/standard/base-types/custom-numeric-format-strings). For the standard format strings used with enumerations, see [Enumeration Format Strings](/dotnet/standard/base-types/enumeration-format-strings). + + The `provider` parameter specifies an implementation that can provide formatting information for `arg0` and `arg1`. `provider` can be any of the following: + +- A object that provides culture-specific formatting information. + +- A object that provides culture-specific formatting information for `arg0` or `arg1` if they are numeric values. + +- A object that provides culture-specific formatting information for `arg0` or `arg1` if they are date and time values. + +- A custom implementation that provides formatting information for `arg0` and `arg1`. Typically, such an implementation also implements the interface. + + If the `provider` parameter is `null`, format provider information is obtained from the current culture. + + `arg0` and `arg1` represent the objects to be formatted. Each format item in `format` is replaced with the string representation of the object that has the corresponding index. If the format item includes `formatString` and the corresponding argument implements the interface, then the argument's `ToString(formatString, provider)` method defines the formatting. Otherwise, the argument's `ToString()` method defines the formatting. + + + +## Examples + The following example uses the method to display time and temperature data stored in a generic object. Note that the format string has three format items, although there are only to objects to format. This is because the first object in the list (a date and time value) is used by two format items: The first format item displays the time, and the second displays the date. + + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/AppendFormat/appendformat2.cs" interactive="try-dotnet" id="Snippet3"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/AppendFormat/appendformat2.fs" id="Snippet3"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.stringbuilder.appendformat/vb/appendformat2.vb" id="Snippet3"::: + ]]> is . - is invalid. - - -or- - + is invalid. + + -or- + The index of a format item is less than 0 (zero), or greater than or equal to 2 (two). The length of the expanded string would exceed . @@ -3386,51 +3386,51 @@ The following example shows how to call many of the methods defined by the Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. Each format item is replaced by the string representation of either of three arguments. A reference to this instance with appended. Each format item in is replaced by the string representation of the corresponding object argument. - object. - - The `format` parameter consists of zero or more runs of text intermixed with zero or more indexed placeholders, called format items, that correspond to `arg0` through `arg2`, the objects in the parameter list of this method. The formatting process replaces each format item with the string representation of the corresponding object. - - The syntax of a format item is as follows: - - {*index*[,*length*][:*formatString*]} - - Elements in square brackets are optional. The following table describes each element. - -|Element|Description| -|-------------|-----------------| -|*index*|The zero-based position in the parameter list of the object to be formatted. If the object specified by *index* is `null`, the format item is replaced by . If there is no parameter in the *index* position, a is thrown.| -|,*length*|The minimum number of characters in the string representation of the parameter. If positive, the parameter is right-aligned; if negative, it is left-aligned.| -|:*formatString*|A standard or custom format string that is supported by the parameter.| - -> [!NOTE] -> For the standard and custom format strings used with date and time values, see [Standard Date and Time Format Strings](/dotnet/standard/base-types/standard-date-and-time-format-strings) and [Custom Date and Time Format Strings](/dotnet/standard/base-types/custom-date-and-time-format-strings). For the standard and custom format strings used with numeric values, see [Standard Numeric Format Strings](/dotnet/standard/base-types/standard-numeric-format-strings) and [Custom Numeric Format Strings](/dotnet/standard/base-types/custom-numeric-format-strings). For the standard format strings used with enumerations, see [Enumeration Format Strings](/dotnet/standard/base-types/enumeration-format-strings). - - `arg0`, `arg1`, and `arg2` represent the objects to be formatted. Each format item in `format` is replaced with the string representation of either `arg0`, `arg1`, or `arg2`, depending on the index of the format item. If the format item includes `formatString` and the corresponding object in `args` implements the interface, then `arg`*x*`.ToString(formatString, null)` defines the formatting, where *x* is the index of the argument. Otherwise, `arg`*x*`.ToString()` defines the formatting. - - If the string assigned to `format` is "Thank you for your donation of {0:####} cans of food to our charitable organization." and `arg0` is an integer with the value 10, the return value will be "Thank you for your donation of 10 cans of food to our charitable organization." - - - -## Examples - The following example demonstrates the method. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringbuilder.appendformat/CPP/appfmt.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/AppendFormat/appfmt.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/AppendFormat/appfmt.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringbuilder.appendformat/VB/appfmt.vb" id="Snippet1"::: - + object. + + The `format` parameter consists of zero or more runs of text intermixed with zero or more indexed placeholders, called format items, that correspond to `arg0` through `arg2`, the objects in the parameter list of this method. The formatting process replaces each format item with the string representation of the corresponding object. + + The syntax of a format item is as follows: + + {*index*[,*length*][:*formatString*]} + + Elements in square brackets are optional. The following table describes each element. + +|Element|Description| +|-------------|-----------------| +|*index*|The zero-based position in the parameter list of the object to be formatted. If the object specified by *index* is `null`, the format item is replaced by . If there is no parameter in the *index* position, a is thrown.| +|,*length*|The minimum number of characters in the string representation of the parameter. If positive, the parameter is right-aligned; if negative, it is left-aligned.| +|:*formatString*|A standard or custom format string that is supported by the parameter.| + +> [!NOTE] +> For the standard and custom format strings used with date and time values, see [Standard Date and Time Format Strings](/dotnet/standard/base-types/standard-date-and-time-format-strings) and [Custom Date and Time Format Strings](/dotnet/standard/base-types/custom-date-and-time-format-strings). For the standard and custom format strings used with numeric values, see [Standard Numeric Format Strings](/dotnet/standard/base-types/standard-numeric-format-strings) and [Custom Numeric Format Strings](/dotnet/standard/base-types/custom-numeric-format-strings). For the standard format strings used with enumerations, see [Enumeration Format Strings](/dotnet/standard/base-types/enumeration-format-strings). + + `arg0`, `arg1`, and `arg2` represent the objects to be formatted. Each format item in `format` is replaced with the string representation of either `arg0`, `arg1`, or `arg2`, depending on the index of the format item. If the format item includes `formatString` and the corresponding object in `args` implements the interface, then `arg`*x*`.ToString(formatString, null)` defines the formatting, where *x* is the index of the argument. Otherwise, `arg`*x*`.ToString()` defines the formatting. + + If the string assigned to `format` is "Thank you for your donation of {0:####} cans of food to our charitable organization." and `arg0` is an integer with the value 10, the return value will be "Thank you for your donation of 10 cans of food to our charitable organization." + + + +## Examples + The following example demonstrates the method. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringbuilder.appendformat/CPP/appfmt.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/AppendFormat/appfmt.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/AppendFormat/appfmt.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringbuilder.appendformat/VB/appfmt.vb" id="Snippet1"::: + ]]> is . - is invalid. - - -or- - + is invalid. + + -or- + The index of a format item is less than 0 (zero), or greater than or equal to 3. The length of the expanded string would exceed . @@ -3515,60 +3515,60 @@ The following example shows how to call many of the methods defined by the Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. Each format item is replaced by the string representation of either of three arguments using a specified format provider. A reference to this instance after the append operation has completed. After the append operation, this instance contains any data that existed before the operation, suffixed by a copy of where any format specification is replaced by the string representation of the corresponding object argument. - object. - - The `format` parameter consists of zero or more runs of text intermixed with zero or more indexed placeholders, called format items, that correspond to objects in the parameter list of this method. The formatting process replaces each format item with the string representation of the corresponding object. - - The syntax of a format item is as follows: - - {*index*[,*length*][:*formatString*]} - - Elements in square brackets are optional. The following table describes each element. - -|Element|Description| -|-------------|-----------------| -|*index*|The zero-based position in the parameter list of the object to be formatted. If the object specified by *index* is `null`, the format item is replaced by . If there is no parameter in the *index* position, a is thrown.| -|,*length*|The minimum number of characters in the string representation of the parameter. If positive, the parameter is right-aligned; if negative, it is left-aligned.| -|:*formatString*|A standard or custom format string that is supported by the parameter.| - -> [!NOTE] -> For the standard and custom format strings used with date and time values, see [Standard Date and Time Format Strings](/dotnet/standard/base-types/standard-date-and-time-format-strings) and [Custom Date and Time Format Strings](/dotnet/standard/base-types/custom-date-and-time-format-strings). For the standard and custom format strings used with numeric values, see [Standard Numeric Format Strings](/dotnet/standard/base-types/standard-numeric-format-strings) and [Custom Numeric Format Strings](/dotnet/standard/base-types/custom-numeric-format-strings). For the standard format strings used with enumerations, see [Enumeration Format Strings](/dotnet/standard/base-types/enumeration-format-strings). - - The `provider` parameter specifies an implementation that can provide formatting information for `arg0` and `arg1`. `provider` can be any of the following: - -- A object that provides culture-specific formatting information. - -- A object that provides culture-specific formatting information for `arg0` or `arg1` if they are numeric values. - -- A object that provides culture-specific formatting information for `arg0`, `arg1`, or `arg2` if they are date and time values. - -- A custom implementation that provides formatting information for `arg0`, `arg1`, and `arg2`. Typically, such an implementation also implements the interface. - - If the `provider` parameter is `null`, format provider information is obtained from the current culture. - - `arg0`, `arg1`, and `arg2` represent the objects to be formatted. Each format item in `format` is replaced with the string representation of the object that has the corresponding index. If the format item includes `formatString` and the corresponding argument implements the interface, then the argument's `ToString(formatString, provider)` method defines the formatting. Otherwise, the argument's `ToString()` method defines the formatting. - - - -## Examples - The following example uses the method to illustrate the result of a Boolean `And` operation with integer values. Note that the format string includes six format items, but the method has only three items in its argument list, because each item is formatted in two different ways. - - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/AppendFormat/appendformat3.cs" interactive="try-dotnet" id="Snippet4"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/AppendFormat/appendformat3.fs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.stringbuilder.appendformat/vb/appendformat3.vb" id="Snippet4"::: - + object. + + The `format` parameter consists of zero or more runs of text intermixed with zero or more indexed placeholders, called format items, that correspond to objects in the parameter list of this method. The formatting process replaces each format item with the string representation of the corresponding object. + + The syntax of a format item is as follows: + + {*index*[,*length*][:*formatString*]} + + Elements in square brackets are optional. The following table describes each element. + +|Element|Description| +|-------------|-----------------| +|*index*|The zero-based position in the parameter list of the object to be formatted. If the object specified by *index* is `null`, the format item is replaced by . If there is no parameter in the *index* position, a is thrown.| +|,*length*|The minimum number of characters in the string representation of the parameter. If positive, the parameter is right-aligned; if negative, it is left-aligned.| +|:*formatString*|A standard or custom format string that is supported by the parameter.| + +> [!NOTE] +> For the standard and custom format strings used with date and time values, see [Standard Date and Time Format Strings](/dotnet/standard/base-types/standard-date-and-time-format-strings) and [Custom Date and Time Format Strings](/dotnet/standard/base-types/custom-date-and-time-format-strings). For the standard and custom format strings used with numeric values, see [Standard Numeric Format Strings](/dotnet/standard/base-types/standard-numeric-format-strings) and [Custom Numeric Format Strings](/dotnet/standard/base-types/custom-numeric-format-strings). For the standard format strings used with enumerations, see [Enumeration Format Strings](/dotnet/standard/base-types/enumeration-format-strings). + + The `provider` parameter specifies an implementation that can provide formatting information for `arg0` and `arg1`. `provider` can be any of the following: + +- A object that provides culture-specific formatting information. + +- A object that provides culture-specific formatting information for `arg0` or `arg1` if they are numeric values. + +- A object that provides culture-specific formatting information for `arg0`, `arg1`, or `arg2` if they are date and time values. + +- A custom implementation that provides formatting information for `arg0`, `arg1`, and `arg2`. Typically, such an implementation also implements the interface. + + If the `provider` parameter is `null`, format provider information is obtained from the current culture. + + `arg0`, `arg1`, and `arg2` represent the objects to be formatted. Each format item in `format` is replaced with the string representation of the object that has the corresponding index. If the format item includes `formatString` and the corresponding argument implements the interface, then the argument's `ToString(formatString, provider)` method defines the formatting. Otherwise, the argument's `ToString()` method defines the formatting. + + + +## Examples + The following example uses the method to illustrate the result of a Boolean `And` operation with integer values. Note that the format string includes six format items, but the method has only three items in its argument list, because each item is formatted in two different ways. + + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/AppendFormat/appendformat3.cs" interactive="try-dotnet" id="Snippet4"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/AppendFormat/appendformat3.fs" id="Snippet4"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.stringbuilder.appendformat/vb/appendformat3.vb" id="Snippet4"::: + ]]> is . - is invalid. - - -or- - + is invalid. + + -or- + The index of a format item is less than 0 (zero), or greater than or equal to 3 (three). The length of the expanded string would exceed . @@ -3635,7 +3635,7 @@ The following example shows how to call many of the methods defined by the An object that supplies culture-specific formatting information. A . The first object to format. - Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. + Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. Each format item is replaced by the string representation of any of the arguments using a specified format provider. A reference to this instance after the append operation has completed. To be added. @@ -3704,7 +3704,7 @@ The following example shows how to call many of the methods defined by the A . The first object to format. The second object to format. - Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. + Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. Each format item is replaced by the string representation of any of the arguments using a specified format provider. A reference to this instance after the append operation has completed. To be added. @@ -3784,7 +3784,7 @@ The following example shows how to call many of the methods defined by the The first object to format. The second object to format. The third object to format. - Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. + Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. Each format item is replaced by the string representation of any of the arguments using a specified format provider. A reference to this instance after the append operation has completed. To be added. @@ -4192,23 +4192,23 @@ The following example shows how to call many of the methods defined by the Appends the default line terminator to the end of the current object. A reference to this instance after the append operation has completed. - property. - - The capacity of this instance is adjusted as needed. - - - -## Examples - The following example demonstrates the method. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringbuilder.appendline/CPP/al.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/AppendLine/al.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/AppendLine/al.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringbuilder.appendline/VB/al.vb" id="Snippet1"::: - + property. + + The capacity of this instance is adjusted as needed. + + + +## Examples + The following example demonstrates the method. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringbuilder.appendline/CPP/al.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/AppendLine/al.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/AppendLine/al.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringbuilder.appendline/VB/al.vb" id="Snippet1"::: + ]]> Enlarging the value of this instance would exceed . @@ -4277,13 +4277,13 @@ The following example shows how to call many of the methods defined by the Appends a copy of the specified string followed by the default line terminator to the end of the current object. A reference to this instance after the append operation has completed. - property. - - The capacity of this instance is adjusted as needed. - + property. + + The capacity of this instance is adjusted as needed. + ]]> Enlarging the value of this instance would exceed . @@ -4432,29 +4432,29 @@ The following example shows how to call many of the methods defined by the Gets or sets the maximum number of characters that can be contained in the memory allocated by the current instance. The maximum number of characters that can be contained in the memory allocated by the current instance. Its value can range from to . - does not affect the string value of the current instance. can be decreased as long as it is not less than . - - The dynamically allocates more space when required and increases accordingly. For performance reasons, a might allocate more memory than needed. The amount of memory allocated is implementation-specific. - - - -## Examples - The following example demonstrates the property. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringbuilder.ensurecapacity/CPP/cap.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Capacity/cap.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Capacity/cap.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringbuilder.ensurecapacity/VB/cap.vb" id="Snippet1"::: - + does not affect the string value of the current instance. can be decreased as long as it is not less than . + + The dynamically allocates more space when required and increases accordingly. For performance reasons, a might allocate more memory than needed. The amount of memory allocated is implementation-specific. + + + +## Examples + The following example demonstrates the property. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringbuilder.ensurecapacity/CPP/cap.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Capacity/cap.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Capacity/cap.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringbuilder.ensurecapacity/VB/cap.vb" id="Snippet1"::: + ]]> - The value specified for a set operation is less than the current length of this instance. - - -or- - + The value specified for a set operation is less than the current length of this instance. + + -or- + The value specified for a set operation is greater than the maximum capacity. @@ -4504,16 +4504,16 @@ The following example shows how to call many of the methods defined by the Gets or sets the character at the specified character position in this instance. The Unicode character at position . - . The first character in the string is at index 0. The length of a string is the number of characters it contains. The last accessible character of a instance is at index - 1. - - is the default property of the class. In C#, it is an indexer. This means that individual characters can be retrieved from the property as shown in the following example, which counts the number of alphabetic, white-space, and punctuation characters in a string. - -:::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Chars/chars1.cs" interactive="try-dotnet" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Chars/chars1.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.stringbuilder.chars/vb/chars1.vb" id="Snippet1"::: - -[!INCLUDE[stringbuilder-performance-note](~/includes/stringbuilder-perf-note.md)] + . The first character in the string is at index 0. The length of a string is the number of characters it contains. The last accessible character of a instance is at index - 1. + + is the default property of the class. In C#, it is an indexer. This means that individual characters can be retrieved from the property as shown in the following example, which counts the number of alphabetic, white-space, and punctuation characters in a string. + +:::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Chars/chars1.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Chars/chars1.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.stringbuilder.chars/vb/chars1.vb" id="Snippet1"::: + +[!INCLUDE[stringbuilder-performance-note](~/includes/stringbuilder-perf-note.md)] ]]> @@ -4564,20 +4564,20 @@ The `index` parameter is the position of a character within the Removes all characters from the current instance. An object whose is 0 (zero). - is a convenience method that is equivalent to setting the property of the current instance to 0 (zero). - -## Examples - -The following example instantiates a object with a string, calls the method, and then appends a new string. - -:::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Clear/clear1.cs" interactive="try-dotnet" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Clear/clear1.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.stringbuilder.clear/vb/clear1.vb" id="Snippet1"::: - + is a convenience method that is equivalent to setting the property of the current instance to 0 (zero). + +## Examples + +The following example instantiates a object with a string, calls the method, and then appends a new string. + +:::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Clear/clear1.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Clear/clear1.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.stringbuilder.clear/vb/clear1.vb" id="Snippet1"::: + ]]> @@ -4627,13 +4627,13 @@ The following example instantiates a object wit The number of characters to be copied. Copies the characters from a specified segment of this instance to a destination span. - method is intended to be used in the rare situation when you need to efficiently copy successive sections of a object to an span. - - For example, your code could populate a object with a large number of characters then use the method to copy small, successive pieces of the object to an span where the pieces are processed. When all the data in the object is processed, the size of the object is set to zero and the cycle is repeated. - + method is intended to be used in the rare situation when you need to efficiently copy successive sections of a object to an span. + + For example, your code could populate a object with a large number of characters then use the method to copy small, successive pieces of the object to an span where the pieces are processed. When all the data in the object is processed, the size of the object is set to zero and the cycle is repeated. + ]]> @@ -4698,38 +4698,38 @@ The following example instantiates a object wit The number of characters to be copied. Copies the characters from a specified segment of this instance to a specified segment of a destination array. - method is intended to be used in the rare situation when you need to efficiently copy successive sections of a object to an array. The array should be a fixed size, preallocated, reusable, and possibly globally accessible. - - For example, your code could populate a object with a large number of characters then use the method to copy small, successive pieces of the object to an array where the pieces are processed. When all the data in the object is processed, the size of the object is set to zero and the cycle is repeated. - - - -## Examples - The following example demonstrates the method. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringbuilder.copyto2/CPP/ct2.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/CopyTo/ct2.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/CopyTo/ct2.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringbuilder.copyto2/VB/ct2.vb" id="Snippet1"::: - + method is intended to be used in the rare situation when you need to efficiently copy successive sections of a object to an array. The array should be a fixed size, preallocated, reusable, and possibly globally accessible. + + For example, your code could populate a object with a large number of characters then use the method to copy small, successive pieces of the object to an array where the pieces are processed. When all the data in the object is processed, the size of the object is set to zero and the cycle is repeated. + + + +## Examples + The following example demonstrates the method. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringbuilder.copyto2/CPP/ct2.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/CopyTo/ct2.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/CopyTo/ct2.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringbuilder.copyto2/VB/ct2.vb" id="Snippet1"::: + ]]> is . - , , or , is less than zero. - - -or- - + , , or , is less than zero. + + -or- + is greater than the length of this instance. - + is greater than the length of this instance. - - -or- - + + is greater than the length of this instance. + + -or- + + is greater than the length of . @@ -4779,28 +4779,28 @@ The following example instantiates a object wit Ensures that the capacity of this instance of is at least the specified value. The new capacity of this instance. - method. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringbuilder.ensurecapacity/CPP/cap.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Capacity/cap.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Capacity/cap.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringbuilder.ensurecapacity/VB/cap.vb" id="Snippet1"::: - + method. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringbuilder.ensurecapacity/CPP/cap.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Capacity/cap.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Capacity/cap.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringbuilder.ensurecapacity/VB/cap.vb" id="Snippet1"::: + ]]> - is less than zero. - - -or- - + is less than zero. + + -or- + Enlarging the value of this instance would exceed . @@ -4847,12 +4847,12 @@ The following example instantiates a object wit if the characters in this instance and are the same; otherwise, . - @@ -4918,22 +4918,22 @@ The `Equals` method performs an ordinal comparison to determine whether the char if this instance and have equal string, , and values; otherwise, . - , and values. The `Equals` method uses ordinal comparison to determine whether the strings are equal. - -**.NET Core 3.0 and later versions:** The current instance and `sb` are equal if the strings assigned to both objects are the same. To determine equality, the `Equals` method uses ordinal comparison. The and property values are not used in the comparison. - -## Examples - The following code uses the method to check whether two objects are equal. The method is called repeatedly after small changes are made to each object, and the results are displayed to the console. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringbuilder.ensurecapacity/CPP/cap.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Capacity/cap.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Capacity/cap.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringbuilder.ensurecapacity/VB/cap.vb" id="Snippet1"::: - + , and values. The `Equals` method uses ordinal comparison to determine whether the strings are equal. + +**.NET Core 3.0 and later versions:** The current instance and `sb` are equal if the strings assigned to both objects are the same. To determine equality, the `Equals` method uses ordinal comparison. The and property values are not used in the comparison. + +## Examples + The following code uses the method to check whether two objects are equal. The method is called repeatedly after small changes are made to each object, and the results are displayed to the console. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringbuilder.ensurecapacity/CPP/cap.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Capacity/cap.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Capacity/cap.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringbuilder.ensurecapacity/VB/cap.vb" id="Snippet1"::: + ]]> @@ -4970,35 +4970,35 @@ The `Equals` method performs an ordinal comparison to determine whether the char Returns an object that can be used to iterate through the chunks of characters represented in a created from this instance. An enumerator for the chunks in the . - chunk in sb.GetChunks()) - foreach(char ch in chunk.Span) - { /* operations on ch */ } -``` - -The purpose of this method is to efficiently extract the data of a *constant* . If the is modified while the chunk enumeration is incomplete, the result is undefined. is also not thread-safe, so operating on it with concurrent threads is illegal. - -The chunks returned are not guaranteed to remain unchanged if the is modified, so do not cache them for later use. - -Creating a from a (as the method does in the previous example) is expensive, so create a local variable for the span if you need to use it in a nested `for` statement. For example: - -```csharp -foreach (ReadOnlyMemory chunk in sb.GetChunks()) -{ - var span = chunk.Span; - for(int i = 0; i < span.Length; i++) - { - /* operations on span[i] */ - } -} -``` - + chunk in sb.GetChunks()) + foreach(char ch in chunk.Span) + { /* operations on ch */ } +``` + +The purpose of this method is to efficiently extract the data of a *constant* . If the is modified while the chunk enumeration is incomplete, the result is undefined. is also not thread-safe, so operating on it with concurrent threads is illegal. + +The chunks returned are not guaranteed to remain unchanged if the is modified, so do not cache them for later use. + +Creating a from a (as the method does in the previous example) is expensive, so create a local variable for the span if you need to use it in a nested `for` statement. For example: + +```csharp +foreach (ReadOnlyMemory chunk in sb.GetChunks()) +{ + var span = chunk.Span; + for(int i = 0; i < span.Length; i++) + { + /* operations on span[i] */ + } +} +``` + ]]> @@ -5015,16 +5015,16 @@ foreach (ReadOnlyMemory chunk in sb.GetChunks()) Inserts the string representation of a specified object into this instance at a specified character position. - method. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringbuilder.insert/CPP/insert.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Insert/insert.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Insert/insert.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringbuilder.insert/VB/insert.vb" id="Snippet1"::: - + method. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringbuilder.insert/CPP/insert.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Insert/insert.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Insert/insert.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringbuilder.insert/VB/insert.vb" id="Snippet1"::: + ]]> @@ -5077,11 +5077,11 @@ foreach (ReadOnlyMemory chunk in sb.GetChunks()) Inserts the string representation of a Boolean value into this instance at the specified character position. A reference to this instance after the insert operation has completed. - is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity is adjusted as needed. - + is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity is adjusted as needed. + ]]> @@ -5141,11 +5141,11 @@ foreach (ReadOnlyMemory chunk in sb.GetChunks()) Inserts the string representation of a specified 8-bit unsigned integer into this instance at the specified character position. A reference to this instance after the insert operation has completed. - is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. - + is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. + ]]> @@ -5211,18 +5211,18 @@ foreach (ReadOnlyMemory chunk in sb.GetChunks()) Inserts the string representation of a specified Unicode character into this instance at the specified character position. A reference to this instance after the insert operation has completed. - is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. - + is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. + ]]> - is less than zero or greater than the length of this instance. - - -or- - + is less than zero or greater than the length of this instance. + + -or- + Enlarging the value of this instance would exceed . @@ -5283,20 +5283,20 @@ foreach (ReadOnlyMemory chunk in sb.GetChunks()) Inserts the string representation of a specified array of Unicode characters into this instance at the specified character position. A reference to this instance after the insert operation has completed. - is not changed. - + is not changed. + ]]> - is less than zero or greater than the length of this instance. - - -or- - + is less than zero or greater than the length of this instance. + + -or- + Enlarging the value of this instance would exceed . @@ -5348,11 +5348,11 @@ foreach (ReadOnlyMemory chunk in sb.GetChunks()) Inserts the string representation of a decimal number into this instance at the specified character position. A reference to this instance after the insert operation has completed. - is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. - + is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. + ]]> @@ -5412,11 +5412,11 @@ foreach (ReadOnlyMemory chunk in sb.GetChunks()) Inserts the string representation of a double-precision floating-point number into this instance at the specified character position. A reference to this instance after the insert operation has completed. - is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. - + is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. + ]]> @@ -5476,11 +5476,11 @@ foreach (ReadOnlyMemory chunk in sb.GetChunks()) Inserts the string representation of a specified 16-bit signed integer into this instance at the specified character position. A reference to this instance after the insert operation has completed. - is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. - + is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. + ]]> @@ -5540,11 +5540,11 @@ foreach (ReadOnlyMemory chunk in sb.GetChunks()) Inserts the string representation of a specified 32-bit signed integer into this instance at the specified character position. A reference to this instance after the insert operation has completed. - is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. - + is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. + ]]> @@ -5604,11 +5604,11 @@ foreach (ReadOnlyMemory chunk in sb.GetChunks()) Inserts the string representation of a 64-bit signed integer into this instance at the specified character position. A reference to this instance after the insert operation has completed. - is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. - + is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. + ]]> @@ -5676,13 +5676,13 @@ foreach (ReadOnlyMemory chunk in sb.GetChunks()) Inserts the string representation of an object into this instance at the specified character position. A reference to this instance after the insert operation has completed. - is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. - - If `value` is `null`, the value of this instance is unchanged. - + is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. + + If `value` is `null`, the value of this instance is unchanged. + ]]> @@ -5738,12 +5738,12 @@ foreach (ReadOnlyMemory chunk in sb.GetChunks()) Inserts the sequence of characters into this instance at the specified character position. A reference to this instance after the insert operation has completed. - @@ -5802,11 +5802,11 @@ The existing characters are shifted to make room for the character sequence in t Inserts the string representation of a specified 8-bit signed integer into this instance at the specified character position. A reference to this instance after the insert operation has completed. - is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity is adjusted as needed. - + is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity is adjusted as needed. + ]]> @@ -5866,11 +5866,11 @@ The existing characters are shifted to make room for the character sequence in t Inserts the string representation of a single-precision floating point number into this instance at the specified character position. A reference to this instance after the insert operation has completed. - is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. - + is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. + ]]> @@ -5944,20 +5944,20 @@ The existing characters are shifted to make room for the character sequence in t Inserts a string into this instance at the specified character position. A reference to this instance after the insert operation has completed. - is not changed if `value` is `null`, or `value` is not `null` but its length is zero. - + is not changed if `value` is `null`, or `value` is not `null` but its length is zero. + ]]> - is less than zero or greater than the current length of this instance. - - -or- - + is less than zero or greater than the current length of this instance. + + -or- + The current length of this object plus the length of exceeds . @@ -6016,11 +6016,11 @@ The existing characters are shifted to make room for the character sequence in t Inserts the string representation of a 16-bit unsigned integer into this instance at the specified character position. A reference to this instance after the insert operation has completed. - is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. - + is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. + ]]> @@ -6086,12 +6086,12 @@ The existing characters are shifted to make room for the character sequence in t Inserts the string representation of a 32-bit unsigned integer into this instance at the specified character position. A reference to this instance after the insert operation has completed. - is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. - - + is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. + + ]]> @@ -6157,11 +6157,11 @@ The existing characters are shifted to make room for the character sequence in t Inserts the string representation of a 64-bit unsigned integer into this instance at the specified character position. A reference to this instance after the insert operation has completed. - is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. - + is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. + ]]> @@ -6237,20 +6237,20 @@ The existing characters are shifted to make room for the character sequence in t Inserts one or more copies of a specified string into this instance at the specified character position. A reference to this instance after insertion has completed. - object is not changed if `value` is `null`, `value` is not `null` but its length is zero, or `count` is zero. - + object is not changed if `value` is `null`, `value` is not `null` but its length is zero, or `count` is zero. + ]]> - is less than zero or greater than the current length of this instance. - - -or- - + is less than zero or greater than the current length of this instance. + + -or- + is less than zero. The current length of this object plus the length of times exceeds . @@ -6322,28 +6322,28 @@ The existing characters are shifted to make room for the character sequence in t Inserts the string representation of a specified subarray of Unicode characters into this instance at the specified character position. A reference to this instance after the insert operation has completed. - is , and and are not zero. - , , or is less than zero. - - -or- - - is greater than the length of this instance. - - -or- - - plus is not a position within . - - -or- - + , , or is less than zero. + + -or- + + is greater than the length of this instance. + + -or- + + plus is not a position within . + + -or- + Enlarging the value of this instance would exceed . @@ -6399,27 +6399,27 @@ The existing characters are shifted to make room for the character sequence in t Gets or sets the length of the current object. The length of this instance. - object is defined by its number of objects. - - Like the property, the property indicates the length of the current string object. Unlike the property, which is read-only, the property allows you to modify the length of the string stored to the object. - - If the specified length is less than the current length, the current object is truncated to the specified length. If the specified length is greater than the current length, the end of the string value of the current object is padded with the Unicode NULL character (U+0000). - - If the specified length is greater than the current capacity, increases so that it is greater than or equal to the specified length. - - - -## Examples - The following example demonstrates the property. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringbuilder.ensurecapacity/CPP/cap.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Capacity/cap.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Capacity/cap.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringbuilder.ensurecapacity/VB/cap.vb" id="Snippet1"::: - + object is defined by its number of objects. + + Like the property, the property indicates the length of the current string object. Unlike the property, which is read-only, the property allows you to modify the length of the string stored to the object. + + If the specified length is less than the current length, the current object is truncated to the specified length. If the specified length is greater than the current length, the end of the string value of the current object is padded with the Unicode NULL character (U+0000). + + If the specified length is greater than the current capacity, increases so that it is greater than or equal to the specified length. + + + +## Examples + The following example demonstrates the property. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringbuilder.ensurecapacity/CPP/cap.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Capacity/cap.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Capacity/cap.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringbuilder.ensurecapacity/VB/cap.vb" id="Snippet1"::: + ]]> The value specified for a set operation is less than zero or greater than . @@ -6467,13 +6467,13 @@ The existing characters are shifted to make room for the character sequence in t Gets the maximum capacity of this instance. The maximum number of characters this instance can hold. - . However, this value is implementation-specific and might be different in other or later implementations. You can explicitly set the maximum capacity of a object by calling the constructor. - -In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. - + . However, this value is implementation-specific and might be different in other or later implementations. You can explicitly set the maximum capacity of a object by calling the constructor. + +In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. + ]]> @@ -6532,24 +6532,24 @@ In .NET Core and in the .NET Framework 4.0 and later versions, when you instanti Removes the specified range of characters from this instance. A reference to this instance after the excise operation has completed. - [!NOTE] -> The method modifies the value of the current instance and returns that instance. It does not create and return a new object. - - - -## Examples - The following example demonstrates the method. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringbuilder.remove/CPP/remove.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Remove/remove.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Remove/remove.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringbuilder.remove/VB/remove.vb" id="Snippet1"::: - + [!NOTE] +> The method modifies the value of the current instance and returns that instance. It does not create and return a new object. + + + +## Examples + The following example demonstrates the method. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringbuilder.remove/CPP/remove.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Remove/remove.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Remove/remove.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringbuilder.remove/VB/remove.vb" id="Snippet1"::: + ]]> If or is less than zero, or + is greater than the length of this instance. @@ -6568,16 +6568,16 @@ In .NET Core and in the .NET Framework 4.0 and later versions, when you instanti Replaces all occurrences of a specified character or string in this instance with another specified character or string. - method. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringbuilder.replace/CPP/replace.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Replace/replace.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Replace/replace.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringbuilder.replace/VB/replace.vb" id="Snippet1"::: - + method. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringbuilder.replace/CPP/replace.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Replace/replace.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Replace/replace.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringbuilder.replace/VB/replace.vb" id="Snippet1"::: + ]]> @@ -6630,11 +6630,11 @@ In .NET Core and in the .NET Framework 4.0 and later versions, when you instanti Replaces all occurrences of a specified character in this instance with another specified character. A reference to this instance with replaced by . - instance is unchanged after the replacement. - + instance is unchanged after the replacement. + ]]> @@ -6746,11 +6746,11 @@ In .NET Core and in the .NET Framework 4.0 and later versions, when you instanti Replaces all occurrences of a specified string in this instance with another specified string. A reference to this instance with all instances of replaced by . - , all occurrences of `oldValue` are removed. - + , all occurrences of `oldValue` are removed. + ]]> @@ -6818,18 +6818,18 @@ In .NET Core and in the .NET Framework 4.0 and later versions, when you instanti Replaces, within a substring of this instance, all occurrences of a specified character with another specified character. A reference to this instance with replaced by in the range from to + -1. - object is unchanged after the replacement. - + object is unchanged after the replacement. + ]]> - + is greater than the length of the value of this instance. - - -or- - + + is greater than the length of the value of this instance. + + -or- + or is less than zero. @@ -6948,25 +6948,25 @@ In .NET Core and in the .NET Framework 4.0 and later versions, when you instanti Replaces, within a substring of this instance, all occurrences of a specified string with another specified string. A reference to this instance with all instances of replaced by in the range from to + - 1. - , all occurrences of `oldValue` are removed. - + , all occurrences of `oldValue` are removed. + ]]> is . The length of is zero. - or is less than zero. - - -or- - - plus indicates a character position not within this instance. - - -or- - + or is less than zero. + + -or- + + plus indicates a character position not within this instance. + + -or- + Enlarging the value of this instance would exceed . @@ -7014,21 +7014,21 @@ In .NET Core and in the .NET Framework 4.0 and later versions, when you instanti System.Void - - + + The object to populate with serialization information. The place to store and retrieve serialized data. Reserved for future use. Populates a object with the data necessary to deserialize the current object. - method. - + method. + ]]> @@ -7097,21 +7097,21 @@ In .NET Core and in the .NET Framework 4.0 and later versions, when you instanti Converts the value of this instance to a . A string whose value is the same as this instance. - method to convert the object to a object before you can pass the string represented by the object to a method that has a parameter or display it in the user interface. - - - -## Examples - The following example demonstrates calling the method. This example is part of a larger example provided for the class. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/StringBuilder/cpp/StringBuilder.cpp" id="Snippet5"::: - :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Overview/StringBuilder.cs" id="Snippet5"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Overview/StringBuilder.fs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/StringBuilder/VB/StringBuilder.vb" id="Snippet5"::: - + method to convert the object to a object before you can pass the string represented by the object to a method that has a parameter or display it in the user interface. + + + +## Examples + The following example demonstrates calling the method. This example is part of a larger example provided for the class. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/StringBuilder/cpp/StringBuilder.cpp" id="Snippet5"::: + :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Overview/StringBuilder.cs" id="Snippet5"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Overview/StringBuilder.fs" id="Snippet5"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/StringBuilder/VB/StringBuilder.vb" id="Snippet5"::: + ]]> @@ -7170,18 +7170,18 @@ In .NET Core and in the .NET Framework 4.0 and later versions, when you instanti Converts the value of a substring of this instance to a . A string whose value is the same as the specified substring of this instance. - method to convert the object to a object before you can pass the string represented by the object to a method that has a parameter or display it in the user interface. - + method to convert the object to a object before you can pass the string represented by the object to a method that has a parameter or display it in the user interface. + ]]> - or is less than zero. - - -or- - + or is less than zero. + + -or- + The sum of and is greater than the length of the current instance. diff --git a/xml/System.Text/UnicodeEncoding.xml b/xml/System.Text/UnicodeEncoding.xml index de6e8530c4a..a27033b090d 100644 --- a/xml/System.Text/UnicodeEncoding.xml +++ b/xml/System.Text/UnicodeEncoding.xml @@ -64,63 +64,63 @@ Represents a UTF-16 encoding of Unicode characters. - , see [Character Encoding in the .NET Framework](/dotnet/standard/base-types/character-encoding). - - The class represents a UTF-16 encoding. The encoder can use either big endian byte order (most significant byte first) or little endian byte order (least significant byte first). For example, the Latin Capital Letter A (code point U+0041) is serialized as follows (in hexadecimal): - -- Big endian byte order: 00 00 00 41 - -- Little endian byte order: 41 00 00 00 - - It is generally more efficient to store Unicode characters using the native byte order of a particular platform. For example, it is better to use the little endian byte order on little endian platforms, such as Intel computers. The class corresponds to the Windows code pages 1200 (little endian byte order) and 1201 (big endian byte order). You can determine the "endianness" of a particular architecture by calling the method. - - Optionally, the object provides a byte order mark (BOM), which is an array of bytes that can be prefixed to the sequence of bytes resulting from the encoding process. If the preamble contains a byte order mark (BOM), it helps the decoder determine the byte order and the transformation format or UTF. - - If the instance is configured to provide a BOM, you can retrieve it by calling the method; otherwise, the method returns an empty array. Note that, even if a object is configured for BOM support, you must include the BOM at the beginning of the encoded byte stream as appropriate; the encoding methods of the class do not do this automatically. + , see [Character Encoding in the .NET Framework](/dotnet/standard/base-types/character-encoding). + + The class represents a UTF-16 encoding. The encoder can use either big endian byte order (most significant byte first) or little endian byte order (least significant byte first). For example, the Latin Capital Letter A (code point U+0041) is serialized as follows (in hexadecimal): + +- Big endian byte order: 00 00 00 41 + +- Little endian byte order: 41 00 00 00 + + It is generally more efficient to store Unicode characters using the native byte order of a particular platform. For example, it is better to use the little endian byte order on little endian platforms, such as Intel computers. The class corresponds to the Windows code pages 1200 (little endian byte order) and 1201 (big endian byte order). You can determine the "endianness" of a particular architecture by calling the method. + + Optionally, the object provides a byte order mark (BOM), which is an array of bytes that can be prefixed to the sequence of bytes resulting from the encoding process. If the preamble contains a byte order mark (BOM), it helps the decoder determine the byte order and the transformation format or UTF. + + If the instance is configured to provide a BOM, you can retrieve it by calling the method; otherwise, the method returns an empty array. Note that, even if a object is configured for BOM support, you must include the BOM at the beginning of the encoded byte stream as appropriate; the encoding methods of the class do not do this automatically. > [!CAUTION] -> To enable error detection and to make the class instance more secure, you should instantiate a object by calling the constructor and setting its `throwOnInvalidBytes` argument to `true`. With error detection, a method that detects an invalid sequence of characters or bytes throws a . Without error detection, no exception is thrown, and the invalid sequence is generally ignored. - - You can instantiate a object in a number of ways, depending on whether you want to it to provide a byte order mark (BOM), whether you want big-endian or little-endian encoding, and whether you want to enable error detection. The following table lists the constructors and the properties that return a object. - -|Member|Endianness|BOM|Error detection| -|------------|----------------|---------|---------------------| -||Big-endian|Yes|No (Replacement fallback)| -||Little-endian|Yes|No (Replacement fallback)| -||Little-endian|Yes|No (Replacement fallback)| -||Configurable|Configurable|No (Replacement fallback)| -||Configurable|Configurable|Configurable| - - The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. - - Likewise, the method determines how many characters result in decoding a sequence of bytes, and the and methods perform the actual decoding. - - For an encoder or decoder that is able to save state information when encoding or decoding data that spans multiple blocks (such as string of 1 million characters that is encoded in 100,000-character segments), use the and properties, respectively. - - - -## Examples - The following example demonstrates how to encode a string of Unicode characters into a byte array by using a object. The byte array is decoded into a string to demonstrate that there is no loss of data. - +> To enable error detection and to make the class instance more secure, you should instantiate a object by calling the constructor and setting its `throwOnInvalidBytes` argument to `true`. With error detection, a method that detects an invalid sequence of characters or bytes throws a . Without error detection, no exception is thrown, and the invalid sequence is generally ignored. + + You can instantiate a object in a number of ways, depending on whether you want to it to provide a byte order mark (BOM), whether you want big-endian or little-endian encoding, and whether you want to enable error detection. The following table lists the constructors and the properties that return a object. + +|Member|Endianness|BOM|Error detection| +|------------|----------------|---------|---------------------| +||Big-endian|Yes|No (Replacement fallback)| +||Little-endian|Yes|No (Replacement fallback)| +||Little-endian|Yes|No (Replacement fallback)| +||Configurable|Configurable|No (Replacement fallback)| +||Configurable|Configurable|Configurable| + + The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. + + Likewise, the method determines how many characters result in decoding a sequence of bytes, and the and methods perform the actual decoding. + + For an encoder or decoder that is able to save state information when encoding or decoding data that spans multiple blocks (such as string of 1 million characters that is encoded in 100,000-character segments), use the and properties, respectively. + + + +## Examples + The following example demonstrates how to encode a string of Unicode characters into a byte array by using a object. The byte array is decoded into a string to demonstrate that there is no loss of data. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.UnicodeEncoding Example/CPP/snippet.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Text/UnicodeEncoding/Overview/snippet.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UnicodeEncoding Example/VB/snippet.vb" id="Snippet1"::: - The following example uses the same string as the previous one, except that it writes the encoded bytes to a file and prefixes the byte stream with a byte order mark (BOM). It then reads the file in two different ways: as a text file by using a object; and as a binary file. As you would expect, neither newly-read string includes the BOM. - + The following example uses the same string as the previous one, except that it writes the encoded bytes to a file and prefixes the byte stream with a byte order mark (BOM). It then reads the file in two different ways: as a text file by using a object; and as a binary file. As you would expect, neither newly-read string includes the BOM. + :::code language="csharp" source="~/snippets/csharp/System.Text/UnicodeEncoding/Overview/bom1.cs" interactive="try-dotnet" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UnicodeEncoding Example/VB/bom1.vb" id="Snippet2"::: @@ -185,21 +185,21 @@ Initializes a new instance of the class. - [!CAUTION] > For security reasons, you should enable error detection by calling the constructor and setting its `throwOnInvalidBytes` argument to `true`. - -## Examples - The following example demonstrates how to create a new instance and display the name of the encoding. - + +## Examples + The following example demonstrates how to create a new instance and display the name of the encoding. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.UnicodeEncoding.ctor Example/CPP/ctor.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Text/UnicodeEncoding/.ctor/ctor.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UnicodeEncoding.ctor Example/VB/ctor.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UnicodeEncoding.ctor Example/VB/ctor.vb" id="Snippet1"::: + ]]> @@ -248,25 +248,25 @@ to specify that the method returns a Unicode byte order mark; otherwise, . Initializes a new instance of the class. Parameters specify whether to use the big endian byte order and whether the method returns a Unicode byte order mark. - [!CAUTION] -> For security reasons, you should enable error detection by calling the constructor and setting its `throwOnInvalidBytes` argument to `true`. - - The `byteOrderMark` parameter controls the operation of the method. If `true`, the method returns a byte array containing the Unicode byte order mark (BOM) in UTF-16 format. If `false`, it returns a zero-length byte array. However, setting `byteOrderMark` to `true` does not cause the method to prefix the BOM at the beginning of the byte array, nor does it cause the method to include the number of bytes in the BOM in the byte count. - - - -## Examples - The following example demonstrates how to create a new instance specifying whether to support little endian or big endian byte ordering and the Unicode byte order mark. - +> For security reasons, you should enable error detection by calling the constructor and setting its `throwOnInvalidBytes` argument to `true`. + + The `byteOrderMark` parameter controls the operation of the method. If `true`, the method returns a byte array containing the Unicode byte order mark (BOM) in UTF-16 format. If `false`, it returns a zero-length byte array. However, setting `byteOrderMark` to `true` does not cause the method to prefix the BOM at the beginning of the byte array, nor does it cause the method to include the number of bytes in the BOM in the byte count. + + + +## Examples + The following example demonstrates how to create a new instance specifying whether to support little endian or big endian byte ordering and the Unicode byte order mark. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.UnicodeEncoding.ctor2 Example/CPP/ctor-boolean-boolean.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Text/UnicodeEncoding/.ctor/ctor-boolean-boolean.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UnicodeEncoding.ctor2 Example/VB/ctor-boolean-boolean.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UnicodeEncoding.ctor2 Example/VB/ctor-boolean-boolean.vb" id="Snippet1"::: + ]]> @@ -318,23 +318,23 @@ to specify that an exception should be thrown when an invalid encoding is detected; otherwise, . Initializes a new instance of the class. Parameters specify whether to use the big endian byte order, whether to provide a Unicode byte order mark, and whether to throw an exception when an invalid encoding is detected. - method. If `true`, the method returns a byte array containing the Unicode byte order mark (BOM) in UTF-16 format. If `false`, it returns a zero-length byte array. However, setting `byteOrderMark` to `true` does not cause the method to prefix the BOM at the beginning of the byte array, nor does it cause the method to include the number of bytes in the BOM in the byte count. - - If the `throwOnInvalidBytes` parameter is `true`, a method that detects an invalid byte sequence throws . Otherwise, the method does not throw an exception, and the invalid sequence is ignored. - + method. If `true`, the method returns a byte array containing the Unicode byte order mark (BOM) in UTF-16 format. If `false`, it returns a zero-length byte array. However, setting `byteOrderMark` to `true` does not cause the method to prefix the BOM at the beginning of the byte array, nor does it cause the method to include the number of bytes in the BOM in the byte count. + + If the `throwOnInvalidBytes` parameter is `true`, a method that detects an invalid byte sequence throws . Otherwise, the method does not throw an exception, and the invalid sequence is ignored. + > [!CAUTION] -> For security reasons, you should use this constructor to create an instance of the class and turn on error detection by setting `throwOnInvalidBytes` to `true`. - -## Examples - The following example demonstrates the behavior of , both with error detection enabled and without. - +> For security reasons, you should use this constructor to create an instance of the class and turn on error detection by setting `throwOnInvalidBytes` to `true`. + +## Examples + The following example demonstrates the behavior of , both with error detection enabled and without. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.UnicodeEncoding.ErrorDetection/CPP/errordetection.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Text/UnicodeEncoding/.ctor/errordetection.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UnicodeEncoding.ErrorDetection/VB/errordetection.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UnicodeEncoding.ErrorDetection/VB/errordetection.vb" id="Snippet1"::: + ]]> @@ -378,20 +378,20 @@ Represents the Unicode character size in bytes. This field is a constant. - and display it. - + and display it. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.UnicodeEncoding.CharSize Example/CPP/charsize.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Text/UnicodeEncoding/CharSize/charsize.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UnicodeEncoding.CharSize Example/VB/charsize.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UnicodeEncoding.CharSize Example/VB/charsize.vb" id="Snippet1"::: + ]]> @@ -455,28 +455,28 @@ if is an instance of and is equal to the current object; otherwise, . - objects are considered equal if all of the following conditions are true: - -- Both objects use the same byte order (little-endian or big-endian). - -- Both objects provide the byte order mark, or both do not. - -- Both objects use the same encoder fallback. - -- Both objects use the same decoder fallback. - - - -## Examples - The following example demonstrates how to use the method to test whether the current object is equal to a different object. Five objects are created and compared, and the results of the comparisons are displayed. - + objects are considered equal if all of the following conditions are true: + +- Both objects use the same byte order (little-endian or big-endian). + +- Both objects provide the byte order mark, or both do not. + +- Both objects use the same encoder fallback. + +- Both objects use the same decoder fallback. + + + +## Examples + The following example demonstrates how to use the method to test whether the current object is equal to a different object. Five objects are created and compared, and the results of the comparisons are displayed. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.UnicodeEncoding.ctor2 Example/CPP/ctor-boolean-boolean.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Text/UnicodeEncoding/.ctor/ctor-boolean-boolean.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UnicodeEncoding.ctor2 Example/VB/ctor-boolean-boolean.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UnicodeEncoding.ctor2 Example/VB/ctor-boolean-boolean.vb" id="Snippet1"::: + ]]> @@ -544,24 +544,24 @@ Calculates the number of bytes produced by encoding the characters in the specified string. The number of bytes produced by encoding the specified characters. - to store the resulting bytes, you call the method. To calculate the maximum array size, you call the method. The method generally allocates less memory, while the method generally executes faster. - - With error detection, an invalid sequence causes this method to throw a . Without error detection, invalid sequences are ignored, and no exception is thrown. - + to store the resulting bytes, you call the method. To calculate the maximum array size, you call the method. The method generally allocates less memory, while the method generally executes faster. + + With error detection, an invalid sequence causes this method to throw a . Without error detection, invalid sequences are ignored, and no exception is thrown. + > [!IMPORTANT] -> To ensure that the encoded bytes are decoded properly when they are saved as a file or as a stream, you can prefix a stream of encoded bytes with a preamble. Inserting the preamble at the beginning of a byte stream (such as at the beginning of a series of bytes to be written to a file) is the developer's responsibility, and the number of bytes in the preamble is not reflected in the value returned by the method. - - - -## Examples - The following example calls the and methods to calculate the maximum and actual number of bytes required to encode a string. It also displays the actual number of bytes required to store a byte stream with a byte order mark. - +> To ensure that the encoded bytes are decoded properly when they are saved as a file or as a stream, you can prefix a stream of encoded bytes with a preamble. Inserting the preamble at the beginning of a byte stream (such as at the beginning of a series of bytes to be written to a file) is the developer's responsibility, and the number of bytes in the preamble is not reflected in the value returned by the method. + + + +## Examples + The following example calls the and methods to calculate the maximum and actual number of bytes required to encode a string. It also displays the actual number of bytes required to store a byte stream with a byte order mark. + :::code language="csharp" source="~/snippets/csharp/System.Text/UnicodeEncoding/GetByteCount/getbytecount1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.unicodeencoding.getbytecount/vb/getbytecount1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.unicodeencoding.getbytecount/vb/getbytecount1.vb" id="Snippet1"::: + ]]> @@ -569,9 +569,9 @@ The resulting number of bytes is greater than the maximum number that can be returned as an integer. Error detection is enabled, and contains an invalid sequence of characters. A fallback occurred (for more information, see Character Encoding in .NET) - - -and- - + + -and- + is set to . @@ -629,8 +629,8 @@ System.Int32 - - + + A pointer to the first character to encode. @@ -638,31 +638,31 @@ Calculates the number of bytes produced by encoding a set of characters starting at the specified character pointer. The number of bytes produced by encoding the specified characters. - requires to store the resulting bytes, you call the method. To calculate the maximum array size, you call the method. The method generally allocates less memory, while the method generally executes faster. - - With error detection, an invalid sequence causes this method to throw a . Without error detection, invalid sequences are ignored, and no exception is thrown. - + requires to store the resulting bytes, you call the method. To calculate the maximum array size, you call the method. The method generally allocates less memory, while the method generally executes faster. + + With error detection, an invalid sequence causes this method to throw a . Without error detection, invalid sequences are ignored, and no exception is thrown. + > [!IMPORTANT] -> To ensure that the encoded bytes are decoded properly when they are saved as a file or as a stream, you can prefix a stream of encoded bytes with a preamble. Inserting the preamble at the beginning of a byte stream (such as at the beginning of a series of bytes to be written to a file) is the developer's responsibility, and the number of bytes in the preamble is not reflected in the value returned by the method. - +> To ensure that the encoded bytes are decoded properly when they are saved as a file or as a stream, you can prefix a stream of encoded bytes with a preamble. Inserting the preamble at the beginning of a byte stream (such as at the beginning of a series of bytes to be written to a file) is the developer's responsibility, and the number of bytes in the preamble is not reflected in the value returned by the method. + ]]> is . - is less than zero. - - -or- - + is less than zero. + + -or- + The resulting number of bytes is greater than the maximum number that can be returned as an integer. Error detection is enabled and contains an invalid sequence of characters. A fallback occurred (for more information, see Character Encoding in .NET) - - -and- - + + -and- + is set to . @@ -723,42 +723,42 @@ Calculates the number of bytes produced by encoding a set of characters from the specified character array. The number of bytes produced by encoding the specified characters. - to store the resulting bytes, the application uses . To calculate the maximum array size, you call the method. The method generally allocates less memory, while the method generally executes faster. - - With error detection enabled, an invalid sequence causes this method to throw an . Without error detection, invalid sequences are ignored, and no exception is thrown. - - To ensure that the encoded bytes are decoded properly when they are saved as a file or as a stream, you can prefix a stream of encoded bytes with a preamble. Inserting the preamble at the beginning of a byte stream (such as at the beginning of a series of bytes to be written to a file) is the developer's responsibility, and the number of bytes in the preamble Is not reflected in the value returned by the method. - - - -## Examples - The following example populates an array with a Latin uppercase and lowercase characters and calls the method to determine the number of bytes needed to encode the Latin lowercase characters. It then displays this information along with the total number of bytes needed if a byte order mark is added. It compares this number with the value returned by the method, which indicates maximum number of bytes needed to encode the Latin lowercase characters. The following example populates an array with a combination of Greek and Cyrillic characters and calls the method to determine the number of bytes needed to encode the Cyrillic characters. It then displays this information along with the total number of bytes needed if a byte order mark is added. It compares this number with the value returned by the method, which indicates maximum number of bytes needed to encode the Cyrillic characters. - + to store the resulting bytes, the application uses . To calculate the maximum array size, you call the method. The method generally allocates less memory, while the method generally executes faster. + + With error detection enabled, an invalid sequence causes this method to throw an . Without error detection, invalid sequences are ignored, and no exception is thrown. + + To ensure that the encoded bytes are decoded properly when they are saved as a file or as a stream, you can prefix a stream of encoded bytes with a preamble. Inserting the preamble at the beginning of a byte stream (such as at the beginning of a series of bytes to be written to a file) is the developer's responsibility, and the number of bytes in the preamble Is not reflected in the value returned by the method. + + + +## Examples + The following example populates an array with a Latin uppercase and lowercase characters and calls the method to determine the number of bytes needed to encode the Latin lowercase characters. It then displays this information along with the total number of bytes needed if a byte order mark is added. It compares this number with the value returned by the method, which indicates maximum number of bytes needed to encode the Latin lowercase characters. The following example populates an array with a combination of Greek and Cyrillic characters and calls the method to determine the number of bytes needed to encode the Cyrillic characters. It then displays this information along with the total number of bytes needed if a byte order mark is added. It compares this number with the value returned by the method, which indicates maximum number of bytes needed to encode the Cyrillic characters. + :::code language="csharp" source="~/snippets/csharp/System.Text/UnicodeEncoding/GetByteCount/getbytecount2.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.unicodeencoding.getbytecount/vb/getbytecount2.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.unicodeencoding.getbytecount/vb/getbytecount2.vb" id="Snippet2"::: + ]]> is (). - or is less than zero. - - -or- - - and do not denote a valid range in . - - -or- - + or is less than zero. + + -or- + + and do not denote a valid range in . + + -or- + The resulting number of bytes is greater than the maximum number that can be returned as an integer. Error detection is enabled, and contains an invalid sequence of characters. A fallback occurred (for more information, see Character Encoding in .NET) - - -and- - + + -and- + is set to . @@ -857,10 +857,10 @@ System.Int32 - - - - + + + + A pointer to the first character to encode. @@ -870,37 +870,37 @@ Encodes a set of characters starting at the specified character pointer into a sequence of bytes that are stored starting at the specified byte pointer. The actual number of bytes written at the location indicated by the parameter. - requires to store the resulting bytes, you call the method. To calculate the maximum array size, you call the method. The method generally allocates less memory, while the method generally executes faster. - - With error detection, an invalid sequence causes this method to throw a . Without error detection, invalid sequences are ignored, and no exception is thrown. - - Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, the application should use the or the object provided by the or the method, respectively. - + requires to store the resulting bytes, you call the method. To calculate the maximum array size, you call the method. The method generally allocates less memory, while the method generally executes faster. + + With error detection, an invalid sequence causes this method to throw a . Without error detection, invalid sequences are ignored, and no exception is thrown. + + Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, the application should use the or the object provided by the or the method, respectively. + > [!IMPORTANT] -> To ensure that the encoded bytes are decoded properly when they are saved as a file or as a stream, you can prefix a stream of encoded bytes with a preamble. Inserting the preamble at the beginning of a byte stream (such as at the beginning of a series of bytes to be written to a file) is the developer's responsibility. The method does not prepend a preamble to the beginning of a sequence of encoded bytes. - +> To ensure that the encoded bytes are decoded properly when they are saved as a file or as a stream, you can prefix a stream of encoded bytes with a preamble. Inserting the preamble at the beginning of a byte stream (such as at the beginning of a series of bytes to be written to a file) is the developer's responsibility. The method does not prepend a preamble to the beginning of a sequence of encoded bytes. + ]]> - is (). - - -or- - + is (). + + -or- + is (). or is less than zero. - Error detection is enabled, and contains an invalid sequence of characters. - - -or- - + Error detection is enabled, and contains an invalid sequence of characters. + + -or- + is less than the resulting number of bytes. A fallback occurred (for more information, see Character Encoding in .NET) - - -and- - + + -and- + is set to . @@ -965,23 +965,23 @@ Encodes a set of characters from the specified character array into the specified byte array. The actual number of bytes written into . - to store the resulting bytes, you call the method. To calculate the maximum array size, you call the method. The method generally allocates less memory, while the method generally executes faster. - - With error detection, an invalid sequence causes this method to throw a . Without error detection, invalid sequences are ignored, and no exception is thrown. - - Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, the application should use the or the provided by the method or the method, respectively. - + to store the resulting bytes, you call the method. To calculate the maximum array size, you call the method. The method generally allocates less memory, while the method generally executes faster. + + With error detection, an invalid sequence causes this method to throw a . Without error detection, invalid sequences are ignored, and no exception is thrown. + + Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, the application should use the or the provided by the method or the method, respectively. + > [!IMPORTANT] -> To ensure that the encoded bytes are decoded properly when they are saved as a file or as a stream, you can prefix a stream of encoded bytes with a preamble. Inserting the preamble at the beginning of a byte stream (such as at the beginning of a series of bytes to be written to a file) is the developer's responsibility. The method does not prepend a preamble to the beginning of a sequence of encoded bytes. - - - -## Examples - The following example demonstrates how to use the method to encode a range of characters from a and store the encoded bytes in a range of elements in a byte array. - +> To ensure that the encoded bytes are decoded properly when they are saved as a file or as a stream, you can prefix a stream of encoded bytes with a preamble. Inserting the preamble at the beginning of a byte stream (such as at the beginning of a series of bytes to be written to a file) is the developer's responsibility. The method does not prepend a preamble to the beginning of a sequence of encoded bytes. + + + +## Examples + The following example demonstrates how to use the method to encode a range of characters from a and store the encoded bytes in a range of elements in a byte array. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.UnicodeEncoding.GetBytes3 Example/CPP/getbytes-string-int32-int32-byte[]-int32.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Text/UnicodeEncoding/GetBytes/getbytes-string-int32-int32-byte[]-int32.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UnicodeEncoding.GetBytes3 Example/VB/getbytes-string-int32-int32-byte[]-int32.vb" id="Snippet1"::: @@ -989,30 +989,30 @@ ]]> - is (). - - -or- - + is (). + + -or- + is (). - or or is less than zero. - - -or- - - and do not denote a valid range in . - - -or- - + or or is less than zero. + + -or- + + and do not denote a valid range in . + + -or- + is not a valid index in . - Error detection is enabled, and contains an invalid sequence of characters. - - -or- - + Error detection is enabled, and contains an invalid sequence of characters. + + -or- + does not have enough capacity from to the end of the array to accommodate the resulting bytes. A fallback occurred (for more information, see Character Encoding in .NET) - - -and- - + + -and- + is set to . @@ -1077,23 +1077,23 @@ Encodes a set of characters from the specified into the specified byte array. The actual number of bytes written into . - to store the resulting bytes, you call the method. To calculate the maximum array size, you call the method. The method generally allocates less memory, while the method generally executes faster. - - With error detection, an invalid sequence causes this method to throw a . Without error detection, invalid sequences are ignored, and no exception is thrown. - - Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, the application should use the or the provided by the method or the method, respectively. - + to store the resulting bytes, you call the method. To calculate the maximum array size, you call the method. The method generally allocates less memory, while the method generally executes faster. + + With error detection, an invalid sequence causes this method to throw a . Without error detection, invalid sequences are ignored, and no exception is thrown. + + Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, the application should use the or the provided by the method or the method, respectively. + > [!IMPORTANT] -> To ensure that the encoded bytes are decoded properly when they are saved as a file or as a stream, you can prefix a stream of encoded bytes with a preamble. Inserting the preamble at the beginning of a byte stream (such as at the beginning of a series of bytes to be written to a file) is the developer's responsibility. The method does not prepend a preamble to the beginning of a sequence of encoded bytes. - - - -## Examples - The following example demonstrates how to encode a range of elements from a Unicode character array and store the encoded bytes in a range of elements in a byte array. - +> To ensure that the encoded bytes are decoded properly when they are saved as a file or as a stream, you can prefix a stream of encoded bytes with a preamble. Inserting the preamble at the beginning of a byte stream (such as at the beginning of a series of bytes to be written to a file) is the developer's responsibility. The method does not prepend a preamble to the beginning of a sequence of encoded bytes. + + + +## Examples + The following example demonstrates how to encode a range of elements from a Unicode character array and store the encoded bytes in a range of elements in a byte array. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.UnicodeEncoding.GetBytes1 Example/CPP/getbytes-char[]-int32-int32-byte[]-int32.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Text/UnicodeEncoding/GetBytes/getbytes-char[]-int32-int32-byte[]-int32.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UnicodeEncoding.GetBytes1 Example/VB/getbytes-char[]-int32-int32-byte[]-int32.vb" id="Snippet1"::: @@ -1101,30 +1101,30 @@ ]]> - is . - - -or- - + is . + + -or- + is (). - or or is less than zero. - - -or- - - and do not denote a valid range in . - - -or- - + or or is less than zero. + + -or- + + and do not denote a valid range in . + + -or- + is not a valid index in . - Error detection is enabled, and contains an invalid sequence of characters. - - -or- - + Error detection is enabled, and contains an invalid sequence of characters. + + -or- + does not have enough capacity from to the end of the array to accommodate the resulting bytes. A fallback occurred (for more information, see Character Encoding in .NET) - - -and- - + + -and- + is set to . @@ -1192,8 +1192,8 @@ System.Int32 - - + + A pointer to the first byte to decode. @@ -1201,28 +1201,28 @@ Calculates the number of characters produced by decoding a sequence of bytes starting at the specified byte pointer. The number of characters produced by decoding the specified sequence of bytes. - requires to store the resulting characters, the application uses . To calculate the maximum array size, the application should use . The method generally allocates less memory, while the method generally executes faster. - - With error detection, an invalid sequence causes this method to throw a . Without error detection, invalid sequences are ignored, and no exception is thrown. - + requires to store the resulting characters, the application uses . To calculate the maximum array size, the application should use . The method generally allocates less memory, while the method generally executes faster. + + With error detection, an invalid sequence causes this method to throw a . Without error detection, invalid sequences are ignored, and no exception is thrown. + ]]> is (). - is less than zero. - - -or- - + is less than zero. + + -or- + The resulting number of bytes is greater than the maximum number that can be returned as an integer. Error detection is enabled, and contains an invalid sequence of bytes. A fallback occurred (for more information, see Character Encoding in .NET) - - -and- - + + -and- + is set to . @@ -1283,41 +1283,41 @@ Calculates the number of characters produced by decoding a sequence of bytes from the specified byte array. The number of characters produced by decoding the specified sequence of bytes. - to store the resulting characters, the application uses . To calculate the maximum array size, the application should use . The method generally allocates less memory, while the method generally executes faster. - - With error detection, an invalid sequence causes this method to throw a . Without error detection, invalid sequences are ignored, and no exception is thrown. - - - -## Examples - The following example demonstrates how to use the method to return the number of characters produced by decoding a range of elements in a byte array using . - + to store the resulting characters, the application uses . To calculate the maximum array size, the application should use . The method generally allocates less memory, while the method generally executes faster. + + With error detection, an invalid sequence causes this method to throw a . Without error detection, invalid sequences are ignored, and no exception is thrown. + + + +## Examples + The following example demonstrates how to use the method to return the number of characters produced by decoding a range of elements in a byte array using . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.UnicodeEncoding.GetCharCount Example/CPP/getcharcount-byte[]-int32-int32.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Text/UnicodeEncoding/GetCharCount/getcharcount-byte[]-int32-int32.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UnicodeEncoding.GetCharCount Example/VB/getcharcount-byte[]-int32-int32.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UnicodeEncoding.GetCharCount Example/VB/getcharcount-byte[]-int32-int32.vb" id="Snippet1"::: + ]]> is (). - or is less than zero. - - -or- - - and do not denote a valid range in . - - -or- - + or is less than zero. + + -or- + + and do not denote a valid range in . + + -or- + The resulting number of bytes is greater than the maximum number that can be returned as an integer. Error detection is enabled, and contains an invalid sequence of bytes. A fallback occurred (for more information, see Character Encoding in .NET) - - -and- - + + -and- + is set to . @@ -1385,10 +1385,10 @@ System.Int32 - - - - + + + + A pointer to the first byte to decode. @@ -1398,36 +1398,36 @@ Decodes a sequence of bytes starting at the specified byte pointer into a set of characters that are stored starting at the specified character pointer. The actual number of characters written at the location indicated by the parameter. - requires to store the resulting characters, the application uses . To calculate the maximum array size, the application should use . The method generally allocates less memory, while the method generally executes faster. - - With error detection, an invalid sequence causes this method to throw a . Without error detection, invalid sequences are ignored, and no exception is thrown. - - If the range of bytes to be decoded includes the byte order mark (BOM) and the byte array was returned by a method of a non-BOM aware type, the character U+FFFE is included in the character array returned by this method. You can remove it by calling the method. - - Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, the application should use the or the object provided by the or the method, respectively. - + requires to store the resulting characters, the application uses . To calculate the maximum array size, the application should use . The method generally allocates less memory, while the method generally executes faster. + + With error detection, an invalid sequence causes this method to throw a . Without error detection, invalid sequences are ignored, and no exception is thrown. + + If the range of bytes to be decoded includes the byte order mark (BOM) and the byte array was returned by a method of a non-BOM aware type, the character U+FFFE is included in the character array returned by this method. You can remove it by calling the method. + + Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, the application should use the or the object provided by the or the method, respectively. + ]]> - is (). - - -or- - + is (). + + -or- + is (). or is less than zero. - Error detection is enabled, and contains an invalid sequence of bytes. - - -or- - + Error detection is enabled, and contains an invalid sequence of bytes. + + -or- + is less than the resulting number of characters. A fallback occurred (for more information, see Character Encoding in .NET) - - -and- - + + -and- + is set to . @@ -1493,53 +1493,53 @@ Decodes a sequence of bytes from the specified byte array into the specified character array. The actual number of characters written into . - to store the resulting characters, the application uses . To calculate the maximum array size, the application should use . The method generally allocates less memory, while the method generally executes faster. - - With error detection, an invalid sequence causes this method to throw a . Without error detection, invalid sequences are ignored, and no exception is thrown. - - If the range of bytes to be decoded includes the byte order mark (BOM) and the byte array was returned by a method of a non-BOM aware type, the character U+FFFE is included in the character array returned by this method. You can remove it by calling the method. - - Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, the application should use the or the provided by the method or the method, respectively. - - - -## Examples - The following example demonstrates how to use the method to decode a range of elements in a byte array and store the result in a character array. - + to store the resulting characters, the application uses . To calculate the maximum array size, the application should use . The method generally allocates less memory, while the method generally executes faster. + + With error detection, an invalid sequence causes this method to throw a . Without error detection, invalid sequences are ignored, and no exception is thrown. + + If the range of bytes to be decoded includes the byte order mark (BOM) and the byte array was returned by a method of a non-BOM aware type, the character U+FFFE is included in the character array returned by this method. You can remove it by calling the method. + + Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, the application should use the or the provided by the method or the method, respectively. + + + +## Examples + The following example demonstrates how to use the method to decode a range of elements in a byte array and store the result in a character array. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.UnicodeEncoding.GetChars Example/CPP/getchars-byte[]-int32-int32-char[]-int32.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Text/UnicodeEncoding/GetChars/getchars-byte[]-int32-int32-char[]-int32.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UnicodeEncoding.GetChars Example/VB/getchars-byte[]-int32-int32-char[]-int32.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UnicodeEncoding.GetChars Example/VB/getchars-byte[]-int32-int32-char[]-int32.vb" id="Snippet1"::: + ]]> - is (). - - -or- - + is (). + + -or- + is (). - or or is less than zero. - - -or- - - and do not denote a valid range in . - - -or- - + or or is less than zero. + + -or- + + and do not denote a valid range in . + + -or- + is not a valid index in . - Error detection is enabled, and contains an invalid sequence of bytes. - - -or- - + Error detection is enabled, and contains an invalid sequence of bytes. + + -or- + does not have enough capacity from to the end of the array to accommodate the resulting characters. A fallback occurred (for more information, see Character Encoding in .NET) - - -and- - + + -and- + is set to . @@ -1588,22 +1588,22 @@ Obtains a decoder that converts a UTF-16 encoded sequence of bytes into a sequence of Unicode characters. A that converts a UTF-16 encoded sequence of bytes into a sequence of Unicode characters. - method converts sequential blocks of bytes into sequential blocks of characters, in a manner similar to the . However, a maintains state information between calls so it can correctly decode byte sequences that span blocks. The also preserves trailing bytes at the end of data blocks and uses the trailing bytes in the next decoding operation. Therefore, and are useful for network transmission and file operations, because those operations often deal with blocks of data instead of a complete data stream. - - If error detection is enabled, that is, the `throwOnInvalidBytes` parameter of the constructor is set to `true`, error detection is also enabled in the returned by this method. If error detection is enabled and an invalid sequence is encountered, the state of the decoder is undefined and processing must stop. - - - -## Examples - The following example uses an encoder and a decoder to encode a string into an array of bytes, and then decode the bytes into an array of characters. - + method converts sequential blocks of bytes into sequential blocks of characters, in a manner similar to the . However, a maintains state information between calls so it can correctly decode byte sequences that span blocks. The also preserves trailing bytes at the end of data blocks and uses the trailing bytes in the next decoding operation. Therefore, and are useful for network transmission and file operations, because those operations often deal with blocks of data instead of a complete data stream. + + If error detection is enabled, that is, the `throwOnInvalidBytes` parameter of the constructor is set to `true`, error detection is also enabled in the returned by this method. If error detection is enabled and an invalid sequence is encountered, the state of the decoder is undefined and processing must stop. + + + +## Examples + The following example uses an encoder and a decoder to encode a string into an array of bytes, and then decode the bytes into an array of characters. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.UnicodeEncoding.EncDec/CPP/encdec.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Text/UnicodeEncoding/GetDecoder/encdec.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UnicodeEncoding.EncDec/VB/encdec.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UnicodeEncoding.EncDec/VB/encdec.vb" id="Snippet1"::: + ]]> @@ -1660,22 +1660,22 @@ Obtains an encoder that converts a sequence of Unicode characters into a UTF-16 encoded sequence of bytes. A object that converts a sequence of Unicode characters into a UTF-16 encoded sequence of bytes. - method converts sequential blocks of characters into sequential blocks of bytes in a manner similar to the method of this class. However, a object maintains state information between calls so that it can correctly encode character sequences that span blocks. The object also preserves trailing characters at the end of data blocks and uses the trailing characters in the next encoding operation. For example, a data block might end with an unmatched high surrogate, and the matching low surrogate might be in the next data block. Therefore, and are useful for network transmission and file operations, because those operations often deal with blocks of data instead of a complete data stream. - - If error detection is enabled, that is, the `throwOnInvalidBytes` parameter of the constructor is set to `true`, error detection is also enabled in the object returned by this method. If error detection is enabled and an invalid sequence is encountered, the state of the encoder is undefined and processing must stop. - - - -## Examples - The following example uses an encoder and a decoder to encode a string into an array of bytes, and then decode the bytes into an array of characters. - + method converts sequential blocks of characters into sequential blocks of bytes in a manner similar to the method of this class. However, a object maintains state information between calls so that it can correctly encode character sequences that span blocks. The object also preserves trailing characters at the end of data blocks and uses the trailing characters in the next encoding operation. For example, a data block might end with an unmatched high surrogate, and the matching low surrogate might be in the next data block. Therefore, and are useful for network transmission and file operations, because those operations often deal with blocks of data instead of a complete data stream. + + If error detection is enabled, that is, the `throwOnInvalidBytes` parameter of the constructor is set to `true`, error detection is also enabled in the object returned by this method. If error detection is enabled and an invalid sequence is encountered, the state of the encoder is undefined and processing must stop. + + + +## Examples + The following example uses an encoder and a decoder to encode a string into an array of bytes, and then decode the bytes into an array of characters. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.UnicodeEncoding.EncDec/CPP/encdec.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Text/UnicodeEncoding/GetDecoder/encdec.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UnicodeEncoding.EncDec/VB/encdec.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UnicodeEncoding.EncDec/VB/encdec.vb" id="Snippet1"::: + ]]> @@ -1773,41 +1773,41 @@ Calculates the maximum number of bytes produced by encoding the specified number of characters. The maximum number of bytes produced by encoding the specified number of characters. - to store the resulting bytes, the application uses . To calculate the maximum array size, the application should use . The method generally allocates less memory, while the method generally executes faster. - - retrieves a worst-case number, including the worst case for the currently selected . If a fallback is chosen with a potentially large string, can return large values. - - In most cases, this method retrieves reasonable numbers for small strings. For large strings, you might have to choose between using very large buffers and catching errors in the rare case that a more reasonable buffer is exceeded. You might also want to consider a different approach using or . - - has no relation to . If your application needs a similar function to use with , it should use . - + to store the resulting bytes, the application uses . To calculate the maximum array size, the application should use . The method generally allocates less memory, while the method generally executes faster. + + retrieves a worst-case number, including the worst case for the currently selected . If a fallback is chosen with a potentially large string, can return large values. + + In most cases, this method retrieves reasonable numbers for small strings. For large strings, you might have to choose between using very large buffers and catching errors in the rare case that a more reasonable buffer is exceeded. You might also want to consider a different approach using or . + + has no relation to . If your application needs a similar function to use with , it should use . + > [!NOTE] -> `GetMaxByteCount(N)` is not necessarily the same value as `N* GetMaxByteCount(1)`. - - - -## Examples - The following example demonstrates how to use the method to return the maximum number of bytes required to encode a specified number of characters. - +> `GetMaxByteCount(N)` is not necessarily the same value as `N* GetMaxByteCount(1)`. + + + +## Examples + The following example demonstrates how to use the method to return the maximum number of bytes required to encode a specified number of characters. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.UnicodeEncoding.GetMaxByteCount Example/CPP/getmaxbytecount-int32.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Text/UnicodeEncoding/GetMaxByteCount/getmaxbytecount-int32.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UnicodeEncoding.GetMaxByteCount Example/VB/getmaxbytecount-int32.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UnicodeEncoding.GetMaxByteCount Example/VB/getmaxbytecount-int32.vb" id="Snippet1"::: + ]]> - is less than zero. - - -or- - + is less than zero. + + -or- + The resulting number of bytes is greater than the maximum number that can be returned as an integer. A fallback occurred (for more information, see Character Encoding in .NET) - - -and- - + + -and- + is set to . @@ -1858,41 +1858,41 @@ Calculates the maximum number of characters produced by decoding the specified number of bytes. The maximum number of characters produced by decoding the specified number of bytes. - to store the resulting characters, the application uses . To calculate the maximum array size, the application should use . The method generally allocates less memory, while the method generally executes faster. - - retrieves a worst-case number, including the worst case for the currently selected . If a fallback is chosen with a potentially large string, retrieves large values. - - In most cases, this method retrieves reasonable numbers for small strings. For large strings, you might have to choose between using very large buffers and catching errors in the rare case that a more reasonable buffer is exceeded. You might also want to consider a different approach using or . - - has no relation to . If your application needs a similar function to use with , it should use . - + to store the resulting characters, the application uses . To calculate the maximum array size, the application should use . The method generally allocates less memory, while the method generally executes faster. + + retrieves a worst-case number, including the worst case for the currently selected . If a fallback is chosen with a potentially large string, retrieves large values. + + In most cases, this method retrieves reasonable numbers for small strings. For large strings, you might have to choose between using very large buffers and catching errors in the rare case that a more reasonable buffer is exceeded. You might also want to consider a different approach using or . + + has no relation to . If your application needs a similar function to use with , it should use . + > [!NOTE] -> `GetMaxCharCount(N)` is not necessarily the same value as `N* GetMaxCharCount(1)`. - - - -## Examples - The following example demonstrates how to use the method to return the maximum number of characters produced by decoding a specified number of bytes. - +> `GetMaxCharCount(N)` is not necessarily the same value as `N* GetMaxCharCount(1)`. + + + +## Examples + The following example demonstrates how to use the method to return the maximum number of characters produced by decoding a specified number of bytes. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.UnicodeEncoding.GetMaxCharCount Example/CPP/getmaxcharcount-int32.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Text/UnicodeEncoding/GetMaxCharCount/getmaxcharcount-int32.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UnicodeEncoding.GetMaxCharCount Example/VB/getmaxcharcount-int32.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UnicodeEncoding.GetMaxCharCount Example/VB/getmaxcharcount-int32.vb" id="Snippet1"::: + ]]> - is less than zero. - - -or- - + is less than zero. + + -or- + The resulting number of bytes is greater than the maximum number that can be returned as an integer. A fallback occurred (for more information, see Character Encoding in .NET) - - -and- - + + -and- + is set to . @@ -1941,48 +1941,48 @@ Returns a Unicode byte order mark encoded in UTF-16 format, if the constructor for this instance requests a byte order mark. A byte array containing the Unicode byte order mark, if the object is configured to supply one. Otherwise, this method returns a zero-length byte array. - object can provide a preamble, which is a byte array that can be prefixed to the sequence of bytes resulting from the encoding process. Prefacing a sequence of encoded bytes with a byte order mark (code point U+FEFF) helps the decoder determine the byte order and the transformation format or UTF. The Unicode byte order mark (BOM) is serialized as follows (in hexadecimal): - -- Big endian byte order: FE FF - -- Little endian byte order: FF FE - - You can instantiate a object whose method returns a valid BOM in the following ways: - -- By retrieving the object returned by the or property. - -- By calling the parameterless constructor to instantiate a object. - -- By supplying `true` as the value of the `byteOrderMark` argument to the or constructors. - - We recommended that you use the BOM, since it provides nearly certain identification of an encoding for files that otherwise have lost a reference to their encoding, such as untagged or improperly tagged web data or random text files stored when a business did not have international concerns. Often user problems might be avoided if data is consistently and properly tagged. - - For standards that provide an encoding type, a BOM is somewhat redundant. However, it can be used to help a server send the correct encoding header. Alternatively, it can be used as a fallback in case the encoding is otherwise lost. - - There are some disadvantages to using a BOM. For example, knowing how to limit the database fields that use a BOM can be difficult. Concatenation of files can be a problem also, for example, when files are merged in such a way that an unnecessary character can end up in the middle of data. In spite of the few disadvantages, however, the use of a BOM is highly recommended. - + object can provide a preamble, which is a byte array that can be prefixed to the sequence of bytes resulting from the encoding process. Prefacing a sequence of encoded bytes with a byte order mark (code point U+FEFF) helps the decoder determine the byte order and the transformation format or UTF. The Unicode byte order mark (BOM) is serialized as follows (in hexadecimal): + +- Big endian byte order: FE FF + +- Little endian byte order: FF FE + + You can instantiate a object whose method returns a valid BOM in the following ways: + +- By retrieving the object returned by the or property. + +- By calling the parameterless constructor to instantiate a object. + +- By supplying `true` as the value of the `byteOrderMark` argument to the or constructors. + + We recommended that you use the BOM, since it provides nearly certain identification of an encoding for files that otherwise have lost a reference to their encoding, such as untagged or improperly tagged web data or random text files stored when a business did not have international concerns. Often user problems might be avoided if data is consistently and properly tagged. + + For standards that provide an encoding type, a BOM is somewhat redundant. However, it can be used to help a server send the correct encoding header. Alternatively, it can be used as a fallback in case the encoding is otherwise lost. + + There are some disadvantages to using a BOM. For example, knowing how to limit the database fields that use a BOM can be difficult. Concatenation of files can be a problem also, for example, when files are merged in such a way that an unnecessary character can end up in the middle of data. In spite of the few disadvantages, however, the use of a BOM is highly recommended. + > [!IMPORTANT] -> To ensure that the encoded bytes are decoded properly, you should prefix the beginning of a stream of encoded bytes with a preamble. Note that the method does not prepend a BOM to a sequence of encoded bytes; supplying a BOM at the beginning of an appropriate byte stream is the developer's responsibility. - - - -## Examples - The following example demonstrates how to use the method to retrieve the Unicode byte order mark in big endian or little endian byte order for an instance of a . - +> To ensure that the encoded bytes are decoded properly, you should prefix the beginning of a stream of encoded bytes with a preamble. Note that the method does not prepend a BOM to a sequence of encoded bytes; supplying a BOM at the beginning of an appropriate byte stream is the developer's responsibility. + + + +## Examples + The following example demonstrates how to use the method to retrieve the Unicode byte order mark in big endian or little endian byte order for an instance of a . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Text.UnicodeEncoding.GetPreamble Example/CPP/getpreamble-.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Text/UnicodeEncoding/GetPreamble/getpreamble-.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UnicodeEncoding.GetPreamble Example/VB/getpreamble-.vb" id="Snippet1"::: - - The following example instantiates two objects, the first of which does not provide a BOM, and the second of which does. It then calls the method to write the BOM to a file before writing a Unicode-encoded string. As the console output from the example shows, the file that saves the bytes from the second encoder has three more bytes than the first. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.UnicodeEncoding.GetPreamble Example/VB/getpreamble-.vb" id="Snippet1"::: + + The following example instantiates two objects, the first of which does not provide a BOM, and the second of which does. It then calls the method to write the BOM to a file before writing a Unicode-encoded string. As the console output from the example shows, the file that saves the bytes from the second encoder has three more bytes than the first. + :::code language="csharp" source="~/snippets/csharp/System.Text/UnicodeEncoding/GetPreamble/GetPreamble1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/System.Text.UnicodeEncoding.GetPreamble/vb/GetPreamble1.vb" id="Snippet1"::: - - You can also compare the files by using the `fc` command in a console window, or you can inspect the files in a text editor that includes a Hex View mode. Note that when the file is opened in an editor that supports UTF-16 encoding, the BOM is not displayed. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/System.Text.UnicodeEncoding.GetPreamble/vb/GetPreamble1.vb" id="Snippet1"::: + + You can also compare the files by using the `fc` command in a console window, or you can inspect the files in a text editor that includes a Hex View mode. Note that when the file is opened in an editor that supports UTF-16 encoding, the BOM is not displayed. + ]]> @@ -2044,40 +2044,40 @@ Decodes a range of bytes from a byte array into a string. A object containing the results of decoding the specified sequence of bytes. - . Without error detection, invalid sequences are ignored, and no exception is thrown. - - If the range of bytes to be decoded includes the byte order mark (BOM) and the byte array was returned by a method of a non-BOM aware type, the character U+FFFE is included in the character array returned by this method. You can remove it by calling the method. - - Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, the application should use the or the object provided by the or the method, respectively. - - - -## Examples - The following example initializes an array by calling the method to determine exactly how many bytes are required for an encoded string and then adding the size of the byte order mark (BOM). The example then calls the method to store the BOM to the array before calling the method to store the encoded bytes to the array. The example then calls the method to decode the string. - + . Without error detection, invalid sequences are ignored, and no exception is thrown. + + If the range of bytes to be decoded includes the byte order mark (BOM) and the byte array was returned by a method of a non-BOM aware type, the character U+FFFE is included in the character array returned by this method. You can remove it by calling the method. + + Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, the application should use the or the object provided by the or the method, respectively. + + + +## Examples + The following example initializes an array by calling the method to determine exactly how many bytes are required for an encoded string and then adding the size of the byte order mark (BOM). The example then calls the method to store the BOM to the array before calling the method to store the encoded bytes to the array. The example then calls the method to decode the string. + :::code language="csharp" source="~/snippets/csharp/System.Text/UnicodeEncoding/GetString/getstring1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.utf8encoding.getstring/vb/getstring1.vb" id="Snippet1"::: - - Note that in this case the decoded string differs from the original string, since it begins with a 16-bit byte order mark U+FFFD. This means that the two strings will compare as unequal, and that if the string is output, the BOM will be displayed as the replacement character "?". To remove the BOM at the beginning of the string, you can call the method. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.text.utf8encoding.getstring/vb/getstring1.vb" id="Snippet1"::: + + Note that in this case the decoded string differs from the original string, since it begins with a 16-bit byte order mark U+FFFD. This means that the two strings will compare as unequal, and that if the string is output, the BOM will be displayed as the replacement character "?". To remove the BOM at the beginning of the string, you can call the method. + ]]> is (). - or is less than zero. - - -or- - + or is less than zero. + + -or- + and do not denote a valid range in . Error detection is enabled, and contains an invalid sequence of bytes. A fallback occurred (for more information, see Character Encoding in .NET) - - -and- - + + -and- + is set to . @@ -2126,32 +2126,32 @@ Gets a Unicode byte order mark encoded in UTF-16 format, if this object is configured to supply one. A byte span containing the Unicode byte order mark, if this object is configured to supply one; otherwise, the default span. - object can provide a preamble, which is a byte span that can be prepended to the sequence of bytes resulting from the encoding process. Prefacing a sequence of encoded bytes with a byte order mark (code point `U+FEFF`) helps the decoder determine the byte order and the transformation format or UTF. The Unicode byte order mark (BOM) is serialized as follows (in hexadecimal): - -- Big endian byte order: `FE FF` - -- Little endian byte order: `FF FE` - - You can instantiate a object whose is a valid BOM in the following ways: - -- By retrieving the object returned by the or property. - -- By calling the parameterless constructor to instantiate a object. - -- By supplying `true` as the value of the `byteOrderMark` argument to the or constructors. - - We recommended that you use the BOM, since it provides nearly certain identification of an encoding for files that otherwise have lost a reference to their encoding, such as untagged or improperly tagged web data or random text files stored when a business did not have international concerns. Often user problems might be avoided if data is consistently and properly tagged. - - For standards that provide an encoding type, a BOM is somewhat redundant. However, it can be used to help a server send the correct encoding header. Alternatively, it can be used as a fallback in case the encoding is otherwise lost. - - There are some disadvantages to using a BOM. For example, knowing how to limit the database fields that use a BOM can be difficult. Concatenation of files can be a problem also, for example, when files are merged in such a way that an unnecessary character can end up in the middle of data. In spite of the few disadvantages, however, the use of a BOM is highly recommended. - + object can provide a preamble, which is a byte span that can be prepended to the sequence of bytes resulting from the encoding process. Prefacing a sequence of encoded bytes with a byte order mark (code point `U+FEFF`) helps the decoder determine the byte order and the transformation format or UTF. The Unicode byte order mark (BOM) is serialized as follows (in hexadecimal): + +- Big endian byte order: `FE FF` + +- Little endian byte order: `FF FE` + + You can instantiate a object whose is a valid BOM in the following ways: + +- By retrieving the object returned by the or property. + +- By calling the parameterless constructor to instantiate a object. + +- By supplying `true` as the value of the `byteOrderMark` argument to the or constructors. + + We recommended that you use the BOM, since it provides nearly certain identification of an encoding for files that otherwise have lost a reference to their encoding, such as untagged or improperly tagged web data or random text files stored when a business did not have international concerns. Often user problems might be avoided if data is consistently and properly tagged. + + For standards that provide an encoding type, a BOM is somewhat redundant. However, it can be used to help a server send the correct encoding header. Alternatively, it can be used as a fallback in case the encoding is otherwise lost. + + There are some disadvantages to using a BOM. For example, knowing how to limit the database fields that use a BOM can be difficult. Concatenation of files can be a problem also, for example, when files are merged in such a way that an unnecessary character can end up in the middle of data. In spite of the few disadvantages, however, the use of a BOM is highly recommended. + > [!IMPORTANT] -> To ensure that the encoded bytes are decoded properly, you should prefix the beginning of a stream of encoded bytes with a preamble. Note that the method does not prepend a BOM to a sequence of encoded bytes; supplying a BOM at the beginning of an appropriate byte stream is the developer's responsibility. - +> To ensure that the encoded bytes are decoded properly, you should prefix the beginning of a stream of encoded bytes with a preamble. Note that the method does not prepend a BOM to a sequence of encoded bytes; supplying a BOM at the beginning of an appropriate byte stream is the developer's responsibility. + ]]> diff --git a/xml/System.Threading.Tasks/Task.xml b/xml/System.Threading.Tasks/Task.xml index 08f63d3780d..383c9d02db6 100644 --- a/xml/System.Threading.Tasks/Task.xml +++ b/xml/System.Threading.Tasks/Task.xml @@ -3039,7 +3039,7 @@ Task t Status: RanToCompletion, Result: 42 System.Void - + A Boolean value that indicates whether this method is being called due to a call to . diff --git a/xml/System.Threading.Tasks/TaskCanceledException.xml b/xml/System.Threading.Tasks/TaskCanceledException.xml index 5ef88ccc9c6..81ad7df2c1d 100644 --- a/xml/System.Threading.Tasks/TaskCanceledException.xml +++ b/xml/System.Threading.Tasks/TaskCanceledException.xml @@ -295,8 +295,8 @@ - - + + The object that holds the serialized object data. diff --git a/xml/System.Threading.Tasks/TaskSchedulerException.xml b/xml/System.Threading.Tasks/TaskSchedulerException.xml index 2e948cb67d1..ef9cc9afbf2 100644 --- a/xml/System.Threading.Tasks/TaskSchedulerException.xml +++ b/xml/System.Threading.Tasks/TaskSchedulerException.xml @@ -119,18 +119,18 @@ Initializes a new instance of the class with a system-supplied message that describes the error. - property of the new instance to a system-supplied message that describes the error, such as "DefaultMessageDisplayedByParameterlessCtorWriterMustSupply" This message takes into account the current system culture. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||`null`.| -||The localized error message string.| - + property of the new instance to a system-supplied message that describes the error, such as "DefaultMessageDisplayedByParameterlessCtorWriterMustSupply" This message takes into account the current system culture. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||`null`.| +||The localized error message string.| + ]]> @@ -227,16 +227,16 @@ The message that describes the exception. The caller of this constructor is required to ensure that this string has been localized for the current system culture. Initializes a new instance of the class with a specified message that describes the error. - . - -|Property|Value| -|--------------|-----------| -||`null`.| -||The error message string specified in `message`.| - + . + +|Property|Value| +|--------------|-----------| +||`null`.| +||The error message string specified in `message`.| + ]]> @@ -291,19 +291,19 @@ - - + + The object that holds the serialized object data. The contextual information about the source or destination. Initializes a new instance of the class with serialized data. - XML and SOAP Serialization @@ -353,18 +353,18 @@ The exception that is the cause of the current exception. If the parameter is not , the current exception is raised in a block that handles the inner exception. Initializes a new instance of the class with a specified error message and a reference to the inner exception that is the cause of this exception. - property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||`null`.| -||The error message string specified in `message`.| - + property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||`null`.| +||The error message string specified in `message`.| + ]]> diff --git a/xml/System.Threading/AbandonedMutexException.xml b/xml/System.Threading/AbandonedMutexException.xml index 8b6d67e3a83..0182d14f83c 100644 --- a/xml/System.Threading/AbandonedMutexException.xml +++ b/xml/System.Threading/AbandonedMutexException.xml @@ -69,27 +69,27 @@ The exception that is thrown when one thread acquires a object that another thread has abandoned by exiting without releasing it. - class. - - The next thread to request ownership of the mutex can handle this exception and proceed, provided that the integrity of the data structures can be verified. - - - -## Examples - The following code example executes a thread that abandons five mutexes, demonstrating their effects on the , , and methods. The value of the property is displayed for the call. - + class. + + The next thread to request ownership of the mutex can handle this exception and proceed, provided that the integrity of the data structures can be verified. + + + +## Examples + The following code example executes a thread that abandons five mutexes, demonstrating their effects on the , , and methods. The value of the property is displayed for the call. + > [!NOTE] -> The call to the method is interrupted by one of the abandoned mutexes. The other abandoned mutex could still cause an to be thrown by subsequent wait methods. - +> The call to the method is interrupted by one of the abandoned mutexes. The other abandoned mutex could still cause an to be thrown by subsequent wait methods. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.AbandonedMutexException/CPP/koax.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/AbandonedMutexException/Overview/koax.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.AbandonedMutexException/VB/koax.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.AbandonedMutexException/VB/koax.vb" id="Snippet1"::: + ]]> @@ -142,20 +142,20 @@ Initializes a new instance of the class with default values. - property of the new instance to a system-supplied message that describes the error, such as "The wait completed due to an abandoned mutex." This message takes into account the current system culture. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||`null`.| -||The system-supplied error message string.| -||`null`.| -||-1 (minus one).| - + property of the new instance to a system-supplied message that describes the error, such as "The wait completed due to an abandoned mutex." This message takes into account the current system culture. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||`null`.| +||The system-supplied error message string.| +||`null`.| +||-1 (minus one).| + ]]> @@ -202,20 +202,20 @@ An error message that explains the reason for the exception. Initializes a new instance of the class with a specified error message. - initialized with this constructor. - -|Property|Value| -|--------------|-----------| -||`null`.| -||`message`.| -||`null`.| -||-1 (minus one).| - + initialized with this constructor. + +|Property|Value| +|--------------|-----------| +||`null`.| +||`message`.| +||`null`.| +||-1 (minus one).| + ]]> @@ -264,20 +264,20 @@ A object that represents the abandoned mutex. Initializes a new instance of the class with a specified index for the abandoned mutex, if applicable, and a object that represents the mutex. - property of the new instance to a system-supplied message that describes the error, such as "The wait completed due to an abandoned mutex." This message takes into account the current system culture. - - The following table shows the initial property values for an instance of initialized with this constructor. - -|Property|Value| -|--------------|-----------| -||`null`.| -||A system-supplied error message string.| -||`handle`.| -||`location`.| - + property of the new instance to a system-supplied message that describes the error, such as "The wait completed due to an abandoned mutex." This message takes into account the current system culture. + + The following table shows the initial property values for an instance of initialized with this constructor. + +|Property|Value| +|--------------|-----------| +||`null`.| +||A system-supplied error message string.| +||`handle`.| +||`location`.| + ]]> @@ -333,19 +333,19 @@ - - + + The object that holds the serialized object data about the exception being thrown. The object that contains contextual information about the source or destination. Initializes a new instance of the class with serialized data. - @@ -394,22 +394,22 @@ The exception that is the cause of the current exception. If the parameter is not , the current exception is raised in a block that handles the inner exception. Initializes a new instance of the class with a specified error message and inner exception. - property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. - - The following table shows the initial property values for an instance of initialized with this constructor. - -|Property|Value| -|--------------|-----------| -||`inner`.| -||`message`.| -||`null`.| -||-1 (minus one).| - + property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. + + The following table shows the initial property values for an instance of initialized with this constructor. + +|Property|Value| +|--------------|-----------| +||`inner`.| +||`message`.| +||`null`.| +||-1 (minus one).| + ]]> @@ -460,20 +460,20 @@ A object that represents the abandoned mutex. Initializes a new instance of the class with a specified error message, the index of the abandoned mutex, if applicable, and the abandoned mutex. - initialized with this constructor. - -|Property|Value| -|--------------|-----------| -||`null`.| -||`message`.| -||`handle`.| -||`location`.| - + initialized with this constructor. + +|Property|Value| +|--------------|-----------| +||`null`.| +||`message`.| +||`handle`.| +||`location`.| + ]]> @@ -526,22 +526,22 @@ A object that represents the abandoned mutex. Initializes a new instance of the class with a specified error message, the inner exception, the index for the abandoned mutex, if applicable, and a object that represents the mutex. - property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. - - The following table shows the initial property values for an instance of initialized with this constructor. - -|Property|Value| -|--------------|-----------| -||`inner`.| -||`message`.| -||`handle`.| -||`location`.| - + property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. + + The following table shows the initial property values for an instance of initialized with this constructor. + +|Property|Value| +|--------------|-----------| +||`inner`.| +||`message`.| +||`handle`.| +||`location`.| + ]]> @@ -588,11 +588,11 @@ Gets the abandoned mutex that caused the exception, if known. A object that represents the abandoned mutex, or if the abandoned mutex could not be identified. - method, the returned is the abandoned mutex with the lowest index in the array of objects that was passed to , or `null` if the abandoned mutex could not be identified. If the exception is thrown on a call to or , this property always returns `null`. - + method, the returned is the abandoned mutex with the lowest index in the array of objects that was passed to , or `null` if the abandoned mutex could not be identified. If the exception is thrown on a call to or , this property always returns `null`. + ]]> @@ -638,23 +638,23 @@ Gets the index of the abandoned mutex that caused the exception, if known. The index, in the array of wait handles passed to the method, of the object that represents the abandoned mutex, or -1 if the index of the abandoned mutex could not be determined. - method, this property returns the index of the abandoned mutex with the lowest index in the array of objects that was passed to , or -1 if the abandoned mutex could not be identified. If the exception is thrown on a call to or , this property always returns -1. - - - -## Examples - The following code example executes a thread that abandons five mutexes. The abandoned mutexes are used to demonstrate the effects on the , , and method calls. The value of the property is displayed for the call. - + method, this property returns the index of the abandoned mutex with the lowest index in the array of objects that was passed to , or -1 if the abandoned mutex could not be identified. If the exception is thrown on a call to or , this property always returns -1. + + + +## Examples + The following code example executes a thread that abandons five mutexes. The abandoned mutexes are used to demonstrate the effects on the , , and method calls. The value of the property is displayed for the call. + > [!NOTE] -> The call to is interrupted by one of the abandoned mutexes. The other abandoned mutex could still cause an to be thrown by subsequent wait methods. - +> The call to is interrupted by one of the abandoned mutexes. The other abandoned mutex could still cause an to be thrown by subsequent wait methods. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.AbandonedMutexException/CPP/koax.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/AbandonedMutexException/Overview/koax.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.AbandonedMutexException/VB/koax.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.AbandonedMutexException/VB/koax.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.Threading/BarrierPostPhaseException.xml b/xml/System.Threading/BarrierPostPhaseException.xml index 4c8c3ba31b5..5d8e06e4014 100644 --- a/xml/System.Threading/BarrierPostPhaseException.xml +++ b/xml/System.Threading/BarrierPostPhaseException.xml @@ -115,18 +115,18 @@ Initializes a new instance of the class with a system-supplied message that describes the error. - property of the new instance to a system-supplied message that describes the error, such as "The postPhaseAction failed with an exception." This message takes into account the current system culture. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||`null`.| -||The localized error message string.| - + property of the new instance to a system-supplied message that describes the error, such as "The postPhaseAction failed with an exception." This message takes into account the current system culture. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||`null`.| +||The localized error message string.| + ]]> Handling and Throwing Exceptions @@ -229,16 +229,16 @@ The message that describes the exception. The caller of this constructor is required to ensure that this string has been localized for the current system culture. Initializes a new instance of the class with a specified message that describes the error. - . - -|Property|Value| -|--------------|-----------| -||`null`.| -||The error message string specified in `message`.| - + . + +|Property|Value| +|--------------|-----------| +||`null`.| +||The error message string specified in `message`.| + ]]> Handling and Throwing Exceptions @@ -298,19 +298,19 @@ - - + + The object that holds the serialized object data. The contextual information about the source or destination. Initializes a new instance of the class with serialized data. - XML and SOAP Serialization @@ -357,18 +357,18 @@ The exception that is the cause of the current exception. If the parameter is not , the current exception is raised in a block that handles the inner exception. Initializes a new instance of the class with a specified error message and a reference to the inner exception that is the cause of this exception. - property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||`null`.| -||The error message string specified in `message`.| - + property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||`null`.| +||The error message string specified in `message`.| + ]]> Handling and Throwing Exceptions diff --git a/xml/System.Threading/EventWaitHandle.xml b/xml/System.Threading/EventWaitHandle.xml index d6a4b529834..b654e14fff1 100644 --- a/xml/System.Threading/EventWaitHandle.xml +++ b/xml/System.Threading/EventWaitHandle.xml @@ -58,37 +58,37 @@ Represents a thread synchronization event. - class allows threads to communicate with each other by signaling. Typically, one or more threads block on an until an unblocked thread calls the method, releasing one or more of the blocked threads. A thread can signal an and then block on it, by calling the `static` (`Shared` in Visual Basic) method. - +The class allows threads to communicate with each other by signaling. Typically, one or more threads block on an until an unblocked thread calls the method, releasing one or more of the blocked threads. A thread can signal an and then block on it, by calling the `static` (`Shared` in Visual Basic) method. + > [!NOTE] -> The class provides access to named system synchronization events. - - The behavior of an that has been signaled depends on its reset mode. An created with the flag resets automatically when signaled, after releasing a single waiting thread. An created with the flag remains signaled until its method is called. - - Automatic reset events provide exclusive access to a resource. If an automatic reset event is signaled when no threads are waiting, it remains signaled until a thread attempts to wait on it. The event releases the thread and immediately resets, blocking subsequent threads. - - Manual reset events are like gates. When the event is not signaled, threads that wait on it will block. When the event is signaled, all waiting threads are released, and the event remains signaled (that is, subsequent waits do not block) until its method is called. Manual reset events are useful when one thread must complete an activity before other threads can proceed. - - objects can be used with the `static`(`Shared` in Visual Basic) and methods. - +> The class provides access to named system synchronization events. + + The behavior of an that has been signaled depends on its reset mode. An created with the flag resets automatically when signaled, after releasing a single waiting thread. An created with the flag remains signaled until its method is called. + + Automatic reset events provide exclusive access to a resource. If an automatic reset event is signaled when no threads are waiting, it remains signaled until a thread attempts to wait on it. The event releases the thread and immediately resets, blocking subsequent threads. + + Manual reset events are like gates. When the event is not signaled, threads that wait on it will block. When the event is signaled, all waiting threads are released, and the event remains signaled (that is, subsequent waits do not block) until its method is called. Manual reset events are useful when one thread must complete an activity before other threads can proceed. + + objects can be used with the `static`(`Shared` in Visual Basic) and methods. + For more information, see the [Thread interaction, or signaling](/dotnet/standard/threading/overview-of-synchronization-primitives#thread-interaction-or-signaling) section of the [Overview of synchronization primitives](/dotnet/standard/threading/overview-of-synchronization-primitives) article. - + > [!CAUTION] > By default, a named event is not restricted to the user that created it. Other users may be able to open and use the event, including interfering with the event by setting or resetting it inappropriately. To restrict access to specific users, you can use a constructor overload or and pass in an when creating the named event. Avoid using named events without access restrictions on systems that might have untrusted users running code. - -## Examples - The following code example uses the method overload to allow the main thread to signal a blocked thread and then wait until the thread finishes a task. - - The example starts five threads and allows them to block on an created with the flag, then releases one thread each time the user presses the Enter key. The example then queues another five threads and releases them all using an created with the flag. - + +## Examples + The following code example uses the method overload to allow the main thread to signal a blocked thread and then wait until the thread finishes a task. + + The example starts five threads and allows them to block on an created with the flag, then releases one thread each time the user presses the Enter key. The example then queues another five threads and releases them all using an created with the flag. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.WaitHandle.SignalAndWait/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/EventResetMode/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.WaitHandle.SignalAndWait/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.WaitHandle.SignalAndWait/VB/source.vb" id="Snippet1"::: + ]]> This type is thread safe. @@ -158,20 +158,20 @@ The class allows threads to communicate One of the values that determines whether the event resets automatically or manually. Initializes a new instance of the class, specifying whether the wait handle is initially signaled, and whether it resets automatically or manually. - flag is specified for `mode`, threads that wait on the event will not block. If the initial state is signaled, and `mode` is , the first thread that waits on the event will be released immediately, after which the event will reset, and subsequent threads will block. - -## Examples - The following code example uses the method overload to allow the main thread to signal a blocked thread and then wait until the thread finishes a task. - - The example starts five threads and allows them to block on an created with the flag, then releases one thread each time the user presses the Enter key. The example then queues another five threads and releases them all using an created with the flag. - + +## Examples + The following code example uses the method overload to allow the main thread to signal a blocked thread and then wait until the thread finishes a task. + + The example starts five threads and allows them to block on an created with the flag, then releases one thread each time the user presses the Enter key. The example then queues another five threads and releases them all using an created with the flag. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.WaitHandle.SignalAndWait/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/EventResetMode/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.WaitHandle.SignalAndWait/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.WaitHandle.SignalAndWait/VB/source.vb" id="Snippet1"::: + ]]> The enum value was out of legal range. @@ -233,23 +233,23 @@ The class allows threads to communicate The name, if the synchronization object is to be shared with other processes; otherwise, or an empty string. The name is case-sensitive. The backslash character (\\) is reserved and may only be used to specify a namespace. For more information on namespaces, see the remarks section. There may be further restrictions on the name depending on the operating system. For example, on Unix-based operating systems, the name after excluding the namespace must be a valid file name. Initializes a new instance of the class, specifying whether the wait handle is initially signaled if created as a result of this call, whether it resets automatically or manually, and the name of a system synchronization event. - [!CAUTION] > By default, a named event is not restricted to the user that created it. Other users may be able to open and use the event, including interfering with the event by setting or resetting it inappropriately. To restrict access to specific users, you can use a constructor overload or and pass in an when creating the named event. Avoid using named events without access restrictions on systems that might have untrusted users running code. - + > [!IMPORTANT] -> When using this constructor for named system events, specify `false` for `initialState`. This constructor provides no way to determine whether a named system event was created, so you cannot make any assumptions about the state of the named event. To determine whether a named event was created, use the constructor or the constructor. - - If the initial state of the event is nonsignaled, threads that wait on the event will block. If the initial state is signaled, and the flag is specified for `mode`, threads that wait on the event will not block. If the initial state is signaled, and `mode` is , the first thread that waits on the event will be released immediately, after which the event will reset, and subsequent threads will block. - +> When using this constructor for named system events, specify `false` for `initialState`. This constructor provides no way to determine whether a named system event was created, so you cannot make any assumptions about the state of the named event. To determine whether a named event was created, use the constructor or the constructor. + + If the initial state of the event is nonsignaled, threads that wait on the event will block. If the initial state is signaled, and the flag is specified for `mode`, threads that wait on the event will not block. If the initial state is signaled, and `mode` is , the first thread that waits on the event will be released immediately, after which the event will reset, and subsequent threads will block. + ]]> @@ -328,20 +328,20 @@ There was some other error. The `HResult` property may provide more information. When this method returns, contains if a local event was created (that is, if is or an empty string) or if the specified named system event was created; if the specified named system event already existed. This parameter is passed uninitialized. Initializes a new instance of the class, specifying whether the wait handle is initially signaled if created as a result of this call, whether it resets automatically or manually, the name of a system synchronization event, and a Boolean variable whose value after the call indicates whether the named system event was created. - flag is specified for `mode`, threads that wait on the event will not block. If the initial state is signaled, and `mode` is , the first thread that waits on the event will be released immediately, after which the event will reset, and subsequent threads will block. - + If a system event with the name specified for the `name` parameter already exists, the `initialState` parameter is ignored. After calling this constructor, use the value in the variable specified for the `ref` parameter (`ByRef` parameter in Visual Basic)`createdNew` to determine whether the named system event already existed or was created. + + If the initial state of the event is nonsignaled, threads that wait on the event will block. If the initial state is signaled, and the flag is specified for `mode`, threads that wait on the event will not block. If the initial state is signaled, and `mode` is , the first thread that waits on the event will be released immediately, after which the event will reset, and subsequent threads will block. + > [!CAUTION] > By default, a named event is not restricted to the user that created it. Other users may be able to open and use the event, including interfering with the event by setting or resetting it inappropriately. To restrict access to specific users, you can use a constructor overload or and pass in an when creating the named event. Avoid using named events without access restrictions on systems that might have untrusted users running code. - + ]]> @@ -389,11 +389,11 @@ There was some other error. The `HResult` property may provide more information. - - - - - + + + + + @@ -404,42 +404,42 @@ There was some other error. The `HResult` property may provide more information. An object that represents the access control security to be applied to the named system event. Initializes a new instance of the class, specifying whether the wait handle is initially signaled if created as a result of this call, whether it resets automatically or manually, the name of a system synchronization event, a Boolean variable whose value after the call indicates whether the named system event was created, and the access control security to be applied to the named event if it is created. - object that represents a system event. You can create multiple objects that represent the same system event. - - If the system event does not exist, it is created with the specified access control security. If the event exists, the specified access control security is ignored. - + object that represents a system event. You can create multiple objects that represent the same system event. + + If the system event does not exist, it is created with the specified access control security. If the event exists, the specified access control security is ignored. + > [!NOTE] -> The caller has full control over the newly created object even if `eventSecurity` denies or fails to grant some access rights to the current user. However, if the current user attempts to get another object to represent the same named event, using either a constructor or the method, Windows access control security is applied. - +> The caller has full control over the newly created object even if `eventSecurity` denies or fails to grant some access rights to the current user. However, if the current user attempts to get another object to represent the same named event, using either a constructor or the method, Windows access control security is applied. + The `name` may be prefixed with `Global\` or `Local\` to specify a namespace. When the `Global` namespace is specified, the synchronization object may be shared with any processes on the system. When the `Local` namespace is specified, which is also the default when no namespace is specified, the synchronization object may be shared with processes in the same session. On Windows, a session is a login session, and services typically run in a different non-interactive session. On Unix-like operating systems, each shell has its own session. Session-local synchronization objects may be appropriate for synchronizing between processes with a parent/child relationship where they all run in the same session. For more information about synchronization object names on Windows, see [Object Names](/windows/win32/sync/object-names). If a `name` is provided and a synchronization object of the requested type already exists in the namespace, the existing synchronization object is opened. If a synchronization object of a different type already exists in the namespace, a `WaitHandleCannotBeOpenedException` is thrown. Otherwise, a new synchronization object is created. - If a system event with the name specified for the `name` parameter already exists, the `initialState` parameter is ignored. After calling this constructor, use the value in the variable specified for the `ref` parameter (`ByRef` parameter in Visual Basic) `createdNew` to determine whether the named system event already existed or was created. - + If a system event with the name specified for the `name` parameter already exists, the `initialState` parameter is ignored. After calling this constructor, use the value in the variable specified for the `ref` parameter (`ByRef` parameter in Visual Basic) `createdNew` to determine whether the named system event already existed or was created. + If the initial state of the event is nonsignaled, threads that wait on the event will block. If the initial state is signaled, and the flag is specified for `mode`, threads that wait on the event will not block. If the initial state is signaled, and `mode` is , the first thread that waits on the event will be released immediately, after which the event will reset, and subsequent threads will block. - + > [!CAUTION] > By default, a named event is not restricted to the user that created it. Other users may be able to open and use the event, including interfering with the event by setting or resetting it inappropriately. To restrict access to specific users, you can pass in an when creating the named event. Avoid using named events without access restrictions on systems that might have untrusted users running code. - -## Examples - The following code example demonstrates the cross-process behavior of a named system event with access control security. The example uses the method overload to test for the existence of a named event. - - If the event does not exist, it is created with initial ownership and access control security that denies the current user the right to use the event, but grants the right to read and change permissions on the event. - - If you run the compiled example from two command windows, the second copy will throw an access violation exception on the call to . The exception is caught, and the example uses the method overload to wait on the event with the rights needed to read and change the permissions. - - After the permissions are changed, the event is opened with the rights required to wait on it and signal it. If you run the compiled example from a third command window, the example runs using the new permissions. - + +## Examples + The following code example demonstrates the cross-process behavior of a named system event with access control security. The example uses the method overload to test for the existence of a named event. + + If the event does not exist, it is created with initial ownership and access control security that denies the current user the right to use the event, but grants the right to read and change permissions on the event. + + If you run the compiled example from two command windows, the second copy will throw an access violation exception on the call to . The exception is caught, and the example uses the method overload to wait on the event with the rights needed to read and change the permissions. + + After the permissions are changed, the event is opened with the rights required to wait on it and signal it. If you run the compiled example from a third command window, the example runs using the new permissions. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.EventWaitHandle.ctor named 5/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/EventWaitHandle/.ctor/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.EventWaitHandle.ctor named 5/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.EventWaitHandle.ctor named 5/VB/source.vb" id="Snippet1"::: + ]]> @@ -494,33 +494,33 @@ There was some other error. The `HResult` property may provide more information. Gets an object that represents the access control security for the named system event represented by the current object. An object that represents the access control security for the named system event. - method uses the following combination of flags (combined using the bitwise OR operation) to search for permissions: , , and . - + method uses the following combination of flags (combined using the bitwise OR operation) to search for permissions: , , and . + The user must have rights to call this method, and the event must have been opened with the flag. - -## Examples - The following code example demonstrates the cross-process behavior of a named system event with access control security. The example uses the method overload to test for the existence of a named event. - - If the event does not exist, it is created with initial ownership and access control security that denies the current user the right to use the event, but grants the right to read and change permissions on the event. - - If you run the compiled example from two command windows, the second copy will throw an access violation exception on the call to . The exception is caught, and the example uses the method overload to wait on the event with the rights needed to read and change the permissions. - - After the permissions have been read, using the method, and changed, the event is opened with the rights required to wait on it and signal it. If you run the compiled example from a third command window, the example runs using the new permissions. - + +## Examples + The following code example demonstrates the cross-process behavior of a named system event with access control security. The example uses the method overload to test for the existence of a named event. + + If the event does not exist, it is created with initial ownership and access control security that denies the current user the right to use the event, but grants the right to read and change permissions on the event. + + If you run the compiled example from two command windows, the second copy will throw an access violation exception on the call to . The exception is caught, and the example uses the method overload to wait on the event with the rights needed to read and change the permissions. + + After the permissions have been read, using the method, and changed, the event is opened with the rights required to wait on it and signal it. If you run the compiled example from a third command window, the example runs using the new permissions. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.EventWaitHandle.ctor named 5/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/EventWaitHandle/.ctor/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.EventWaitHandle.ctor named 5/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.EventWaitHandle.ctor named 5/VB/source.vb" id="Snippet1"::: + ]]> - The current object represents a named system event, and the user does not have . - - -or- - + The current object represents a named system event, and the user does not have . + + -or- + The current object represents a named system event, and was not opened with . The method was previously called on this . Overview of synchronization primitives @@ -590,21 +590,21 @@ There was some other error. The `HResult` property may provide more information. Opens the specified named synchronization event, if it already exists. An object that represents the named system event. - method tries to open the specified named system event. To create the system event when it does not already exist, use one of the constructors that has a `name` parameter. - - Multiple calls to this method that use the same value for `name` do not necessarily return the same object, even though the objects that are returned represent the same named system event. - + + Multiple calls to this method that use the same value for `name` do not necessarily return the same object, even though the objects that are returned represent the same named system event. + In .NET Framework, this method overload is equivalent to calling the [System.Threading.EventWaitHandle.OpenExisting(System.String,System.Security.AccessControl.EventWaitHandleRights)](/dotnet/api/system.threading.eventwaithandle.openexisting?view=netframework-4.8&preserve-view=true#System_Threading_EventWaitHandle_OpenExisting_System_String_System_Security_AccessControl_EventWaitHandleRights_) method overload and specifying and rights, combined by using the bitwise `OR` operation. - + Specifying the flag allows a thread to wait on the named system event, and specifying the flag allows a thread to call the and methods. - + ]]> A synchronization object with the provided cannot be opened. It may not exist, or a synchronization object of a different type might have the same name. In some cases, this exception may be thrown for invalid names. @@ -657,8 +657,8 @@ There was some other error. The `HResult` property may provide more information. System.Threading.EventWaitHandle - - + + The name of the synchronization object to be opened and shared with other processes. The name is case-sensitive. The backslash character (\\) is reserved and may only be used to specify a namespace. For more information on namespaces, see the remarks section. There may be further restrictions on the name depending on the operating system. For example, on Unix-based operating systems, the name after excluding the namespace must be a valid file name. @@ -666,32 +666,32 @@ There was some other error. The `HResult` property may provide more information. Opens the specified named synchronization event, if it already exists, with the desired security access. An object that represents the named system event. - flag to allow threads to wait on the event, and the flag to allow threads to call the and methods. - - The method tries to open an existing named system event. To create the system event when it does not already exist, use one of the constructors that has a `name` parameter. - + The `rights` parameter must include the flag to allow threads to wait on the event, and the flag to allow threads to call the and methods. + + The method tries to open an existing named system event. To create the system event when it does not already exist, use one of the constructors that has a `name` parameter. + Multiple calls to this method that use the same value for `name` do not necessarily return the same object, even though the objects that are returned represent the same named system event. - -## Examples - The following code example demonstrates the cross-process behavior of a named system event with access control security. The example uses the method overload to test for the existence of a named event. - - If the event does not exist, it is created with initial ownership and access control security that denies the current user the right to use the event, but grants the right to read and change permissions on the event. - - If you run the compiled example from two command windows, the second copy will throw an access violation exception on the call to . The exception is caught, and the example uses the method overload to wait on the event with the rights needed to read and change the permissions. - - After the permissions are changed, the event is opened with the rights required to wait on it and signal it. If you run the compiled example from a third command window, the example runs using the new permissions. - + +## Examples + The following code example demonstrates the cross-process behavior of a named system event with access control security. The example uses the method overload to test for the existence of a named event. + + If the event does not exist, it is created with initial ownership and access control security that denies the current user the right to use the event, but grants the right to read and change permissions on the event. + + If you run the compiled example from two command windows, the second copy will throw an access violation exception on the call to . The exception is caught, and the example uses the method overload to wait on the event with the rights needed to read and change the permissions. + + After the permissions are changed, the event is opened with the rights required to wait on it and signal it. If you run the compiled example from a third command window, the example runs using the new permissions. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.EventWaitHandle.ctor named 5/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/EventWaitHandle/.ctor/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.EventWaitHandle.ctor named 5/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.EventWaitHandle.ctor named 5/VB/source.vb" id="Snippet1"::: + ]]> @@ -813,25 +813,25 @@ There was some other error. The `HResult` property may provide more information. if the operation succeeds; otherwise, . - with (including ), the method releases a single thread. If there are no waiting threads, the wait handle remains signaled until a thread attempts to wait on it, or until its method is called. - + with (including ), the method releases a single thread. If there are no waiting threads, the wait handle remains signaled until a thread attempts to wait on it, or until its method is called. + > [!IMPORTANT] -> There is no guarantee that every call to the method will release a thread from an whose reset mode is . If two calls are too close together, so that the second call occurs before a thread has been released, only one thread is released. It is as if the second call did not happen. Also, if is called when there are no threads waiting and the is already signaled, the call has no effect. - +> There is no guarantee that every call to the method will release a thread from an whose reset mode is . If two calls are too close together, so that the second call occurs before a thread has been released, only one thread is released. It is as if the second call did not happen. Also, if is called when there are no threads waiting and the is already signaled, the call has no effect. + For an with (including ), calling the method leaves the wait handle in a signaled state until its method is called. - -## Examples - The following code example uses the method overload to allow the main thread to signal a blocked thread and then wait until the thread finishes a task. - - The example starts five threads and allows them to block on an created with the flag, then releases one thread each time the user presses the Enter key. The example then queues another five threads and releases them all using an created with the flag. - + +## Examples + The following code example uses the method overload to allow the main thread to signal a blocked thread and then wait until the thread finishes a task. + + The example starts five threads and allows them to block on an created with the flag, then releases one thread each time the user presses the Enter key. The example then queues another five threads and releases them all using an created with the flag. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.WaitHandle.SignalAndWait/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/EventResetMode/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.WaitHandle.SignalAndWait/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.WaitHandle.SignalAndWait/VB/source.vb" id="Snippet1"::: + ]]> The method was previously called on this . @@ -867,39 +867,39 @@ There was some other error. The `HResult` property may provide more information. System.Void - + An object that represents the access control security to be applied to the named system event. Sets the access control security for a named system event. - rights to call this method, and the event must have been opened with the flag. - -## Examples - The following code example demonstrates the cross-process behavior of a named system event with access control security. The example uses the method overload to test for the existence of a named event. - - If the event does not exist, it is created with initial ownership and access control security that denies the current user the right to use the event, but grants the right to read and change permissions on the event. - - If you run the compiled example from two command windows, the second copy will throw an access violation exception on the call to . The exception is caught, and the example uses the method overload to wait on the event with the rights needed to read and change the permissions. - - After the permissions are changed, using the method, the event is opened with the rights required to wait on it and signal it. If you run the compiled example from a third command window, the example runs using the new permissions. - + +## Examples + The following code example demonstrates the cross-process behavior of a named system event with access control security. The example uses the method overload to test for the existence of a named event. + + If the event does not exist, it is created with initial ownership and access control security that denies the current user the right to use the event, but grants the right to read and change permissions on the event. + + If you run the compiled example from two command windows, the second copy will throw an access violation exception on the call to . The exception is caught, and the example uses the method overload to wait on the event with the rights needed to read and change the permissions. + + After the permissions are changed, using the method, the event is opened with the rights required to wait on it and signal it. If you run the compiled example from a third command window, the example runs using the new permissions. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.EventWaitHandle.ctor named 5/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/EventWaitHandle/.ctor/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.EventWaitHandle.ctor named 5/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.EventWaitHandle.ctor named 5/VB/source.vb" id="Snippet1"::: + ]]> is . - The user does not have . - - -or- - + The user does not have . + + -or- + The event was not opened with . The current object does not represent a named system event. The method was previously called on this . @@ -984,21 +984,21 @@ There was some other error. The `HResult` property may provide more information. if the named synchronization event was opened successfully; otherwise, . In some cases, may be returned for invalid names. - constructors that has a `name` parameter. - - If you are uncertain whether a named synchronization event exists, use this method overload instead of the method overload, which throws an exception if the synchronization event does not exist. - - This method overload is equivalent to calling the method overload and specifying and rights, combined by using the bitwise OR operation. Specifying the flag allows a thread to wait on the named system event, and specifying the flag allows a thread to call the and methods. - - Multiple calls to this method that use the same value for `name` do not necessarily return the same object, even though the objects that are returned represent the same named system event. - + To create the system event when it does not already exist, use one of the constructors that has a `name` parameter. + + If you are uncertain whether a named synchronization event exists, use this method overload instead of the method overload, which throws an exception if the synchronization event does not exist. + + This method overload is equivalent to calling the method overload and specifying and rights, combined by using the bitwise OR operation. Specifying the flag allows a thread to wait on the named system event, and specifying the flag allows a thread to call the and methods. + + Multiple calls to this method that use the same value for `name` do not necessarily return the same object, even though the objects that are returned represent the same named system event. + ]]> @@ -1047,9 +1047,9 @@ There was some other error. The `HResult` property may provide more information. System.Boolean - - - + + + The name of the synchronization object to be opened and shared with other processes. The name is case-sensitive. The backslash character (\\) is reserved and may only be used to specify a namespace. For more information on namespaces, see the remarks section. There may be further restrictions on the name depending on the operating system. For example, on Unix-based operating systems, the name after excluding the namespace must be a valid file name. @@ -1059,21 +1059,21 @@ There was some other error. The `HResult` property may provide more information. if the named synchronization event was opened successfully; otherwise, . In some cases, may be returned for invalid names. - constructors that has a `name` parameter. - - If you are uncertain whether a named synchronization event exists, use this method overload instead of the method overload, which throws an exception if the synchronization event does not exist. - - The `rights` parameter must include the flag to allow threads to wait on the event, and the flag to allow threads to call the and methods. - - Multiple calls to this method that use the same value for `name` do not necessarily return the same object, even though the objects that are returned represent the same named system event. - + To create the system event when it does not already exist, use one of the constructors that has a `name` parameter. + + If you are uncertain whether a named synchronization event exists, use this method overload instead of the method overload, which throws an exception if the synchronization event does not exist. + + The `rights` parameter must include the flag to allow threads to wait on the event, and the flag to allow threads to call the and methods. + + Multiple calls to this method that use the same value for `name` do not necessarily return the same object, even though the objects that are returned represent the same named system event. + ]]> diff --git a/xml/System.Threading/ExecutionContext.xml b/xml/System.Threading/ExecutionContext.xml index d3a3f3e420f..afc935467c1 100644 --- a/xml/System.Threading/ExecutionContext.xml +++ b/xml/System.Threading/ExecutionContext.xml @@ -74,21 +74,21 @@ Manages the execution context for the current thread. This class cannot be inherited. - class provides a single container for all information relevant to a logical thread of execution. In .NET Framework, this includes security context, call context, and synchronization context. In .NET Core, the security context and call context are not supported, however, the impersonation context and culture would typically flow with the execution context. Also in .NET Core, the synchronization context does not flow with the execution context, whereas in .NET Framework it may in some cases. For more information, see [ExecutionContext vs SynchronizationContext](https://devblogs.microsoft.com/pfxteam/executioncontext-vs-synchronizationcontext/). - - The class provides the functionality for user code to capture and transfer this context across user-defined asynchronous points. The common language runtime ensures that the is consistently transferred across runtime-defined asynchronous points within the managed process. - + + The class provides the functionality for user code to capture and transfer this context across user-defined asynchronous points. The common language runtime ensures that the is consistently transferred across runtime-defined asynchronous points within the managed process. + - The following is applicable to .NET Framework only. - - - An execution context is the managed equivalent of a COM apartment. Within an application domain, the entire execution context must be transferred whenever a thread is transferred. This situation occurs during transfers made by the method, most thread pool operations, and Windows Forms thread marshaling through the Windows message pump. It does not occur in unsafe thread pool operations (such as the method), which do not transfer the compressed stack. Wherever the compressed stack flows, the managed principal, synchronization, locale, and user context also flow. The class provides the and methods to get the execution context and the method to set the execution context for the current thread. - - An that is associated with a thread cannot be set on another thread. Attempting to do so will result in an exception being thrown. To propagate the from one thread to another, make a copy of the . - - Internally, the stores all data that is associated with the . This allows the data to be propagated when the is copied and transferred. - + + An execution context is the managed equivalent of a COM apartment. Within an application domain, the entire execution context must be transferred whenever a thread is transferred. This situation occurs during transfers made by the method, most thread pool operations, and Windows Forms thread marshaling through the Windows message pump. It does not occur in unsafe thread pool operations (such as the method), which do not transfer the compressed stack. Wherever the compressed stack flows, the managed principal, synchronization, locale, and user context also flow. The class provides the and methods to get the execution context and the method to set the execution context for the current thread. + + An that is associated with a thread cannot be set on another thread. Attempting to do so will result in an exception being thrown. To propagate the from one thread to another, make a copy of the . + + Internally, the stores all data that is associated with the . This allows the data to be propagated when the is copied and transferred. + ]]> @@ -143,11 +143,11 @@ Captures the execution context from the current thread. An object representing the execution context for the current thread. - method. - + method. + ]]> @@ -196,11 +196,11 @@ Creates a copy of the current execution context. An object representing the current execution context. - This context cannot be copied because it is used. Only newly captured contexts can be copied. @@ -251,16 +251,16 @@ Releases all 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). + > [!NOTE] -> Always call `Dispose` 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 `Dispose` 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. + ]]> Cleaning Up Unmanaged Resources @@ -317,21 +317,21 @@ System.Void - - + + The object to be populated with serialization information. The structure representing the destination context of the serialization. Sets the specified object with the logical context information needed to recreate an instance of the current execution context. - sets a with the logical call context information. During deserialization, the execution context object is reconstituted from the transmitted over the stream. - - For more information, see . - + sets a with the logical call context information. During deserialization, the execution context object is reconstituted from the transmitted over the stream. + + For more information, see . + ]]> @@ -379,11 +379,11 @@ if the flow is suppressed; otherwise, . - method is used by infrastructure components to determine whether to transfer the during asynchronous operations. - + method is used by infrastructure components to determine whether to transfer the during asynchronous operations. + ]]> @@ -475,13 +475,13 @@ To revert to the current execution context; capture it before calling Restore, a Restores the flow of the execution context across asynchronous threads. - reverses the effect of a prior method call. - - This method is called by the method of the structure returned by the method. You should use the method to restore the flow of the execution context, not the method. - + reverses the effect of a prior method call. + + This method is called by the method of the structure returned by the method. You should use the method to restore the flow of the execution context, not the method. + ]]> The context flow cannot be restored because it is not being suppressed. @@ -546,22 +546,22 @@ To revert to the current execution context; capture it before calling Restore, a The object to pass to the callback method. Runs a method in a specified execution context on the current thread. - - is . - - -or- - - was not acquired through a capture operation. - - -or- - + is . + + -or- + + was not acquired through a capture operation. + + -or- + has already been used as the argument to a call. @@ -609,13 +609,13 @@ To revert to the current execution context; capture it before calling Restore, a Suppresses the flow of the execution context across asynchronous threads. An structure for restoring the flow. - on the current thread. - + on the current thread. + You must use the method on the returned structure to restore the flow of the . - + ]]> The context flow is already suppressed. diff --git a/xml/System.Threading/LockRecursionException.xml b/xml/System.Threading/LockRecursionException.xml index 6b329cc11bf..abd8e8dec61 100644 --- a/xml/System.Threading/LockRecursionException.xml +++ b/xml/System.Threading/LockRecursionException.xml @@ -68,25 +68,25 @@ The exception that is thrown when recursive entry into a lock is not compatible with the recursion policy for the lock. - is thrown for several reasons, including the following: - -- If a thread tries to enter an instance of recursively, but the instance does not support recursion. - -- If a thread tries to enter a instance in write mode or upgradeable mode when the thread initially entered the lock in read mode. This represents a potential deadlock and therefore is not allowed. - -- If allowing one more level of recursion would exceed the maximum value for the internal storage counter used to track recursions. This limit is so large that applications should never encounter it. - - - -## Examples - The following example shows two causes of when using the class. The program creates a by using the parameterless constructor, which disallows recursion. The program then starts a thread that enters the lock in read mode. The thread tries to enter the lock recursively in read mode, and catches the resulting exception. Finally, the thread tries to enter write mode, which would create a potential for deadlocks. The thread catches the resulting exception. - + is thrown for several reasons, including the following: + +- If a thread tries to enter an instance of recursively, but the instance does not support recursion. + +- If a thread tries to enter a instance in write mode or upgradeable mode when the thread initially entered the lock in read mode. This represents a potential deadlock and therefore is not allowed. + +- If allowing one more level of recursion would exceed the maximum value for the internal storage counter used to track recursions. This limit is so large that applications should never encounter it. + + + +## Examples + The following example shows two causes of when using the class. The program creates a by using the parameterless constructor, which disallows recursion. The program then starts a thread that enters the lock in read mode. The thread tries to enter the lock recursively in read mode, and catches the resulting exception. Finally, the thread tries to enter write mode, which would create a potential for deadlocks. The thread catches the resulting exception. + :::code language="csharp" source="~/snippets/csharp/System.Threading/LockRecursionException/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.LockRecursionException/vb/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.LockRecursionException/vb/source.vb" id="Snippet1"::: + ]]> @@ -141,18 +141,18 @@ Initializes a new instance of the class with a system-supplied message that describes the error. - property of the new instance to a system-supplied message that describes the error, such as "Recursive read lock acquisitions not allowed in this mode." This message takes the current system culture into account. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||`null`.| -||The localized error message string.| - + property of the new instance to a system-supplied message that describes the error, such as "Recursive read lock acquisitions not allowed in this mode." This message takes the current system culture into account. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||`null`.| +||The localized error message string.| + ]]> Handling and Throwing Exceptions @@ -201,18 +201,18 @@ The message that describes the exception. The caller of this constructor must make sure that this string has been localized for the current system culture. Initializes a new instance of the class with a specified message that describes the error. - property of the new exception with the `message` parameter. The content of `message` is intended to be understood by humans. The caller of this constructor must make sure that this string has been localized for the current system culture. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||`null`.| -||The error message string.| - + property of the new exception with the `message` parameter. The content of `message` is intended to be understood by humans. The caller of this constructor must make sure that this string has been localized for the current system culture. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||`null`.| +||The error message string.| + ]]> Handling and Throwing Exceptions @@ -266,19 +266,19 @@ - - + + The object that holds the serialized object data. The contextual information about the source or destination. Initializes a new instance of the class with serialized data. - XML and SOAP Serialization @@ -329,18 +329,18 @@ The exception that caused the current exception. If the parameter is not , the current exception is raised in a block that handles the inner exception. Initializes a new instance of the class with a specified error message and a reference to the inner exception that is the cause of this exception. - property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||The exception specified in `innerException`.| -||The error message string specified in `message`.| - + property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||The exception specified in `innerException`.| +||The error message string specified in `message`.| + ]]> Handling and Throwing Exceptions diff --git a/xml/System.Threading/Monitor.xml b/xml/System.Threading/Monitor.xml index 6f13eb7d27a..18222563e66 100644 --- a/xml/System.Threading/Monitor.xml +++ b/xml/System.Threading/Monitor.xml @@ -1350,9 +1350,9 @@ System.Boolean - - - + + + The object on which to wait. @@ -1414,9 +1414,9 @@ System.Boolean - - - + + + The object on which to wait. diff --git a/xml/System.Threading/Mutex.xml b/xml/System.Threading/Mutex.xml index 0725fce1c32..0e30e799b71 100644 --- a/xml/System.Threading/Mutex.xml +++ b/xml/System.Threading/Mutex.xml @@ -59,57 +59,57 @@ A synchronization primitive that can also be used for interprocess synchronization. - is a synchronization primitive that grants exclusive access to the shared resource to only one thread. If a thread acquires a mutex, the second thread that wants to acquire that mutex is suspended until the first thread releases the mutex. - + is a synchronization primitive that grants exclusive access to the shared resource to only one thread. If a thread acquires a mutex, the second thread that wants to acquire that mutex is suspended until the first thread releases the mutex. + > [!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. - - You can use the method to request ownership of a mutex. The calling thread blocks until one of the following occurs: - -- The mutex is signaled to indicate that it is not owned. When this happens, the method returns `true`, and the calling thread assumes ownership of the mutex and accesses the resource protected by the mutex. When it has finished accessing the resource, the thread must call the method to release ownership of the mutex. The first example in the Examples section illustrates this pattern. - -- The time-out interval specified in the call to a method that has a `millisecondsTimeout` or `timeout` parameter has elapsed. When this happens, the method returns `false`, and the calling thread makes no further attempt to acquire ownership of the mutex. In this case, you should structure your code so that access to the resource that is protected by the mutex is denied to the calling thread. Because the thread never acquired ownership of the mutex, it must not call the method. The second example in the Examples section illustrates this pattern. - - The class enforces thread identity, so a mutex can be released only by the thread that acquired it. By contrast, the class does not enforce thread identity. A mutex can also be passed across application domain boundaries. - - The thread that owns a mutex can request the same mutex in repeated calls to without blocking its execution. However, the thread must call the method the same number of times to release ownership of the mutex. - - Because the class inherits from , you can also call the static and methods to synchronize access to a protected resource. - - If a thread terminates while owning a mutex, the mutex is said to be abandoned. The state of the mutex is set to signaled, and the next waiting thread gets ownership. Beginning in version 2.0 of the .NET Framework, an is thrown in the next thread that acquires the abandoned mutex. Before version 2.0 of the .NET Framework, no exception was thrown. - +> 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 use the method to request ownership of a mutex. The calling thread blocks until one of the following occurs: + +- The mutex is signaled to indicate that it is not owned. When this happens, the method returns `true`, and the calling thread assumes ownership of the mutex and accesses the resource protected by the mutex. When it has finished accessing the resource, the thread must call the method to release ownership of the mutex. The first example in the Examples section illustrates this pattern. + +- The time-out interval specified in the call to a method that has a `millisecondsTimeout` or `timeout` parameter has elapsed. When this happens, the method returns `false`, and the calling thread makes no further attempt to acquire ownership of the mutex. In this case, you should structure your code so that access to the resource that is protected by the mutex is denied to the calling thread. Because the thread never acquired ownership of the mutex, it must not call the method. The second example in the Examples section illustrates this pattern. + + The class enforces thread identity, so a mutex can be released only by the thread that acquired it. By contrast, the class does not enforce thread identity. A mutex can also be passed across application domain boundaries. + + The thread that owns a mutex can request the same mutex in repeated calls to without blocking its execution. However, the thread must call the method the same number of times to release ownership of the mutex. + + Because the class inherits from , you can also call the static and methods to synchronize access to a protected resource. + + If a thread terminates while owning a mutex, the mutex is said to be abandoned. The state of the mutex is set to signaled, and the next waiting thread gets ownership. Beginning in version 2.0 of the .NET Framework, an is thrown in the next thread that acquires the abandoned mutex. Before version 2.0 of the .NET Framework, no exception was thrown. + > [!CAUTION] -> An abandoned mutex often indicates a serious error in the code. When a thread exits without releasing the mutex, the data structures protected by the mutex might not be in a consistent state. The next thread to request ownership of the mutex can handle this exception and proceed, if the integrity of the data structures can be verified. - - In the case of a system-wide mutex, an abandoned mutex might indicate that an application has been terminated abruptly (for example, by using Windows Task Manager). - - Mutexes are of two types: local mutexes, which are unnamed, and named system mutexes. A local mutex exists only within your process. It can be used by any thread in your process that has a reference to the object that represents the mutex. Each unnamed object represents a separate local mutex. - - Named system mutexes are visible throughout the operating system, and can be used to synchronize the activities of processes. You can create a object that represents a named system mutex by using a constructor that accepts a name. The operating-system object can be created at the same time, or it can exist before the creation of the object. You can create multiple objects that represent the same named system mutex, and you can use the method to open an existing named system mutex. - +> An abandoned mutex often indicates a serious error in the code. When a thread exits without releasing the mutex, the data structures protected by the mutex might not be in a consistent state. The next thread to request ownership of the mutex can handle this exception and proceed, if the integrity of the data structures can be verified. + + In the case of a system-wide mutex, an abandoned mutex might indicate that an application has been terminated abruptly (for example, by using Windows Task Manager). + + Mutexes are of two types: local mutexes, which are unnamed, and named system mutexes. A local mutex exists only within your process. It can be used by any thread in your process that has a reference to the object that represents the mutex. Each unnamed object represents a separate local mutex. + + Named system mutexes are visible throughout the operating system, and can be used to synchronize the activities of processes. You can create a object that represents a named system mutex by using a constructor that accepts a name. The operating-system object can be created at the same time, or it can exist before the creation of the object. You can create multiple objects that represent the same named system mutex, and you can use the method to open an existing named system mutex. + > [!NOTE] -> On a server that is running Terminal Services, a named system mutex can have two levels of visibility. If its name begins with the prefix `Global\`, the mutex is visible in all terminal server sessions. If its name begins with the prefix `Local\`, the mutex is visible only in the terminal server session where it was created. In that case, a separate mutex with the same name can exist in each of the other terminal server sessions on the server. If you do not specify a prefix when you create a named mutex, it takes the prefix `Local\`. Within a terminal server session, two mutexes whose names differ only by their prefixes are separate mutexes, and both are visible to all processes in the terminal server session. That is, the prefix names `Global\` and `Local\` describe the scope of the mutex name relative to terminal server sessions, not relative to processes. - +> On a server that is running Terminal Services, a named system mutex can have two levels of visibility. If its name begins with the prefix `Global\`, the mutex is visible in all terminal server sessions. If its name begins with the prefix `Local\`, the mutex is visible only in the terminal server session where it was created. In that case, a separate mutex with the same name can exist in each of the other terminal server sessions on the server. If you do not specify a prefix when you create a named mutex, it takes the prefix `Local\`. Within a terminal server session, two mutexes whose names differ only by their prefixes are separate mutexes, and both are visible to all processes in the terminal server session. That is, the prefix names `Global\` and `Local\` describe the scope of the mutex name relative to terminal server sessions, not relative to processes. + > [!CAUTION] > By default, a named mutex is not restricted to the user that created it. Other users may be able to open and use the mutex, including interfering with the mutex by entering the mutex and not exiting it. On Unix-like operating systems, the file system is used in the implementation of named mutexes, and other users may be able to interfere with named mutexes in more significant ways. On Windows, to restrict access to specific users, you can use a constructor overload or and pass in a when creating the named mutex. On Unix-like operating systems, currently there is no way to restrict access to a named mutex. Avoid using named mutexes without access restrictions on systems that might have untrusted users running code. - + [!INCLUDE[backslash-mutex-note](~/includes/backslash-mutex.md)] - -## Examples - This example shows how a local object is used to synchronize access to a protected resource. Because each calling thread is blocked until it acquires ownership of the mutex, it must call the method to release ownership of the mutex. - + +## Examples + This example shows how a local object is used to synchronize access to a protected resource. Because each calling thread is blocked until it acquires ownership of the mutex, it must call the method to release ownership of the mutex. + :::code language="csharp" source="~/snippets/csharp/System.Threading/Mutex/Overview/example1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.mutex.class/vb/example1.vb" id="Snippet1"::: - - In the following example, each thread calls the method to acquire the mutex. If the time-out interval elapses, the method returns `false`, and the thread neither acquires the mutex nor gains access to the resource the mutex protects. The method is called only by the thread that acquires the mutex. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.mutex.class/vb/example1.vb" id="Snippet1"::: + + In the following example, each thread calls the method to acquire the mutex. If the time-out interval elapses, the method returns `false`, and the thread neither acquires the mutex nor gains access to the resource the mutex protects. The method is called only by the thread that acquires the mutex. + :::code language="csharp" source="~/snippets/csharp/System.Threading/Mutex/Overview/example2.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.mutex.class/vb/example2.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.mutex.class/vb/example2.vb" id="Snippet2"::: + ]]> This type is thread safe. @@ -176,20 +176,20 @@ Initializes a new instance of the class with default properties. - constructor overload and specifying `false` for initial ownership of the mutex. That is, the calling thread does not own the mutex. - - - -## Examples - The following code example shows how a local object is used to synchronize access to a protected resource. The thread that creates the mutex does not own it initially. - + constructor overload and specifying `false` for initial ownership of the mutex. That is, the calling thread does not own the mutex. + + + +## Examples + The following code example shows how a local object is used to synchronize access to a protected resource. The thread that creates the mutex does not own it initially. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.Mutex Default Ctor Example/CPP/class1.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/Mutex/.ctor/class13.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.Mutex Default Ctor Example/VB/class1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.Mutex Default Ctor Example/VB/class1.vb" id="Snippet1"::: + ]]> Managed Threading @@ -247,15 +247,15 @@ to give the calling thread initial ownership of the mutex; otherwise, . Initializes a new instance of the class with a Boolean value that indicates whether the calling thread should have initial ownership of the mutex. - object is used to synchronize access to a protected resource. The thread that creates the owns it initially. - + object is used to synchronize access to a protected resource. The thread that creates the owns it initially. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.Mutex 1Arg Ctor Example/CPP/class1.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/Mutex/.ctor/class1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.Mutex 1Arg Ctor Example/VB/class1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.Mutex 1Arg Ctor Example/VB/class1.vb" id="Snippet1"::: + ]]> Managed Threading @@ -320,42 +320,42 @@ The name, if the synchronization object is to be shared with other processes; otherwise, or an empty string. The name is case-sensitive. The backslash character (\\) is reserved and may only be used to specify a namespace. For more information on namespaces, see the remarks section. There may be further restrictions on the name depending on the operating system. For example, on Unix-based operating systems, the name after excluding the namespace must be a valid file name. Initializes a new instance of the class with a Boolean value that indicates whether the calling thread should have initial ownership of the mutex, and a string that is the name of the mutex. - constructor if you need to determine initial ownership. - - This constructor initializes a object that represents a named system mutex. You can create multiple objects that represent the same named system mutex. - - If the named mutex has already been created with access control security, and the caller does not have , an exception is thrown. To open an existing named mutex with only those permissions needed for synchronizing thread activities, see the method. - - If you specify `null` or an empty string for `name`, a local mutex is created, as if you had called the constructor. In this case, `createdNew` is always `true`. - - Because they are system-wide, named mutexes can be used to coordinate resource use across process boundaries. - + If `name` is not `null` and `initiallyOwned` is `true`, the calling thread owns the mutex only if the named system mutex was created as a result of this call. Since there is no mechanism for determining whether the named system mutex was created, it is better to specify `false` for `initiallyOwned` when calling this constructor overload. You can use the constructor if you need to determine initial ownership. + + This constructor initializes a object that represents a named system mutex. You can create multiple objects that represent the same named system mutex. + + If the named mutex has already been created with access control security, and the caller does not have , an exception is thrown. To open an existing named mutex with only those permissions needed for synchronizing thread activities, see the method. + + If you specify `null` or an empty string for `name`, a local mutex is created, as if you had called the constructor. In this case, `createdNew` is always `true`. + + Because they are system-wide, named mutexes can be used to coordinate resource use across process boundaries. + > [!NOTE] -> On a server that is running Terminal Services, a named system mutex can have two levels of visibility. If its name begins with the prefix `Global\`, the mutex is visible in all terminal server sessions. If its name begins with the prefix `Local\`, the mutex is visible only in the terminal server session where it was created. In that case, a separate mutex with the same name can exist in each of the other terminal server sessions on the server. If you do not specify a prefix when you create a named mutex, it takes the prefix `Local\`. Within a terminal server session, two mutexes whose names differ only by their prefixes are separate mutexes, and both are visible to all processes in the terminal server session. That is, the prefix names `Global\` and `Local\` describe the scope of the mutex name relative to terminal server sessions, not relative to processes. - +> On a server that is running Terminal Services, a named system mutex can have two levels of visibility. If its name begins with the prefix `Global\`, the mutex is visible in all terminal server sessions. If its name begins with the prefix `Local\`, the mutex is visible only in the terminal server session where it was created. In that case, a separate mutex with the same name can exist in each of the other terminal server sessions on the server. If you do not specify a prefix when you create a named mutex, it takes the prefix `Local\`. Within a terminal server session, two mutexes whose names differ only by their prefixes are separate mutexes, and both are visible to all processes in the terminal server session. That is, the prefix names `Global\` and `Local\` describe the scope of the mutex name relative to terminal server sessions, not relative to processes. + > [!CAUTION] > By default, a named mutex is not restricted to the user that created it. Other users may be able to open and use the mutex, including interfering with the mutex by entering the mutex and not exiting it. On Unix-like operating systems, the file system is used in the implementation of named mutexes, and other users may be able to interfere with named mutexes in more significant ways. On Windows, to restrict access to specific users, you can use a constructor overload or and pass in a when creating the named mutex. On Unix-like operating systems, currently there is no way to restrict access to a named mutex. Avoid using named mutexes without access restrictions on systems that might have untrusted users running code. - + [!INCLUDE[backslash-mutex-note](~/includes/backslash-mutex.md)] -## Examples - The following example shows how a named mutex is used to signal between threads running in two separate processes. - - Run this program from two or more command windows. Each process creates a object that represents the named mutex `MyMutex`. The named mutex is a system object whose lifetime is bounded by the lifetimes of the objects that represent it. The named mutex is created when the first process creates its object; in this example, the named mutex is owned by the first process that runs the program. The named mutex is destroyed when all the objects that represent it have been released. - - The constructor overload used in this example cannot tell the calling thread whether initial ownership of the named mutex was granted. You should not use this constructor to request initial ownership unless you can be certain that the thread will create the named mutex. - +## Examples + The following example shows how a named mutex is used to signal between threads running in two separate processes. + + Run this program from two or more command windows. Each process creates a object that represents the named mutex `MyMutex`. The named mutex is a system object whose lifetime is bounded by the lifetimes of the objects that represent it. The named mutex is created when the first process creates its object; in this example, the named mutex is owned by the first process that runs the program. The named mutex is destroyed when all the objects that represent it have been released. + + The constructor overload used in this example cannot tell the calling thread whether initial ownership of the named mutex was granted. You should not use this constructor to request initial ownership unless you can be certain that the thread will create the named mutex. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.Mutex 2Arg Ctor Example/CPP/class1.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/Mutex/.ctor/class11.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.Mutex 2Arg Ctor Example/VB/class1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.Mutex 2Arg Ctor Example/VB/class1.vb" id="Snippet1"::: + ]]> The named mutex exists and has access control security, but the user does not have . @@ -434,38 +434,38 @@ There was some other error. The `HResult` property may provide more information. When this method returns, contains a Boolean that is if a local mutex was created (that is, if is or an empty string) or if the specified named system mutex was created; if the specified named system mutex already existed. This parameter is passed uninitialized. Initializes a new instance of the class with a Boolean value that indicates whether the calling thread should have initial ownership of the mutex, a string that is the name of the mutex, and a Boolean value that, when the method returns, indicates whether the calling thread was granted initial ownership of the mutex. - method. - - This constructor initializes a object that represents a named system mutex. You can create multiple objects that represent the same named system mutex. - - If the named mutex has already been created with access control security, and the caller does not have rights, an exception is thrown. To open an existing named mutex with only those permissions needed for synchronizing thread activities, see the method. - - If you specify `null` or an empty string for `name`, a local mutex is created, as if you had called the constructor. In this case, `createdNew` is always `true`. - - Because they are system-wide, named mutexes can be used to coordinate resource use across process boundaries. - + If `name` is not `null` and `initiallyOwned` is `true`, the calling thread owns the named mutex only if `createdNew` is `true` after the call. Otherwise the thread can request the mutex by calling the method. + + This constructor initializes a object that represents a named system mutex. You can create multiple objects that represent the same named system mutex. + + If the named mutex has already been created with access control security, and the caller does not have rights, an exception is thrown. To open an existing named mutex with only those permissions needed for synchronizing thread activities, see the method. + + If you specify `null` or an empty string for `name`, a local mutex is created, as if you had called the constructor. In this case, `createdNew` is always `true`. + + Because they are system-wide, named mutexes can be used to coordinate resource use across process boundaries. + > [!NOTE] -> On a server that is running Terminal Services, a named system mutex can have two levels of visibility. If its name begins with the prefix `Global\`, the mutex is visible in all terminal server sessions. If its name begins with the prefix `Local\`, the mutex is visible only in the terminal server session where it was created. In that case, a separate mutex with the same name can exist in each of the other terminal server sessions on the server. If you do not specify a prefix when you create a named mutex, it takes the prefix `Local\`. Within a terminal server session, two mutexes whose names differ only by their prefixes are separate mutexes, and both are visible to all processes in the terminal server session. That is, the prefix names `Global\` and `Local\` describe the scope of the mutex name relative to terminal server sessions, not relative to processes. - +> On a server that is running Terminal Services, a named system mutex can have two levels of visibility. If its name begins with the prefix `Global\`, the mutex is visible in all terminal server sessions. If its name begins with the prefix `Local\`, the mutex is visible only in the terminal server session where it was created. In that case, a separate mutex with the same name can exist in each of the other terminal server sessions on the server. If you do not specify a prefix when you create a named mutex, it takes the prefix `Local\`. Within a terminal server session, two mutexes whose names differ only by their prefixes are separate mutexes, and both are visible to all processes in the terminal server session. That is, the prefix names `Global\` and `Local\` describe the scope of the mutex name relative to terminal server sessions, not relative to processes. + > [!CAUTION] > By default, a named mutex is not restricted to the user that created it. Other users may be able to open and use the mutex, including interfering with the mutex by entering the mutex and not exiting it. On Unix-like operating systems, the file system is used in the implementation of named mutexes, and other users may be able to interfere with named mutexes in more significant ways. On Windows, to restrict access to specific users, you can use a constructor overload or and pass in a when creating the named mutex. On Unix-like operating systems, currently there is no way to restrict access to a named mutex. Avoid using named mutexes without access restrictions on systems that might have untrusted users running code. -[!INCLUDE[backslash-mutex-note](~/includes/backslash-mutex.md)] - -## Examples - The following code example shows how a named mutex is used to signal between processes or threads. Run this program from two or more command windows. Each process creates a object that represents the named mutex "MyMutex". The named mutex is a system object. In this example, its lifetime is bounded by the lifetimes of the objects that represent it. The named mutex is created when the first process creates its local object, and destroyed when all the objects that represent it have been released. The named mutex is initially owned by the first process. The second process and any subsequent processes wait for earlier processes to release the named mutex. - +[!INCLUDE[backslash-mutex-note](~/includes/backslash-mutex.md)] + +## Examples + The following code example shows how a named mutex is used to signal between processes or threads. Run this program from two or more command windows. Each process creates a object that represents the named mutex "MyMutex". The named mutex is a system object. In this example, its lifetime is bounded by the lifetimes of the objects that represent it. The named mutex is created when the first process creates its local object, and destroyed when all the objects that represent it have been released. The named mutex is initially owned by the first process. The second process and any subsequent processes wait for earlier processes to release the named mutex. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.Mutex 3Arg Ctor Example/CPP/class1.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/Mutex/.ctor/class12.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.Mutex 3Arg Ctor Example/VB/class1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.Mutex 3Arg Ctor Example/VB/class1.vb" id="Snippet1"::: + ]]> The named mutex exists and has access control security, but the user does not have . @@ -514,10 +514,10 @@ There was some other error. The `HResult` property may provide more information. - - - - + + + + @@ -527,52 +527,52 @@ There was some other error. The `HResult` property may provide more information. A object that represents the access control security to be applied to the named system mutex. Initializes a new instance of the class with a Boolean value that indicates whether the calling thread should have initial ownership of the mutex, a string that is the name of the mutex, a Boolean variable that, when the method returns, indicates whether the calling thread was granted initial ownership of the mutex, and the access control security to be applied to the named mutex. - method. - - Use this constructor to apply access control security to a named system mutex when it is created, preventing other code from taking control of the mutex. - - This constructor initializes a object that represents a named system mutex. You can create multiple objects that represent the same named system mutex. - - If the named system mutex does not exist, it is created with the specified access control security. If the named mutex exists, the specified access control security is ignored. - + If `name` is not `null` and `initiallyOwned` is `true`, the calling thread owns the named mutex only if `createdNew` is `true` after the call. Otherwise the thread can request the mutex by calling the method. + + Use this constructor to apply access control security to a named system mutex when it is created, preventing other code from taking control of the mutex. + + This constructor initializes a object that represents a named system mutex. You can create multiple objects that represent the same named system mutex. + + If the named system mutex does not exist, it is created with the specified access control security. If the named mutex exists, the specified access control security is ignored. + > [!NOTE] -> The caller has full control over the newly created object even if `mutexSecurity` denies or fails to grant some access rights to the current user. However, if the current user attempts to get another object to represent the same named mutex, using either a constructor or the method, Windows access control security is applied. - - If the named mutex has already been created with access control security, and the caller does not have , an exception is thrown. To open an existing named mutex with only those permissions needed for synchronizing thread activities, see the method. - - If you specify `null` or an empty string for `name`, a local mutex is created, as if you had called the constructor. In this case, `createdNew` is always `true`. - - Because they are system-wide, named mutexes can be used to coordinate resource use across process boundaries. - +> The caller has full control over the newly created object even if `mutexSecurity` denies or fails to grant some access rights to the current user. However, if the current user attempts to get another object to represent the same named mutex, using either a constructor or the method, Windows access control security is applied. + + If the named mutex has already been created with access control security, and the caller does not have , an exception is thrown. To open an existing named mutex with only those permissions needed for synchronizing thread activities, see the method. + + If you specify `null` or an empty string for `name`, a local mutex is created, as if you had called the constructor. In this case, `createdNew` is always `true`. + + Because they are system-wide, named mutexes can be used to coordinate resource use across process boundaries. + > [!NOTE] -> On a server that is running Terminal Services, a named system mutex can have two levels of visibility. If its name begins with the prefix `Global\`, the mutex is visible in all terminal server sessions. If its name begins with the prefix `Local\`, the mutex is visible only in the terminal server session where it was created. In that case, a separate mutex with the same name can exist in each of the other terminal server sessions on the server. If you do not specify a prefix when you create a named mutex, it takes the prefix `Local\`. Within a terminal server session, two mutexes whose names differ only by their prefixes are separate mutexes, and both are visible to all processes in the terminal server session. That is, the prefix names `Global\` and `Local\` describe the scope of the mutex name relative to terminal server sessions, not relative to processes. - +> On a server that is running Terminal Services, a named system mutex can have two levels of visibility. If its name begins with the prefix `Global\`, the mutex is visible in all terminal server sessions. If its name begins with the prefix `Local\`, the mutex is visible only in the terminal server session where it was created. In that case, a separate mutex with the same name can exist in each of the other terminal server sessions on the server. If you do not specify a prefix when you create a named mutex, it takes the prefix `Local\`. Within a terminal server session, two mutexes whose names differ only by their prefixes are separate mutexes, and both are visible to all processes in the terminal server session. That is, the prefix names `Global\` and `Local\` describe the scope of the mutex name relative to terminal server sessions, not relative to processes. + > [!CAUTION] > By default, a named mutex is not restricted to the user that created it. Other users may be able to open and use the mutex, including interfering with the mutex by entering the mutex and not exiting it. To restrict access to specific users, you can pass in a when creating the named mutex. Avoid using named mutexes without access restrictions on systems that might have untrusted users running code. -[!INCLUDE[backslash-mutex-note](~/includes/backslash-mutex.md)] - - -## Examples - The following code example demonstrates the cross-process behavior of a named mutex with access control security. The example uses the method overload to test for the existence of a named mutex. - - If the mutex does not exist, it is created with initial ownership and access control security that denies the current user the right to use the mutex, but grants the right to read and change permissions on the mutex. - - If you run the compiled example from two command windows, the second copy will throw an access violation exception on the call to . The exception is caught, and the example uses the method overload to open the mutex with the rights needed to read and change the permissions. - - After the permissions are changed, the mutex is opened with the rights required to enter and release it. If you run the compiled example from a third command window, it runs using the new permissions. - +[!INCLUDE[backslash-mutex-note](~/includes/backslash-mutex.md)] + + +## Examples + The following code example demonstrates the cross-process behavior of a named mutex with access control security. The example uses the method overload to test for the existence of a named mutex. + + If the mutex does not exist, it is created with initial ownership and access control security that denies the current user the right to use the mutex, but grants the right to read and change permissions on the mutex. + + If you run the compiled example from two command windows, the second copy will throw an access violation exception on the call to . The exception is caught, and the example uses the method overload to open the mutex with the rights needed to read and change the permissions. + + After the permissions are changed, the mutex is opened with the rights required to enter and release it. If you run the compiled example from a third command window, it runs using the new permissions. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.Mutex.ctor named 4/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/Mutex/.ctor/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.Mutex.ctor named 4/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.Mutex.ctor named 4/VB/source.vb" id="Snippet1"::: + ]]> @@ -622,35 +622,35 @@ There was some other error. The `HResult` property may provide more information. Gets a object that represents the access control security for the named mutex. A object that represents the access control security for the named mutex. - method uses the following combination of flags (combined using the bitwise OR operation) to search for permissions: , , and . - + method uses the following combination of flags (combined using the bitwise OR operation) to search for permissions: , , and . + The user must have to call this method, and the mutex must have been opened with . > [!NOTE] > In .NET Core and .NET 5+, the equivalent method is . -## Examples - The following code example demonstrates the cross-process behavior of a named mutex with access control security. The example uses the method overload to test for the existence of a named mutex. - - If the mutex does not exist, it is created with initial ownership and access control security that denies the current user the right to use the mutex, but grants the right to read and change permissions on the mutex. - - If you run the compiled example from two command windows, the second copy will throw an access violation exception on the call to . The exception is caught, and the example uses the method overload to open the mutex with the rights needed to read and change the permissions, using the and methods. - - After the permissions are changed, the mutex is opened with the rights required to enter and release it. If you run the compiled example from a third command window, it runs using the new permissions. - +## Examples + The following code example demonstrates the cross-process behavior of a named mutex with access control security. The example uses the method overload to test for the existence of a named mutex. + + If the mutex does not exist, it is created with initial ownership and access control security that denies the current user the right to use the mutex, but grants the right to read and change permissions on the mutex. + + If you run the compiled example from two command windows, the second copy will throw an access violation exception on the call to . The exception is caught, and the example uses the method overload to open the mutex with the rights needed to read and change the permissions, using the and methods. + + After the permissions are changed, the mutex is opened with the rights required to enter and release it. If you run the compiled example from a third command window, it runs using the new permissions. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.Mutex.ctor named 4/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/Mutex/.ctor/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.Mutex.ctor named 4/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.Mutex.ctor named 4/VB/source.vb" id="Snippet1"::: + ]]> - The current object represents a named system mutex, but the user does not have . - - -or- - + The current object represents a named system mutex, but the user does not have . + + -or- + The current object represents a named system mutex, and was not opened with . @@ -714,38 +714,38 @@ There was some other error. The `HResult` property may provide more information. Opens the specified named mutex, if it already exists. An object that represents the named system mutex. - method tries to open the specified named system mutex. To create the system mutex when it does not already exist, use one of the constructors that has a `name` parameter. - - Multiple calls to this method that use the same value for `name` do not necessarily return the same object, even though the objects that are returned represent the same named system mutex. - - This method overload is equivalent to calling the method overload and specifying and rights, combined by using the bitwise OR operation. - - Specifying the flag allows a thread to wait on the mutex, and specifying the flag allows a thread to call the method. - - This method does not request ownership of the mutex. - - - -## Examples - The following code example demonstrates the cross-process behavior of a named mutex with access control security. The example uses the method overload to test for the existence of a named mutex. - - If the mutex does not exist, it is created with initial ownership and access control security that denies the current user the right to use the mutex, but grants the right to read and change permissions on the mutex. - - If you run the compiled example from two command windows, the second copy will throw an access violation exception on the call to . The exception is caught, and the example uses the method overload to open the mutex with the rights needed to read and change the permissions. - - After the permissions are changed, the mutex is opened with the rights required to enter and release it. If you run the compiled example from a third command window, it runs using the new permissions. - + The method tries to open the specified named system mutex. To create the system mutex when it does not already exist, use one of the constructors that has a `name` parameter. + + Multiple calls to this method that use the same value for `name` do not necessarily return the same object, even though the objects that are returned represent the same named system mutex. + + This method overload is equivalent to calling the method overload and specifying and rights, combined by using the bitwise OR operation. + + Specifying the flag allows a thread to wait on the mutex, and specifying the flag allows a thread to call the method. + + This method does not request ownership of the mutex. + + + +## Examples + The following code example demonstrates the cross-process behavior of a named mutex with access control security. The example uses the method overload to test for the existence of a named mutex. + + If the mutex does not exist, it is created with initial ownership and access control security that denies the current user the right to use the mutex, but grants the right to read and change permissions on the mutex. + + If you run the compiled example from two command windows, the second copy will throw an access violation exception on the call to . The exception is caught, and the example uses the method overload to open the mutex with the rights needed to read and change the permissions. + + After the permissions are changed, the mutex is opened with the rights required to enter and release it. If you run the compiled example from a third command window, it runs using the new permissions. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.Mutex.ctor named 4/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/Mutex/.ctor/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.Mutex.ctor named 4/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.Mutex.ctor named 4/VB/source.vb" id="Snippet1"::: + ]]> @@ -797,8 +797,8 @@ There was some other error. The `HResult` property may provide more information. System.Threading.Mutex - - + + The name of the synchronization object to be shared with other processes. The name is case-sensitive. The backslash character (\\) is reserved and may only be used to specify a namespace. For more information on namespaces, see the remarks section. There may be further restrictions on the name depending on the operating system. For example, on Unix-based operating systems, the name after excluding the namespace must be a valid file name. @@ -806,36 +806,36 @@ There was some other error. The `HResult` property may provide more information. Opens the specified named mutex, if it already exists, with the desired security access. An object that represents the named system mutex. - flag to allow threads to wait on the mutex, and the flag to allow threads to call the method. - - The method tries to open an existing named mutex. To create the system mutex when it does not already exist, use one of the constructors that has a `name` parameter. - - Multiple calls to this method that use the same value for `name` do not necessarily return the same object, even though the objects that are returned represent the same named system mutex. - - This method does not request ownership of the mutex. - - - -## Examples - The following code example demonstrates the cross-process behavior of a named mutex with access control security. The example uses the method overload to test for the existence of a named mutex. - - If the mutex does not exist, it is created with initial ownership and access control security that denies the current user the right to use the mutex, but grants the right to read and change permissions on the mutex. - - If you run the compiled example from two command windows, the second copy will throw an access violation exception on the call to . The exception is caught, and the example uses the method overload to open the mutex with the rights needed to read and change the permissions. - - After the permissions are changed, the mutex is opened with the rights required to enter and release it. If you run the compiled example from a third command window, it runs using the new permissions. - + The `rights` parameter must include the flag to allow threads to wait on the mutex, and the flag to allow threads to call the method. + + The method tries to open an existing named mutex. To create the system mutex when it does not already exist, use one of the constructors that has a `name` parameter. + + Multiple calls to this method that use the same value for `name` do not necessarily return the same object, even though the objects that are returned represent the same named system mutex. + + This method does not request ownership of the mutex. + + + +## Examples + The following code example demonstrates the cross-process behavior of a named mutex with access control security. The example uses the method overload to test for the existence of a named mutex. + + If the mutex does not exist, it is created with initial ownership and access control security that denies the current user the right to use the mutex, but grants the right to read and change permissions on the mutex. + + If you run the compiled example from two command windows, the second copy will throw an access violation exception on the call to . The exception is caught, and the example uses the method overload to open the mutex with the rights needed to read and change the permissions. + + After the permissions are changed, the mutex is opened with the rights required to enter and release it. If you run the compiled example from a third command window, it runs using the new permissions. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.Mutex.ctor named 4/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/Mutex/.ctor/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.Mutex.ctor named 4/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.Mutex.ctor named 4/VB/source.vb" id="Snippet1"::: + ]]> @@ -908,32 +908,32 @@ There was some other error. The `HResult` property may provide more information. Releases the once. - method), it must subsequently call to relinquish ownership of the mutex and unblock other threads that are trying to gain ownership of the mutex. If the attempt to get ownership of the mutex fails (for example, when a call to the method with a `millisecondsTimeout` or a `timeout` parameter returns `false` because the request times out), the thread shouldn't call , In this case, the thread should also not be allowed to access the resource protected by the mutex, as the following example shows. - + method), it must subsequently call to relinquish ownership of the mutex and unblock other threads that are trying to gain ownership of the mutex. If the attempt to get ownership of the mutex fails (for example, when a call to the method with a `millisecondsTimeout` or a `timeout` parameter returns `false` because the request times out), the thread shouldn't call , In this case, the thread should also not be allowed to access the resource protected by the mutex, as the following example shows. + :::code language="csharp" source="~/snippets/csharp/System.Threading/Mutex/Overview/example2.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.mutex.class/vb/example2.vb" id="Snippet2"::: - - A thread that owns a mutex can specify the same mutex in repeated wait function calls without blocking its execution. The number of calls is kept by the common language runtime. The thread must call the same number of times to release ownership of the mutex. - - If a thread terminates while owning a mutex, the mutex is said to be abandoned. The state of the mutex is set to signaled and the next waiting thread gets ownership. If no one owns the mutex, the state of the mutex is signaled. Beginning in version 2.0 of the .NET Framework, an is thrown in the next thread that acquires the mutex. Prior to version 2.0 of the .NET Framework, no exception was thrown. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.mutex.class/vb/example2.vb" id="Snippet2"::: + + A thread that owns a mutex can specify the same mutex in repeated wait function calls without blocking its execution. The number of calls is kept by the common language runtime. The thread must call the same number of times to release ownership of the mutex. + + If a thread terminates while owning a mutex, the mutex is said to be abandoned. The state of the mutex is set to signaled and the next waiting thread gets ownership. If no one owns the mutex, the state of the mutex is signaled. Beginning in version 2.0 of the .NET Framework, an is thrown in the next thread that acquires the mutex. Prior to version 2.0 of the .NET Framework, no exception was thrown. + > [!CAUTION] -> An abandoned mutex often indicates a serious error in the code. When a thread exits without releasing the mutex, the data structures protected by the mutex might not be in a consistent state. The next thread to request ownership of the mutex can handle this exception and proceed, if the integrity of the data structures can be verified. - - In the case of a system-wide mutex, an abandoned mutex might indicate that an application has been terminated abruptly (for example, by using Windows Task Manager). - - - -## Examples - The following example shows how a local object is used to synchronize access to a protected resource. The thread that creates the mutex does not own it initially. The method is used to release the mutex when it is no longer needed. - +> An abandoned mutex often indicates a serious error in the code. When a thread exits without releasing the mutex, the data structures protected by the mutex might not be in a consistent state. The next thread to request ownership of the mutex can handle this exception and proceed, if the integrity of the data structures can be verified. + + In the case of a system-wide mutex, an abandoned mutex might indicate that an application has been terminated abruptly (for example, by using Windows Task Manager). + + + +## Examples + The following example shows how a local object is used to synchronize access to a protected resource. The thread that creates the mutex does not own it initially. The method is used to release the mutex when it is no longer needed. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.Mutex Default Ctor Example/CPP/class1.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/Mutex/.ctor/class13.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.Mutex Default Ctor Example/VB/class1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.Mutex Default Ctor Example/VB/class1.vb" id="Snippet1"::: + ]]> The calling thread does not own the mutex. @@ -971,41 +971,41 @@ There was some other error. The `HResult` property may provide more information. System.Void - + A object that represents the access control security to be applied to the named system mutex. Sets the access control security for a named system mutex. - rights to call this method, and the mutex must have been opened with . > [!NOTE] > In .NET Core and .NET 5+, the equivalent method is . -## Examples - The following code example demonstrates the cross-process behavior of a named mutex with access control security. The example uses the method overload to test for the existence of a named mutex. - - If the mutex does not exist, it is created with initial ownership and access control security that denies the current user the right to use the mutex, but grants the right to read and change permissions on the mutex. - - If you run the compiled example from two command windows, the second copy will throw an access violation exception on the call to . The exception is caught, and the example uses the method overload to open the mutex with the rights needed to read and change the permissions, using the and methods. - - After the permissions are changed, the mutex is opened with the rights required to enter and release it. If you run the compiled example from a third command window, it runs using the new permissions. - +## Examples + The following code example demonstrates the cross-process behavior of a named mutex with access control security. The example uses the method overload to test for the existence of a named mutex. + + If the mutex does not exist, it is created with initial ownership and access control security that denies the current user the right to use the mutex, but grants the right to read and change permissions on the mutex. + + If you run the compiled example from two command windows, the second copy will throw an access violation exception on the call to . The exception is caught, and the example uses the method overload to open the mutex with the rights needed to read and change the permissions, using the and methods. + + After the permissions are changed, the mutex is opened with the rights required to enter and release it. If you run the compiled example from a third command window, it runs using the new permissions. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.Mutex.ctor named 4/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/Mutex/.ctor/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.Mutex.ctor named 4/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.Mutex.ctor named 4/VB/source.vb" id="Snippet1"::: + ]]> is . - The user does not have . - - -or- - + The user does not have . + + -or- + The mutex was not opened with . The current object does not represent a named system mutex. @@ -1084,23 +1084,23 @@ There was some other error. The `HResult` property may provide more information. if the named mutex was opened successfully; otherwise, . In some cases, may be returned for invalid names. - constructors that has a `name` parameter. - - If you are uncertain whether a named mutex exists, use this method overload instead of the method overload, which throws an exception if the mutex does not exist. - - Multiple calls to this method that use the same value for `name` do not necessarily return the same object, even though the objects that are returned represent the same named system mutex. - - This method overload is equivalent to calling the method overload and specifying and rights, combined by using the bitwise OR operation. Specifying the flag allows a thread to wait on the mutex, and specifying the flag allows a thread to call the method. - - This method does not request ownership of the mutex. - + To create the system mutex when it does not already exist, use one of the constructors that has a `name` parameter. + + If you are uncertain whether a named mutex exists, use this method overload instead of the method overload, which throws an exception if the mutex does not exist. + + Multiple calls to this method that use the same value for `name` do not necessarily return the same object, even though the objects that are returned represent the same named system mutex. + + This method overload is equivalent to calling the method overload and specifying and rights, combined by using the bitwise OR operation. Specifying the flag allows a thread to wait on the mutex, and specifying the flag allows a thread to call the method. + + This method does not request ownership of the mutex. + ]]> @@ -1149,9 +1149,9 @@ There was some other error. The `HResult` property may provide more information. System.Boolean - - - + + + The name of the synchronization object to be shared with other processes. The name is case-sensitive. The backslash character (\\) is reserved and may only be used to specify a namespace. For more information on namespaces, see the remarks section. There may be further restrictions on the name depending on the operating system. For example, on Unix-based operating systems, the name after excluding the namespace must be a valid file name. @@ -1161,23 +1161,23 @@ There was some other error. The `HResult` property may provide more information. if the named mutex was opened successfully; otherwise, . In some cases, may be returned for invalid names. - constructors that has a `name` parameter. - - If you are uncertain whether a named mutex exists, use this method overload instead of the method overload, which throws an exception if the mutex does not exist. - - The `rights` parameter must include the flag to allow threads to wait on the mutex, and the flag to allow threads to call the method. - - Multiple calls to this method that use the same value for `name` do not necessarily return the same object, even though the objects that are returned represent the same named system mutex. - - This method does not request ownership of the mutex. - + To create the system mutex when it does not already exist, use one of the constructors that has a `name` parameter. + + If you are uncertain whether a named mutex exists, use this method overload instead of the method overload, which throws an exception if the mutex does not exist. + + The `rights` parameter must include the flag to allow threads to wait on the mutex, and the flag to allow threads to call the method. + + Multiple calls to this method that use the same value for `name` do not necessarily return the same object, even though the objects that are returned represent the same named system mutex. + + This method does not request ownership of the mutex. + ]]> diff --git a/xml/System.Threading/Semaphore.xml b/xml/System.Threading/Semaphore.xml index db3aad48670..e6fffe2d4a3 100644 --- a/xml/System.Threading/Semaphore.xml +++ b/xml/System.Threading/Semaphore.xml @@ -58,35 +58,35 @@ Limits the number of threads that can access a resource or pool of resources concurrently. - class to control access to a pool of resources. Threads enter the semaphore by calling the method, which is inherited from the class, and release the semaphore by calling the method. - - The count on a semaphore is decremented each time a thread enters the semaphore, and incremented when a thread releases the semaphore. When the count is zero, subsequent requests block until other threads release the semaphore. When all threads have released the semaphore, the count is at the maximum value specified when the semaphore was created. - - There is no guaranteed order, such as FIFO or LIFO, in which blocked threads enter the semaphore. - - A thread can enter the semaphore multiple times, by calling the method repeatedly. To release some or all of these entries, the thread can call the parameterless method overload multiple times, or it can call the method overload that specifies the number of entries to be released. - - The class does not enforce thread identity on calls to or . It is the programmer's responsibility to ensure that threads do not release the semaphore too many times. For example, suppose a semaphore has a maximum count of two, and that thread A and thread B both enter the semaphore. If a programming error in thread B causes it to call twice, both calls succeed. The count on the semaphore is full, and when thread A eventually calls , a is thrown. - - Semaphores are of two types: local semaphores and named system semaphores. If you create a object using a constructor that accepts a name, it is associated with an operating-system semaphore of that name. Named system semaphores are visible throughout the operating system, and can be used to synchronize the activities of processes. You can create multiple objects that represent the same named system semaphore, and you can use the method to open an existing named system semaphore. - - A local semaphore exists only within your process. It can be used by any thread in your process that has a reference to the local object. Each object is a separate local semaphore. - + class to control access to a pool of resources. Threads enter the semaphore by calling the method, which is inherited from the class, and release the semaphore by calling the method. + + The count on a semaphore is decremented each time a thread enters the semaphore, and incremented when a thread releases the semaphore. When the count is zero, subsequent requests block until other threads release the semaphore. When all threads have released the semaphore, the count is at the maximum value specified when the semaphore was created. + + There is no guaranteed order, such as FIFO or LIFO, in which blocked threads enter the semaphore. + + A thread can enter the semaphore multiple times, by calling the method repeatedly. To release some or all of these entries, the thread can call the parameterless method overload multiple times, or it can call the method overload that specifies the number of entries to be released. + + The class does not enforce thread identity on calls to or . It is the programmer's responsibility to ensure that threads do not release the semaphore too many times. For example, suppose a semaphore has a maximum count of two, and that thread A and thread B both enter the semaphore. If a programming error in thread B causes it to call twice, both calls succeed. The count on the semaphore is full, and when thread A eventually calls , a is thrown. + + Semaphores are of two types: local semaphores and named system semaphores. If you create a object using a constructor that accepts a name, it is associated with an operating-system semaphore of that name. Named system semaphores are visible throughout the operating system, and can be used to synchronize the activities of processes. You can create multiple objects that represent the same named system semaphore, and you can use the method to open an existing named system semaphore. + + A local semaphore exists only within your process. It can be used by any thread in your process that has a reference to the local object. Each object is a separate local semaphore. + > [!CAUTION] > By default, a named semaphore is not restricted to the user that created it. Other users may be able to open and use the semaphore, including interfering with the semaphore by acquiring the semaphore multiple times and not releasing it. To restrict access to specific users, you can use a constructor overload or and pass in a when creating the named semaphore. Avoid using named semaphores without access restrictions on systems that might have untrusted users running code. - - - -## Examples - The following code example creates a semaphore with a maximum count of three and an initial count of zero. The example starts five threads, which block waiting for the semaphore. The main thread uses the method overload to increase the semaphore count to its maximum, allowing three threads to enter the semaphore. Each thread uses the method to wait for one second, to simulate work, and then calls the method overload to release the semaphore. Each time the semaphore is released, the previous semaphore count is displayed. Console messages track semaphore use. The simulated work interval is increased slightly for each thread, to make the output easier to read. - + + + +## Examples + The following code example creates a semaphore with a maximum count of three and an initial count of zero. The example starts five threads, which block waiting for the semaphore. The main thread uses the method overload to increase the semaphore count to its maximum, allowing three threads to enter the semaphore. Each thread uses the method to wait for one second, to simulate work, and then calls the method overload to release the semaphore. Each time the semaphore is released, the previous semaphore count is displayed. Console messages track semaphore use. The simulated work interval is increased slightly for each thread, to make the output easier to read. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.Semaphore2/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/Semaphore/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.Semaphore2/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.Semaphore2/VB/source.vb" id="Snippet1"::: + ]]> This type is thread safe. @@ -156,31 +156,31 @@ The maximum number of requests for the semaphore that can be granted concurrently. Initializes a new instance of the class, specifying the initial number of entries and the maximum number of concurrent entries. - (`maximumCount` minus `initialCount`) times. If you do not want to reserve any entries for the thread that creates the semaphore, use the same number for `maximumCount` and `initialCount`. - - - -## Examples - The following example creates a semaphore with a maximum count of three and an initial count of zero. The example starts five threads, which block waiting for the semaphore. The main thread uses the method overload to increase the semaphore count to its maximum, allowing three threads to enter the semaphore. Each thread uses the method to wait for one second, to simulate work, and then calls the method overload to release the semaphore. Each time the semaphore is released, the previous semaphore count is displayed. Console messages track semaphore use. The simulated work interval is increased slightly for each thread, to make the output easier to read. - + (`maximumCount` minus `initialCount`) times. If you do not want to reserve any entries for the thread that creates the semaphore, use the same number for `maximumCount` and `initialCount`. + + + +## Examples + The following example creates a semaphore with a maximum count of three and an initial count of zero. The example starts five threads, which block waiting for the semaphore. The main thread uses the method overload to increase the semaphore count to its maximum, allowing three threads to enter the semaphore. Each thread uses the method to wait for one second, to simulate work, and then calls the method overload to release the semaphore. Each time the semaphore is released, the previous semaphore count is displayed. Console messages track semaphore use. The simulated work interval is increased slightly for each thread, to make the output easier to read. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.Semaphore2/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/Semaphore/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.Semaphore2/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.Semaphore2/VB/source.vb" id="Snippet1"::: + ]]> is greater than . - is less than 1. - - -or- - + is less than 1. + + -or- + is less than 0. Managed Threading Semaphore @@ -236,38 +236,38 @@ The name, if the synchronization object is to be shared with other processes; otherwise, or an empty string. The name is case-sensitive. The backslash character (\\) is reserved and may only be used to specify a namespace. For more information on namespaces, see the remarks section. There may be further restrictions on the name depending on the operating system. For example, on Unix-based operating systems, the name after excluding the namespace must be a valid file name. Initializes a new instance of the class, specifying the initial number of entries and the maximum number of concurrent entries, and optionally specifying the name of a system semaphore object. - object that represents a named system semaphore. You can create multiple objects that represent the same named system semaphore. - + object that represents a named system semaphore. You can create multiple objects that represent the same named system semaphore. + The `name` may be prefixed with `Global\` or `Local\` to specify a namespace. When the `Global` namespace is specified, the synchronization object may be shared with any processes on the system. When the `Local` namespace is specified, which is also the default when no namespace is specified, the synchronization object may be shared with processes in the same session. On Windows, a session is a login session, and services typically run in a different non-interactive session. On Unix-like operating systems, each shell has its own session. Session-local synchronization objects may be appropriate for synchronizing between processes with a parent/child relationship where they all run in the same session. For more information about synchronization object names on Windows, see [Object Names](https://docs.microsoft.com/windows/win32/sync/object-names). If a `name` is provided and a synchronization object of the requested type already exists in the namespace, the existing synchronization object is used. If a synchronization object of a different type already exists in the namespace, a `WaitHandleCannotBeOpenedException` is thrown. Otherwise, a new synchronization object is created. - If the named system semaphore does not exist, it is created with the initial count and maximum count specified by `initialCount` and `maximumCount`. If the named system semaphore already exists, `initialCount` and `maximumCount` are not used, although invalid values still cause exceptions. If you need to determine whether or not a named system semaphore was created, use the constructor overload instead. - + If the named system semaphore does not exist, it is created with the initial count and maximum count specified by `initialCount` and `maximumCount`. If the named system semaphore already exists, `initialCount` and `maximumCount` are not used, although invalid values still cause exceptions. If you need to determine whether or not a named system semaphore was created, use the constructor overload instead. + > [!IMPORTANT] -> When you use this constructor overload, the recommended practice is to specify the same number for `initialCount` and `maximumCount`. If `initialCount` is less than `maximumCount`, and a named system semaphore is created, the effect is the same as if the current thread had called (`maximumCount` minus `initialCount`) times. However, with this constructor overload there is no way to determine whether a named system semaphore was created. - - If you specify `null` or an empty string for `name`, a local semaphore is created, as if you had called the constructor overload. - - Because named semaphores are visible throughout the operating system, they can be used to coordinate resource use across process boundaries. - - If you want to find out whether a named system semaphore exists, use the method. The method attempts to open an existing named semaphore, and throws an exception if the system semaphore does not exist. - +> When you use this constructor overload, the recommended practice is to specify the same number for `initialCount` and `maximumCount`. If `initialCount` is less than `maximumCount`, and a named system semaphore is created, the effect is the same as if the current thread had called (`maximumCount` minus `initialCount`) times. However, with this constructor overload there is no way to determine whether a named system semaphore was created. + + If you specify `null` or an empty string for `name`, a local semaphore is created, as if you had called the constructor overload. + + Because named semaphores are visible throughout the operating system, they can be used to coordinate resource use across process boundaries. + + If you want to find out whether a named system semaphore exists, use the method. The method attempts to open an existing named semaphore, and throws an exception if the system semaphore does not exist. + > [!CAUTION] > By default, a named semaphore is not restricted to the user that created it. Other users may be able to open and use the semaphore, including interfering with the semaphore by acquiring the semaphore multiple times and not releasing it. To restrict access to specific users, you can use a constructor overload or and pass in a when creating the named semaphore. Avoid using named semaphores without access restrictions on systems that might have untrusted users running code. - - - -## Examples - The following code example demonstrates the cross-process behavior of a named semaphore. The example creates a named semaphore with a maximum count of five and an initial count of five. The program makes three calls to the method. Thus, if you run the compiled example from two command windows, the second copy will block on the third call to . Release one or more entries in the first copy of the program to unblock the second. - + + + +## Examples + The following code example demonstrates the cross-process behavior of a named semaphore. The example creates a named semaphore with a maximum count of five and an initial count of five. The program makes three calls to the method. Thus, if you run the compiled example from two command windows, the second copy will block on the third call to . Release one or more entries in the first copy of the program to unblock the second. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.Semaphore.ctor named 3/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/Semaphore/.ctor/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.Semaphore.ctor named 3/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.Semaphore.ctor named 3/VB/source.vb" id="Snippet1"::: + ]]> @@ -277,10 +277,10 @@ .NET Framework only: is longer than MAX_PATH (260 characters). - is less than 1. - - -or- - + is less than 1. + + -or- + is less than 0. is invalid. This can be for various reasons, including some restrictions that may be placed by the operating system, such as an unknown prefix or invalid characters. Note that the name and common prefixes "Global\\" and "Local\\" are case-sensitive. @@ -352,35 +352,35 @@ There was some other error. The `HResult` property may provide more information. When this method returns, contains if a local semaphore was created (that is, if is or an empty string) or if the specified named system semaphore was created; if the specified named system semaphore already existed. This parameter is passed uninitialized. Initializes a new instance of the class, specifying the initial number of entries and the maximum number of concurrent entries, optionally specifying the name of a system semaphore object, and specifying a variable that receives a value indicating whether a new system semaphore was created. - object that represents a named system semaphore. You can create multiple objects that represent the same named system semaphore. - - If the named system semaphore does not exist, it is created with the initial count and maximum count specified by `initialCount` and `maximumCount`. If the named system semaphore already exists, `initialCount` and `maximumCount` are not used, although invalid values still cause exceptions. Use `createdNew` to determine whether the system semaphore was created. - - If `initialCount` is less than `maximumCount`, and `createdNew` is `true`, the effect is the same as if the current thread had called (`maximumCount` minus `initialCount`) times. - - If you specify `null` or an empty string for `name`, a local semaphore is created, as if you had called the constructor overload. In this case, `createdNew` is always `true`. - - Because named semaphores are visible throughout the operating system, they can be used to coordinate resource use across process boundaries. - + This constructor initializes a object that represents a named system semaphore. You can create multiple objects that represent the same named system semaphore. + + If the named system semaphore does not exist, it is created with the initial count and maximum count specified by `initialCount` and `maximumCount`. If the named system semaphore already exists, `initialCount` and `maximumCount` are not used, although invalid values still cause exceptions. Use `createdNew` to determine whether the system semaphore was created. + + If `initialCount` is less than `maximumCount`, and `createdNew` is `true`, the effect is the same as if the current thread had called (`maximumCount` minus `initialCount`) times. + + If you specify `null` or an empty string for `name`, a local semaphore is created, as if you had called the constructor overload. In this case, `createdNew` is always `true`. + + Because named semaphores are visible throughout the operating system, they can be used to coordinate resource use across process boundaries. + > [!CAUTION] > By default, a named semaphore is not restricted to the user that created it. Other users may be able to open and use the semaphore, including interfering with the semaphore by acquiring the semaphore multiple times and not releasing it. To restrict access to specific users, you can use a constructor overload or and pass in a when creating the named semaphore. Avoid using named semaphores without access restrictions on systems that might have untrusted users running code. - - - -## Examples - The following code example demonstrates the cross-process behavior of a named semaphore. The example creates a named semaphore with a maximum count of five and an initial count of two. That is, it reserves three entries for the thread that calls the constructor. If `createNew` is `false`, the program makes three calls to the method. Thus, if you run the compiled example from two command windows, the second copy will block on the third call to . Release one or more entries in the first copy of the program to unblock the second. - + + + +## Examples + The following code example demonstrates the cross-process behavior of a named semaphore. The example creates a named semaphore with a maximum count of five and an initial count of two. That is, it reserves three entries for the thread that calls the constructor. If `createNew` is `false`, the program makes three calls to the method. Thus, if you run the compiled example from two command windows, the second copy will block on the third call to . Release one or more entries in the first copy of the program to unblock the second. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.Semaphore.ctor named 4/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/Semaphore/.ctor/source1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.Semaphore.ctor named 4/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.Semaphore.ctor named 4/VB/source.vb" id="Snippet1"::: + ]]> @@ -390,10 +390,10 @@ There was some other error. The `HResult` property may provide more information. .NET Framework only: is longer than MAX_PATH (260 characters). - is less than 1. - - -or- - + is less than 1. + + -or- + is less than 0. is invalid. This can be for various reasons, including some restrictions that may be placed by the operating system, such as an unknown prefix or invalid characters. Note that the name and common prefixes "Global\\" and "Local\\" are case-sensitive. @@ -429,11 +429,11 @@ There was some other error. The `HResult` property may provide more information. netstandard - - - - - + + + + + The initial number of requests for the semaphore that can be satisfied concurrently. @@ -443,44 +443,44 @@ There was some other error. The `HResult` property may provide more information. A object that represents the access control security to be applied to the named system semaphore. Initializes a new instance of the class, specifying the initial number of entries and the maximum number of concurrent entries, optionally specifying the name of a system semaphore object, specifying a variable that receives a value indicating whether a new system semaphore was created, and specifying security access control for the system semaphore. - object that represents a named system semaphore. You can create multiple objects that represent the same named system semaphore. - - If the named system semaphore does not exist, it is created with the specified access control security. If the named semaphore exists, the specified access control security is ignored. - + This constructor initializes a object that represents a named system semaphore. You can create multiple objects that represent the same named system semaphore. + + If the named system semaphore does not exist, it is created with the specified access control security. If the named semaphore exists, the specified access control security is ignored. + > [!NOTE] -> The caller has full control over the newly created object even if `semaphoreSecurity` denies or fails to grant some access rights to the current user. However, if the current user attempts to get another object to represent the same named semaphore, using either a constructor or the method, Windows access control security is applied. - - If the named system semaphore does not exist, it is created with the initial count and maximum count specified by `initialCount` and `maximumCount`. If the named system semaphore already exists, `initialCount` and `maximumCount` are not used, although invalid values still cause exceptions. Use the `createdNew` parameter to determine whether the system semaphore was created by this constructor. - - If `initialCount` is less than `maximumCount`, and `createdNew` is `true`, the effect is the same as if the current thread had called (`maximumCount` minus `initialCount`) times. - - If you specify `null` or an empty string for `name`, a local semaphore is created, as if you had called the constructor overload. In this case, `createdNew` is always `true`. - - Because named semaphores are visible throughout the operating system, they can be used to coordinate resource use across process boundaries. - +> The caller has full control over the newly created object even if `semaphoreSecurity` denies or fails to grant some access rights to the current user. However, if the current user attempts to get another object to represent the same named semaphore, using either a constructor or the method, Windows access control security is applied. + + If the named system semaphore does not exist, it is created with the initial count and maximum count specified by `initialCount` and `maximumCount`. If the named system semaphore already exists, `initialCount` and `maximumCount` are not used, although invalid values still cause exceptions. Use the `createdNew` parameter to determine whether the system semaphore was created by this constructor. + + If `initialCount` is less than `maximumCount`, and `createdNew` is `true`, the effect is the same as if the current thread had called (`maximumCount` minus `initialCount`) times. + + If you specify `null` or an empty string for `name`, a local semaphore is created, as if you had called the constructor overload. In this case, `createdNew` is always `true`. + + Because named semaphores are visible throughout the operating system, they can be used to coordinate resource use across process boundaries. + > [!CAUTION] > By default, a named semaphore is not restricted to the user that created it. Other users may be able to open and use the semaphore, including interfering with the semaphore by acquiring the semaphore multiple times and not releasing it. To restrict access to specific users, you can pass in a when creating the named semaphore. Avoid using named semaphores without access restrictions on systems that might have untrusted users running code. - - - -## Examples - The following code example demonstrates the cross-process behavior of a named semaphore with access control security. The example uses the method overload to test for the existence of a named semaphore. If the semaphore does not exist, it is created with a maximum count of two and with access control security that denies the current user the right to use the semaphore but grants the right to read and change permissions on the semaphore. If you run the compiled example from two command windows, the second copy will throw an access violation exception on the call to the method. The exception is caught, and the example uses the method overload to open the semaphore with the rights needed to read and change the permissions. - - After the permissions are changed, the semaphore is opened with the rights required to enter and release. If you run the compiled example from a third command window, it runs using the new permissions. - + + + +## Examples + The following code example demonstrates the cross-process behavior of a named semaphore with access control security. The example uses the method overload to test for the existence of a named semaphore. If the semaphore does not exist, it is created with a maximum count of two and with access control security that denies the current user the right to use the semaphore but grants the right to read and change permissions on the semaphore. If you run the compiled example from two command windows, the second copy will throw an access violation exception on the call to the method. The exception is caught, and the example uses the method overload to open the semaphore with the rights needed to read and change the permissions. + + After the permissions are changed, the semaphore is opened with the rights required to enter and release. If you run the compiled example from a third command window, it runs using the new permissions. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.Semaphore.ctor named 5a/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/Semaphore/.ctor/source2.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.Semaphore.ctor named 5a/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.Semaphore.ctor named 5a/VB/source.vb" id="Snippet1"::: + ]]> @@ -490,10 +490,10 @@ There was some other error. The `HResult` property may provide more information. .NET Framework only: is longer than MAX_PATH (260 characters). - is less than 1. - - -or- - + is less than 1. + + -or- + is less than 0. The named semaphore exists and has access control security, and the user does not have . @@ -536,36 +536,36 @@ There was some other error. The `HResult` property may provide more information. Gets the access control security for a named system semaphore. A object that represents the access control security for the named system semaphore. - method uses the following combination of flags (combined using the bitwise OR operation) to search for permissions: , , and . - - The user must have rights to call this method, and the semaphore must have been opened with rights. - - On a local semaphore, access control security is irrelevant. If the object does not represent a named system semaphore, this method returns a object that grants all rights to any user. - - - -## Examples - The following code example demonstrates the cross-process behavior of a named semaphore with access control security. The example uses the method overload to test for the existence of a named semaphore. - - If the semaphore does not exist, it is created with a maximum count of two and with access control security that denies the current user the right to use the semaphore, but grants the right to read and change permissions on the semaphore. - - If you run the compiled example from two command windows, the second copy will throw an access violation exception on the call to the method. The exception is caught, and the example uses the method overload to open the semaphore with the rights needed to read and change the permissions. The access control security for the system semaphore is obtained using the method. - - After the permissions are changed, the semaphore is opened with the rights required to enter and release. If you run the compiled example from a third command window, it runs using the new permissions. - + method uses the following combination of flags (combined using the bitwise OR operation) to search for permissions: , , and . + + The user must have rights to call this method, and the semaphore must have been opened with rights. + + On a local semaphore, access control security is irrelevant. If the object does not represent a named system semaphore, this method returns a object that grants all rights to any user. + + + +## Examples + The following code example demonstrates the cross-process behavior of a named semaphore with access control security. The example uses the method overload to test for the existence of a named semaphore. + + If the semaphore does not exist, it is created with a maximum count of two and with access control security that denies the current user the right to use the semaphore, but grants the right to read and change permissions on the semaphore. + + If you run the compiled example from two command windows, the second copy will throw an access violation exception on the call to the method. The exception is caught, and the example uses the method overload to open the semaphore with the rights needed to read and change the permissions. The access control security for the system semaphore is obtained using the method. + + After the permissions are changed, the semaphore is opened with the rights required to enter and release. If you run the compiled example from a third command window, it runs using the new permissions. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.Semaphore.ctor named 5a/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/Semaphore/.ctor/source2.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.Semaphore.ctor named 5a/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.Semaphore.ctor named 5a/VB/source.vb" id="Snippet1"::: + ]]> - The current object represents a named system semaphore, and the user does not have rights. - - -or- - + The current object represents a named system semaphore, and the user does not have rights. + + -or- + The current object represents a named system semaphore and was not opened with rights. Managed Threading Semaphore @@ -635,36 +635,36 @@ There was some other error. The `HResult` property may provide more information. Opens the specified named semaphore, if it already exists. An object that represents the named system semaphore. - method tries to open the specified named semaphore. To create the system semaphore when it does not already exist, use one of the constructors that has a `name` parameter. - - Multiple calls to this method that use the same value for `name` do not necessarily return the same object, even though the objects that are returned represent the same named system semaphore. - - This method overload is equivalent to calling the method overload and specifying and rights, combined by using the bitwise OR operation. - - Specifying the flag allows a thread to enter the semaphore, and specifying the flag allows a thread to call the method. - - - -## Examples - The following code example demonstrates the cross-process behavior of a named semaphore with access control security. The example uses the method overload to test for the existence of a named semaphore. - - If the semaphore does not exist, it is created with a maximum count of two and with access control security that denies the current user the right to use the semaphore, but which grants the right to read and change permissions on the semaphore. - - If you run the compiled example from two command windows, the second copy will throw an access violation exception on the call to the method overload. The exception is caught, and the example uses the method overload to open the semaphore with the rights needed to read and change the permissions. - - After the permissions are changed, the semaphore is opened with the rights required to enter and release it. If you run the compiled example from a third command window, it runs using the new permissions. - + The method tries to open the specified named semaphore. To create the system semaphore when it does not already exist, use one of the constructors that has a `name` parameter. + + Multiple calls to this method that use the same value for `name` do not necessarily return the same object, even though the objects that are returned represent the same named system semaphore. + + This method overload is equivalent to calling the method overload and specifying and rights, combined by using the bitwise OR operation. + + Specifying the flag allows a thread to enter the semaphore, and specifying the flag allows a thread to call the method. + + + +## Examples + The following code example demonstrates the cross-process behavior of a named semaphore with access control security. The example uses the method overload to test for the existence of a named semaphore. + + If the semaphore does not exist, it is created with a maximum count of two and with access control security that denies the current user the right to use the semaphore, but which grants the right to read and change permissions on the semaphore. + + If you run the compiled example from two command windows, the second copy will throw an access violation exception on the call to the method overload. The exception is caught, and the example uses the method overload to open the semaphore with the rights needed to read and change the permissions. + + After the permissions are changed, the semaphore is opened with the rights required to enter and release it. If you run the compiled example from a third command window, it runs using the new permissions. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.Semaphore.ctor named 5a/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/Semaphore/.ctor/source2.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.Semaphore.ctor named 5a/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.Semaphore.ctor named 5a/VB/source.vb" id="Snippet1"::: + ]]> @@ -711,8 +711,8 @@ There was some other error. The `HResult` property may provide more information. System.Threading.Semaphore - - + + The name of the synchronization object to be shared with other processes. The name is case-sensitive. The backslash character (\\) is reserved and may only be used to specify a namespace. For more information on namespaces, see the remarks section. There may be further restrictions on the name depending on the operating system. For example, on Unix-based operating systems, the name after excluding the namespace must be a valid file name. @@ -720,34 +720,34 @@ There was some other error. The `HResult` property may provide more information. Opens the specified named semaphore, if it already exists, with the desired security access. An object that represents the named system semaphore. - flag to allow threads to enter the semaphore, and the flag to allow threads to call the method. - - The method tries to open an existing named semaphore. To create the system semaphore when it does not already exist, use one of the constructors that has a `name` parameter. - - Multiple calls to this method that use the same value for `name` do not necessarily return the same object, even though the objects that are returned represent the same named system semaphore. - - - -## Examples - The following code example demonstrates the cross-process behavior of a named semaphore with access control security. The example uses the method overload to test for the existence of a named semaphore. - - If the semaphore does not exist, it is created with a maximum count of two and with access control security that denies the current user the right to use the semaphore, but grants the right to read and change permissions on the semaphore. - - If you run the compiled example from two command windows, the second copy will throw an access violation exception on the call to the method. The exception is caught, and the example uses the method overload to open the semaphore with the rights needed to read and change the permissions. - - After the permissions are changed, the semaphore is opened with the rights required to enter and release it. If you run the compiled example from a third command window, it runs using the new permissions. - + The `rights` parameter must include the flag to allow threads to enter the semaphore, and the flag to allow threads to call the method. + + The method tries to open an existing named semaphore. To create the system semaphore when it does not already exist, use one of the constructors that has a `name` parameter. + + Multiple calls to this method that use the same value for `name` do not necessarily return the same object, even though the objects that are returned represent the same named system semaphore. + + + +## Examples + The following code example demonstrates the cross-process behavior of a named semaphore with access control security. The example uses the method overload to test for the existence of a named semaphore. + + If the semaphore does not exist, it is created with a maximum count of two and with access control security that denies the current user the right to use the semaphore, but grants the right to read and change permissions on the semaphore. + + If you run the compiled example from two command windows, the second copy will throw an access violation exception on the call to the method. The exception is caught, and the example uses the method overload to open the semaphore with the rights needed to read and change the permissions. + + After the permissions are changed, the semaphore is opened with the rights required to enter and release it. If you run the compiled example from a third command window, it runs using the new permissions. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.Semaphore.ctor named 5a/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/Semaphore/.ctor/source2.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.Semaphore.ctor named 5a/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.Semaphore.ctor named 5a/VB/source.vb" id="Snippet1"::: + ]]> @@ -836,34 +836,34 @@ There was some other error. The `HResult` property may provide more information. Exits the semaphore and returns the previous count. The count on the semaphore before the method was called. - method to enter the semaphore, and they typically use this method overload to exit. - - If a is thrown by the method, it does not necessarily indicate a problem with the calling thread. A programming error in another thread might have caused that thread to exit the semaphore more times than it entered. - - If the current object represents a named system semaphore, the user must have rights and the semaphore must have been opened with rights. - - - -## Examples - The following code example creates a semaphore with a maximum count of three and an initial count of zero. The example starts five threads, which block waiting for the semaphore. The main thread uses the method overload to increase the semaphore count to its maximum, allowing three threads to enter the semaphore. Each thread uses the method to wait for one second, to simulate work, and then calls the method overload to release the semaphore. - - Each time the semaphore is released, the previous semaphore count is displayed. Console messages track semaphore use. The simulated work interval is increased slightly for each thread, to make the output easier to read. - + method to enter the semaphore, and they typically use this method overload to exit. + + If a is thrown by the method, it does not necessarily indicate a problem with the calling thread. A programming error in another thread might have caused that thread to exit the semaphore more times than it entered. + + If the current object represents a named system semaphore, the user must have rights and the semaphore must have been opened with rights. + + + +## Examples + The following code example creates a semaphore with a maximum count of three and an initial count of zero. The example starts five threads, which block waiting for the semaphore. The main thread uses the method overload to increase the semaphore count to its maximum, allowing three threads to enter the semaphore. Each thread uses the method to wait for one second, to simulate work, and then calls the method overload to release the semaphore. + + Each time the semaphore is released, the previous semaphore count is displayed. Console messages track semaphore use. The simulated work interval is increased slightly for each thread, to make the output easier to read. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.Semaphore2/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/Semaphore/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.Semaphore2/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.Semaphore2/VB/source.vb" id="Snippet1"::: + ]]> The semaphore count is already at the maximum value. A Win32 error occurred with a named semaphore. - The current semaphore represents a named system semaphore, but the user does not have . - - -or- - + The current semaphore represents a named system semaphore, but the user does not have . + + -or- + The current semaphore represents a named system semaphore, but it was not opened with . Managed Threading Semaphore @@ -918,36 +918,36 @@ There was some other error. The `HResult` property may provide more information. Exits the semaphore a specified number of times and returns the previous count. The count on the semaphore before the method was called. - is thrown by the method, it does not necessarily indicate a problem with the calling thread. A programming error in another thread might have caused that thread to exit the semaphore more times than it entered. - - If the current object represents a named system semaphore, the user must have rights and the semaphore must have been opened with rights. - - - -## Examples - The following code example creates a semaphore with a maximum count of three and an initial count of zero. The example starts five threads, which block waiting for the semaphore. The main thread uses the method overload to increase the semaphore count to its maximum, allowing three threads to enter the semaphore. Each thread uses the method to wait for one second, to simulate work, and then calls the method overload to release the semaphore. - - Each time the semaphore is released, the previous semaphore count is displayed. Console messages track semaphore use. The simulated work interval is increased slightly for each thread, to make the output easier to read. - + is thrown by the method, it does not necessarily indicate a problem with the calling thread. A programming error in another thread might have caused that thread to exit the semaphore more times than it entered. + + If the current object represents a named system semaphore, the user must have rights and the semaphore must have been opened with rights. + + + +## Examples + The following code example creates a semaphore with a maximum count of three and an initial count of zero. The example starts five threads, which block waiting for the semaphore. The main thread uses the method overload to increase the semaphore count to its maximum, allowing three threads to enter the semaphore. Each thread uses the method to wait for one second, to simulate work, and then calls the method overload to release the semaphore. + + Each time the semaphore is released, the previous semaphore count is displayed. Console messages track semaphore use. The simulated work interval is increased slightly for each thread, to make the output easier to read. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.Semaphore2/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/Semaphore/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.Semaphore2/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.Semaphore2/VB/source.vb" id="Snippet1"::: + ]]> is less than 1. The semaphore count is already at the maximum value. A Win32 error occurred with a named semaphore. - The current semaphore represents a named system semaphore, but the user does not have rights. - - -or- - + The current semaphore represents a named system semaphore, but the user does not have rights. + + -or- + The current semaphore represents a named system semaphore, but it was not opened with rights. Managed Threading Semaphore @@ -976,42 +976,42 @@ There was some other error. The `HResult` property may provide more information. System.Void - + A object that represents the access control security to be applied to the named system semaphore. Sets the access control security for a named system semaphore. - objects that represent named system semaphores. - - The user must have rights to call this method, and the semaphore must have been opened with rights. - - - -## Examples - The following code example demonstrates the cross-process behavior of a named semaphore with access control security. The example uses the method overload to test for the existence of a named semaphore. - - If the semaphore does not exist, it is created with a maximum count of two and with access control security that denies the current user the right to use the semaphore but grants the right to read and change permissions on the semaphore. - - If you run the compiled example from two command windows, the second copy will throw an access violation exception on the call to the method. The exception is caught, and the example uses the method overload to open the semaphore with the rights needed to read and change the permissions. - - After the permissions are changed, using the method, the semaphore is opened with the rights required to enter and release. If you run the compiled example from a third command window, it runs using the new permissions. - + objects that represent named system semaphores. + + The user must have rights to call this method, and the semaphore must have been opened with rights. + + + +## Examples + The following code example demonstrates the cross-process behavior of a named semaphore with access control security. The example uses the method overload to test for the existence of a named semaphore. + + If the semaphore does not exist, it is created with a maximum count of two and with access control security that denies the current user the right to use the semaphore but grants the right to read and change permissions on the semaphore. + + If you run the compiled example from two command windows, the second copy will throw an access violation exception on the call to the method. The exception is caught, and the example uses the method overload to open the semaphore with the rights needed to read and change the permissions. + + After the permissions are changed, using the method, the semaphore is opened with the rights required to enter and release. If you run the compiled example from a third command window, it runs using the new permissions. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.Semaphore.ctor named 5a/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/Semaphore/.ctor/source2.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.Semaphore.ctor named 5a/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.Semaphore.ctor named 5a/VB/source.vb" id="Snippet1"::: + ]]> is . - The user does not have rights. - - -or- - + The user does not have rights. + + -or- + The semaphore was not opened with rights. The current object does not represent a named system semaphore. Managed Threading @@ -1092,19 +1092,19 @@ There was some other error. The `HResult` property may provide more information. if the named semaphore was opened successfully; otherwise, . In some cases, may be returned for invalid names. - constructors that has a `name` parameter. - - If you are uncertain whether a named semaphore exists, use this method overload instead of the method overload, which throws an exception if the semaphore does not exist. - - This method overload is equivalent to calling the method overload and specifying and rights, combined by using the bitwise OR operation. Specifying the flag allows a thread to enter the semaphore, and specifying the flag allows a thread to call the method. - + To create the system semaphore when it does not already exist, use one of the constructors that has a `name` parameter. + + If you are uncertain whether a named semaphore exists, use this method overload instead of the method overload, which throws an exception if the semaphore does not exist. + + This method overload is equivalent to calling the method overload and specifying and rights, combined by using the bitwise OR operation. Specifying the flag allows a thread to enter the semaphore, and specifying the flag allows a thread to call the method. + ]]> @@ -1147,9 +1147,9 @@ There was some other error. The `HResult` property may provide more information. System.Boolean - - - + + + The name of the synchronization object to be shared with other processes. The name is case-sensitive. The backslash character (\\) is reserved and may only be used to specify a namespace. For more information on namespaces, see the remarks section. There may be further restrictions on the name depending on the operating system. For example, on Unix-based operating systems, the name after excluding the namespace must be a valid file name. @@ -1159,21 +1159,21 @@ There was some other error. The `HResult` property may provide more information. if the named semaphore was opened successfully; otherwise, . In some cases, may be returned for invalid names. - constructors that has a `name` parameter. - - If you are uncertain whether a named semaphore exists, use this method overload instead of the method overload, which throws an exception if the semaphore does not exist. - - The `rights` parameter must include the flag to allow threads to enter the semaphore, and the flag to allow threads to call the method. - - Multiple calls to this method that use the same value for `name` do not necessarily return the same object, even though the objects that are returned represent the same named system semaphore. - + To create the system semaphore when it does not already exist, use one of the constructors that has a `name` parameter. + + If you are uncertain whether a named semaphore exists, use this method overload instead of the method overload, which throws an exception if the semaphore does not exist. + + The `rights` parameter must include the flag to allow threads to enter the semaphore, and the flag to allow threads to call the method. + + Multiple calls to this method that use the same value for `name` do not necessarily return the same object, even though the objects that are returned represent the same named system semaphore. + ]]> diff --git a/xml/System.Threading/SemaphoreFullException.xml b/xml/System.Threading/SemaphoreFullException.xml index fcc10ed62a4..8044f94fddd 100644 --- a/xml/System.Threading/SemaphoreFullException.xml +++ b/xml/System.Threading/SemaphoreFullException.xml @@ -78,27 +78,27 @@ The exception that is thrown when the method is called on a semaphore whose count is already at the maximum. - method at this point, a is thrown. - + method at this point, a is thrown. + > [!NOTE] -> The class does not enforce thread identity on calls to the and methods. It is not necessary for the same thread that called to call . - - does not necessarily indicate a problem with the code where the exception occurred. Consider the following scenario: Thread A and thread B enter a semaphore that has a maximum count of two. A programming error in thread B causes it to call twice, so that the count on the semaphore is full. As a result, when thread A eventually calls , a is thrown. - - For a list of initial property values for an instance of the class, see the constructor. - - - -## Examples - The following code example shows how a programming error in one thread can lead to a in another thread: Two threads enter a semaphore. The second thread releases the semaphore twice, while the first thread is still executing its task. When the first thread finishes and releases the semaphore, the semaphore count is already full and an exception is thrown. - +> The class does not enforce thread identity on calls to the and methods. It is not necessary for the same thread that called to call . + + does not necessarily indicate a problem with the code where the exception occurred. Consider the following scenario: Thread A and thread B enter a semaphore that has a maximum count of two. A programming error in thread B causes it to call twice, so that the count on the semaphore is full. As a result, when thread A eventually calls , a is thrown. + + For a list of initial property values for an instance of the class, see the constructor. + + + +## Examples + The following code example shows how a programming error in one thread can lead to a in another thread: Two threads enter a semaphore. The second thread releases the semaphore twice, while the first thread is still executing its task. When the first thread finishes and releases the semaphore, the semaphore count is already full and an exception is thrown. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.SemaphoreFullException/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/SemaphoreFullException/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.SemaphoreFullException/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.SemaphoreFullException/VB/source.vb" id="Snippet1"::: + ]]> @@ -154,18 +154,18 @@ Initializes a new instance of the class with default values. - property of the new instance to a system-supplied message that describes the error, such as "Adding the given count to the semaphore would cause it to exceed its maximum count." This message takes into account the current system culture. - - The following table shows the initial property values for an instance of the class. - -|Property|Value| -|--------------|-----------| -||`null`.| -||The system-supplied error message string.| - + property of the new instance to a system-supplied message that describes the error, such as "Adding the given count to the semaphore would cause it to exceed its maximum count." This message takes into account the current system culture. + + The following table shows the initial property values for an instance of the class. + +|Property|Value| +|--------------|-----------| +||`null`.| +||The system-supplied error message string.| + ]]> @@ -215,18 +215,18 @@ The error message that explains the reason for the exception. Initializes a new instance of the class with a specified error message. - class initialized with this constructor. - -|Property|Value| -|--------------|-----------| -||`null`.| -||`message`.| - + class initialized with this constructor. + +|Property|Value| +|--------------|-----------| +||`null`.| +||`message`.| + ]]> @@ -281,19 +281,19 @@ - - + + The object that holds the serialized object data about the exception being thrown. The object that contains contextual information about the source or destination. Initializes a new instance of the class with serialized data. - @@ -345,11 +345,11 @@ The exception that is the cause of the current exception. If the parameter is not , the current exception is raised in a block that handles the inner exception. Initializes a new instance of the class with a specified error message and a reference to the inner exception that is the cause of this exception. - property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. - + property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. + ]]> diff --git a/xml/System.Threading/SynchronizationContext.xml b/xml/System.Threading/SynchronizationContext.xml index 4e5eaff55ba..90b80e17a49 100644 --- a/xml/System.Threading/SynchronizationContext.xml +++ b/xml/System.Threading/SynchronizationContext.xml @@ -54,17 +54,17 @@ Provides the basic functionality for propagating a synchronization context in various synchronization models. - class is a base class that provides a free-threaded context with no synchronization. - - The purpose of the synchronization model implemented by this class is to allow the internal asynchronous/synchronous operations of the common language runtime to behave properly with different synchronization models. This model also simplifies some of the requirements that managed applications have had to follow in order to work correctly under different synchronization environments. - - Providers of synchronization models can extend this class and provide their own implementations for these methods. - - For more information about synchronization contexts, see the article [It's All About the SynchronizationContext](https://docs.microsoft.com/archive/msdn-magazine/2011/february/msdn-magazine-parallel-computing-it-s-all-about-the-synchronizationcontext) in the MSDN Magazine. - + class is a base class that provides a free-threaded context with no synchronization. + + The purpose of the synchronization model implemented by this class is to allow the internal asynchronous/synchronous operations of the common language runtime to behave properly with different synchronization models. This model also simplifies some of the requirements that managed applications have had to follow in order to work correctly under different synchronization environments. + + Providers of synchronization models can extend this class and provide their own implementations for these methods. + + For more information about synchronization contexts, see the article [It's All About the SynchronizationContext](https://docs.microsoft.com/archive/msdn-magazine/2011/february/msdn-magazine-parallel-computing-it-s-all-about-the-synchronizationcontext) in the MSDN Magazine. + ]]> @@ -104,11 +104,11 @@ Creates a new instance of the class. - @@ -153,11 +153,11 @@ When overridden in a derived class, creates a copy of the synchronization context. A new object. - object. - + object. + ]]> @@ -216,11 +216,11 @@ Gets the synchronization context for the current thread. A object representing the current synchronization context. - @@ -305,11 +305,11 @@ When overridden in a derived class, responds to the notification that an operation has completed. - @@ -353,11 +353,11 @@ When overridden in a derived class, responds to the notification that an operation has started. - @@ -414,11 +414,11 @@ The object passed to the delegate. When overridden in a derived class, dispatches an asynchronous message to a synchronization context. - method starts an asynchronous request to post a message. - + method starts an asynchronous request to post a message. + ]]> @@ -475,11 +475,11 @@ The object passed to the delegate. When overridden in a derived class, dispatches a synchronous message to a synchronization context. - method starts a synchronous request to send a message. - + method starts a synchronous request to send a message. + ]]> The method was called in a Windows Store app. The implementation of for Windows Store apps does not support the method. @@ -637,9 +637,9 @@ System.Int32 - - - + + + An array of type that contains the native operating system handles. @@ -649,11 +649,11 @@ Waits for any or all the elements in the specified array to receive a signal. The array index of the object that satisfied the wait. - method calls the external declaration to perform the wait activity. Override the method to change the wait behavior for the synchronization context. - + method calls the external declaration to perform the wait activity. Override the method to change the wait behavior for the synchronization context. + ]]> @@ -713,9 +713,9 @@ System.Int32 - - - + + + An array of type that contains the native operating system handles. @@ -725,11 +725,11 @@ Helper function that waits for any or all the elements in the specified array to receive a signal. The array index of the object that satisfied the wait. - is a declaration for an unmanaged external helper function. is called by the method to wait for a signal for the specified operating system handles. - + is a declaration for an unmanaged external helper function. is called by the method to wait for a signal for the specified operating system handles. + ]]> diff --git a/xml/System.Threading/SynchronizationLockException.xml b/xml/System.Threading/SynchronizationLockException.xml index 7363bb45869..dbe4946b47a 100644 --- a/xml/System.Threading/SynchronizationLockException.xml +++ b/xml/System.Threading/SynchronizationLockException.xml @@ -70,15 +70,15 @@ The exception that is thrown when a method requires the caller to own the lock on a given Monitor, and the method is invoked by a caller that does not own that lock. - is thrown by calling the , , , and methods of the class from an unsynchronized block of code. - - uses the HRESULT COR_E_SYNCHRONIZATIONLOCK, which has the value 0x80131518. - - For a list of initial property values for an instance of , see the constructors. - + is thrown by calling the , , , and methods of the class from an unsynchronized block of code. + + uses the HRESULT COR_E_SYNCHRONIZATIONLOCK, which has the value 0x80131518. + + For a list of initial property values for an instance of , see the constructors. + ]]> @@ -133,16 +133,16 @@ Initializes a new instance of the class with default properties. - . - -|Property|Value| -|--------------|-----------| -||`null`.| -||The localized error message string.| - + . + +|Property|Value| +|--------------|-----------| +||`null`.| +||The localized error message string.| + ]]> @@ -188,16 +188,16 @@ The error message that explains the reason for the exception. Initializes a new instance of the class with a specified error message. - . - -|Property|Value| -|--------------|-----------| -||`null`.| -||The error message string.| - + . + +|Property|Value| +|--------------|-----------| +||`null`.| +||The error message string.| + ]]> @@ -252,19 +252,19 @@ - - + + The that holds the serialized object data about the exception being thrown. The that contains contextual information about the source or destination. Initializes a new instance of the class with serialized data. - XML and SOAP Serialization @@ -313,18 +313,18 @@ The exception that is the cause of the current exception. If the parameter is not , the current exception is raised in a block that handles the inner exception. Initializes a new instance of the class with a specified error message and a reference to the inner exception that is the cause of this exception. - property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||The inner exception reference.| -||The error message string.| - + property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||The inner exception reference.| +||The error message string.| + ]]> diff --git a/xml/System.Threading/Thread.xml b/xml/System.Threading/Thread.xml index 8264a2f9522..3fc00149597 100644 --- a/xml/System.Threading/Thread.xml +++ b/xml/System.Threading/Thread.xml @@ -3879,11 +3879,11 @@ When you call the `Suspend` method on a thread, the system notes that a thread s System.Void - - - - - + + + + + Reserved for future use. Must be IID_NULL. @@ -3930,9 +3930,9 @@ When you call the `Suspend` method on a thread, the system notes that a thread s System.Void - - - + + + The type information to return. @@ -3977,7 +3977,7 @@ When you call the `Suspend` method on a thread, the system notes that a thread s System.Void - + Points to a location that receives the number of type information interfaces provided by the object. @@ -4020,14 +4020,14 @@ When you call the `Suspend` method on a thread, the system notes that a thread s System.Void - - - - - - - - + + + + + + + + Identifies the member. diff --git a/xml/System.Threading/Timer.xml b/xml/System.Threading/Timer.xml index fb541a40115..b157f48a522 100644 --- a/xml/System.Threading/Timer.xml +++ b/xml/System.Threading/Timer.xml @@ -92,66 +92,66 @@ Provides a mechanism for executing a method on a thread pool thread at specified intervals. This class cannot be inherited. - delegate to specify the method you want the to execute. The signature of the delegate is: - -```csharp -void TimerCallback(Object state) -``` - -```cpp -void TimerCallback(Object state) -``` - -```vb -Sub TimerCallback(state As Object) -``` - - The timer delegate is specified when the timer is constructed, and cannot be changed. The method does not execute on the thread that created the timer; it executes on a thread supplied by the system. - + delegate to specify the method you want the to execute. The signature of the delegate is: + +```csharp +void TimerCallback(Object state) +``` + +```cpp +void TimerCallback(Object state) +``` + +```vb +Sub TimerCallback(state As Object) +``` + + The timer delegate is specified when the timer is constructed, and cannot be changed. The method does not execute on the thread that created the timer; it executes on a thread supplied by the system. + > [!TIP] -> .NET includes several timer classes, each of which offers different functionality: +> .NET includes several timer classes, each of which offers different functionality: > > - , which fires an event and executes the code in one or more event sinks at regular intervals. The class is intended for use as a server-based or service component in a multithreaded environment; it has no user interface and is not visible at runtime. > - , which executes a single callback method on a thread pool thread at regular intervals. The callback method is defined when the timer is instantiated and cannot be changed. Like the class, this class is intended for use as a server-based or service component in a multithreaded environment; it has no user interface and is not visible at runtime. > - , a Windows Forms component that fires an event and executes the code in one or more event sinks at regular intervals. The component has no user interface and is designed for use in a single-threaded environment; it executes on the UI thread. > - (.NET Framework only), an ASP.NET component that performs asynchronous or synchronous web page postbacks at a regular interval. > - , a timer that's integrated into the `Dispatcher` queue. This timer is processed with a specified priority at a specified time interval. - - When you create a timer, you can specify an amount of time to wait before the first execution of the method (due time), and an amount of time to wait between subsequent executions (period). The class has the same resolution as the system clock. This means that if the period is less than the resolution of the system clock, the delegate will execute at intervals defined by the resolution of the system clock, which is approximately 15 milliseconds on Windows 7 and Windows 8 systems. You can change the due time and period, or disable the timer, by using the method. - + + When you create a timer, you can specify an amount of time to wait before the first execution of the method (due time), and an amount of time to wait between subsequent executions (period). The class has the same resolution as the system clock. This means that if the period is less than the resolution of the system clock, the delegate will execute at intervals defined by the resolution of the system clock, which is approximately 15 milliseconds on Windows 7 and Windows 8 systems. You can change the due time and period, or disable the timer, by using the method. + > [!NOTE] -> As long as you are using a , you must keep a reference to it. As with any managed object, a is subject to garbage collection when there are no references to it. The fact that a is still active does not prevent it from being collected. +> As long as you are using a , you must keep a reference to it. As with any managed object, a is subject to garbage collection when there are no references to it. The fact that a is still active does not prevent it from being collected. > [!NOTE] > The system clock that is used is the same clock used by [GetTickCount](/windows/win32/api/sysinfoapi/nf-sysinfoapi-gettickcount), which is not affected by changes made with [timeBeginPeriod](/windows/win32/api/timeapi/nf-timeapi-timebeginperiod) and [timeEndPeriod](/windows/win32/api/timeapi/nf-timeapi-timeendperiod). - - When a timer is no longer needed, use the method to free the resources held by the timer. Note that callbacks can occur after the method overload has been called, because the timer queues callbacks for execution by thread pool threads. You can use the method overload to wait until all callbacks have completed. - - The callback method executed by the timer should be reentrant, because it is called on threads. The callback can be executed simultaneously on two thread pool threads if the timer interval is less than the time required to execute the callback, or if all thread pool threads are in use and the callback is queued multiple times. - + + When a timer is no longer needed, use the method to free the resources held by the timer. Note that callbacks can occur after the method overload has been called, because the timer queues callbacks for execution by thread pool threads. You can use the method overload to wait until all callbacks have completed. + + The callback method executed by the timer should be reentrant, because it is called on threads. The callback can be executed simultaneously on two thread pool threads if the timer interval is less than the time required to execute the callback, or if all thread pool threads are in use and the callback is queued multiple times. + > [!NOTE] -> is a simple, lightweight timer that uses callback methods and is served by thread pool threads. It is not recommended for use with Windows Forms, because its callbacks do not occur on the user interface thread. is a better choice for use with Windows Forms. For server-based timer functionality, you might consider using , which raises events and has additional features. - - - -## Examples - The following example defines a `StatusChecker` class that includes a `CheckStatus` method whose signature is the same as the delegate. The `state` argument of the `CheckStatus` method is an object that is used to synchronize the application thread and the thread pool thread that executes the callback delegate. The `StatusChecker` class also includes two state variables: - - `invokeCount` - Indicates the number of times the callback method has been invoked. - - `maxCount` - Determines the maximum number of times the callback method should be invoked. - - The application thread creates the timer, which waits one second and then executes the `CheckStatus` callback method every 250 milliseconds. The application thread then blocks until the object is signaled. When the `CheckStatus` callback method executes `maxCount` times, it calls the `AutoResetEvent.Set` method to set the state of the object to signaled. The first time this happens, the application thread calls the method so that the callback method now executes every half second. It once again blocks until the object is signaled. When this happens, the timer is destroyed by calling its method, and the application terminates. - +> is a simple, lightweight timer that uses callback methods and is served by thread pool threads. It is not recommended for use with Windows Forms, because its callbacks do not occur on the user interface thread. is a better choice for use with Windows Forms. For server-based timer functionality, you might consider using , which raises events and has additional features. + + + +## Examples + The following example defines a `StatusChecker` class that includes a `CheckStatus` method whose signature is the same as the delegate. The `state` argument of the `CheckStatus` method is an object that is used to synchronize the application thread and the thread pool thread that executes the callback delegate. The `StatusChecker` class also includes two state variables: + + `invokeCount` + Indicates the number of times the callback method has been invoked. + + `maxCount` + Determines the maximum number of times the callback method should be invoked. + + The application thread creates the timer, which waits one second and then executes the `CheckStatus` callback method every 250 milliseconds. The application thread then blocks until the object is signaled. When the `CheckStatus` callback method executes `maxCount` times, it calls the `AutoResetEvent.Set` method to set the state of the object to signaled. The first time this happens, the application thread calls the method so that the callback method now executes every half second. It once again blocks until the object is signaled. When this happens, the timer is destroyed by calling its method, and the application terminates. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.Timer/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/Timer/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.Timer/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.Timer/VB/source.vb" id="Snippet1"::: + ]]> This type is thread safe. @@ -210,29 +210,29 @@ Sub TimerCallback(state As Object) - + A delegate representing a method to be executed. Initializes a new instance of the class with an infinite period and an infinite due time, using the newly created object as the state object. - object itself as the state object. After creating the timer, use the method to set the interval and due time. - - This constructor specifies an infinite due time before the first callback and an infinite interval between callbacks, in order to prevent the first callback from occurring before the object is assigned to the state object. - - The method specified for `callback` should be reentrant, because it is called on threads. The method can be executed simultaneously on two thread pool threads if the timer interval is less than the time required to execute the method, or if all thread pool threads are in use and the method is queued multiple times. - - - -## Examples - The following code example creates a new timer, using the timer itself as the state object. The method is used to start the timer. When the timer callback occurs, the state object is used to turn the timer off. - + object itself as the state object. After creating the timer, use the method to set the interval and due time. + + This constructor specifies an infinite due time before the first callback and an infinite interval between callbacks, in order to prevent the first callback from occurring before the object is assigned to the state object. + + The method specified for `callback` should be reentrant, because it is called on threads. The method can be executed simultaneously on two thread pool threads if the timer interval is less than the time required to execute the method, or if all thread pool threads are in use and the method is queued multiple times. + + + +## Examples + The following code example creates a new timer, using the timer itself as the state object. The method is used to start the timer. When the timer callback occurs, the state object is used to turn the timer off. + :::code language="csharp" source="~/snippets/csharp/System.Threading/Timer/.ctor/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/timerSelfCtor/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/timerSelfCtor/VB/source.vb" id="Snippet1"::: + ]]> @@ -299,29 +299,29 @@ Sub TimerCallback(state As Object) The time interval between invocations of , in milliseconds. Specify to disable periodic signaling. Initializes a new instance of the class, using a 32-bit signed integer to specify the time interval. - , `callback` is not invoked; the timer is disabled, but can be re-enabled by calling the method. - - Because the class has the same resolution as the system clock, which is approximately 15 milliseconds on Windows 7 and Windows 8 systems, the `callback` delegate executes at intervals defined by the resolution of the system clock if `period` is less than the resolution of the system clock. If `period` is zero (0) or and `dueTime` is not , `callback` is invoked once; the periodic behavior of the timer is disabled, but can be re-enabled using the method. + , `callback` is not invoked; the timer is disabled, but can be re-enabled by calling the method. + + Because the class has the same resolution as the system clock, which is approximately 15 milliseconds on Windows 7 and Windows 8 systems, the `callback` delegate executes at intervals defined by the resolution of the system clock if `period` is less than the resolution of the system clock. If `period` is zero (0) or and `dueTime` is not , `callback` is invoked once; the periodic behavior of the timer is disabled, but can be re-enabled using the method. > [!NOTE] > The system clock that is used is the same clock used by [GetTickCount](/windows/win32/api/sysinfoapi/nf-sysinfoapi-gettickcount), which is not affected by changes made with [timeBeginPeriod](/windows/win32/api/timeapi/nf-timeapi-timebeginperiod) and [timeEndPeriod](/windows/win32/api/timeapi/nf-timeapi-timeendperiod). - - The method specified for `callback` should be reentrant, because it is called on threads. The method can be executed simultaneously on two thread pool threads if the timer interval is less than the time required to execute the method, or if all thread pool threads are in use and the method is queued multiple times. - - - -## Examples - The following code example shows how to create a `TimerCallback` delegate and initialize a new instance of the `Timer` class. - + + The method specified for `callback` should be reentrant, because it is called on threads. The method can be executed simultaneously on two thread pool threads if the timer interval is less than the time required to execute the method, or if all thread pool threads are in use and the method is queued multiple times. + + + +## Examples + The following code example shows how to create a `TimerCallback` delegate and initialize a new instance of the `Timer` class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.Timer/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/Timer/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.Timer/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.Timer/VB/source.vb" id="Snippet1"::: + ]]> The or parameter is negative and is not equal to . @@ -371,8 +371,8 @@ Sub TimerCallback(state As Object) - - + + [System.Runtime.CompilerServices.Nullable(2)] @@ -380,8 +380,8 @@ Sub TimerCallback(state As Object) - - + + A delegate representing a method to be executed. @@ -390,20 +390,20 @@ Sub TimerCallback(state As Object) The time interval between invocations of , in milliseconds. Specify to disable periodic signaling. Initializes a new instance of the class, using 64-bit signed integers to measure time intervals. - , `callback` is not invoked; the timer is disabled, but can be re-enabled by calling the method. - - Because the class has the same resolution as the system clock, which is approximately 15 milliseconds on Windows 7 and Windows 8 systems, the `callback` delegate executes at intervals defined by the resolution of the system clock if `period` is less than the resolution of the system clock. If `period` is zero (0) or and `dueTime` is not , `callback` is invoked once; the periodic behavior of the timer is disabled, but can be re-enabled using the method. + , `callback` is not invoked; the timer is disabled, but can be re-enabled by calling the method. + + Because the class has the same resolution as the system clock, which is approximately 15 milliseconds on Windows 7 and Windows 8 systems, the `callback` delegate executes at intervals defined by the resolution of the system clock if `period` is less than the resolution of the system clock. If `period` is zero (0) or and `dueTime` is not , `callback` is invoked once; the periodic behavior of the timer is disabled, but can be re-enabled using the method. > [!NOTE] > The system clock that is used is the same clock used by [GetTickCount](/windows/win32/api/sysinfoapi/nf-sysinfoapi-gettickcount), which is not affected by changes made with [timeBeginPeriod](/windows/win32/api/timeapi/nf-timeapi-timebeginperiod) and [timeEndPeriod](/windows/win32/api/timeapi/nf-timeapi-timeendperiod). - - The method specified for `callback` should be reentrant, because it is called on threads. The method can be executed simultaneously on two thread pool threads if the timer interval is less than the time required to execute the method, or if all thread pool threads are in use and the method is queued multiple times. - + + The method specified for `callback` should be reentrant, because it is called on threads. The method can be executed simultaneously on two thread pool threads if the timer interval is less than the time required to execute the method, or if all thread pool threads are in use and the method is queued multiple times. + ]]> The or parameter is negative and is not equal to . @@ -473,29 +473,29 @@ Sub TimerCallback(state As Object) The time interval between invocations of . Specify to disable periodic signaling. Initializes a new instance of the class, using values to measure time intervals. - method. - - Because the class has the same resolution as the system clock, which is approximately 15 milliseconds on Windows 7 and Windows 8 systems, the `callback` delegate executes at intervals defined by the resolution of the system clock if `period` is less than the resolution of the system clock. If `period` is zero (0) or negative one (-1) milliseconds and `dueTime` is positive, `callback` is invoked once; the periodic behavior of the timer is disabled, but can be re-enabled using the method. + method. + + Because the class has the same resolution as the system clock, which is approximately 15 milliseconds on Windows 7 and Windows 8 systems, the `callback` delegate executes at intervals defined by the resolution of the system clock if `period` is less than the resolution of the system clock. If `period` is zero (0) or negative one (-1) milliseconds and `dueTime` is positive, `callback` is invoked once; the periodic behavior of the timer is disabled, but can be re-enabled using the method. > [!NOTE] > The system clock that is used is the same clock used by [GetTickCount](/windows/win32/api/sysinfoapi/nf-sysinfoapi-gettickcount), which is not affected by changes made with [timeBeginPeriod](/windows/win32/api/timeapi/nf-timeapi-timebeginperiod) and [timeEndPeriod](/windows/win32/api/timeapi/nf-timeapi-timeendperiod). - - The method specified for `callback` should be reentrant, because it is called on threads. The method can be executed simultaneously on two thread pool threads if the timer interval is less than the time required to execute the method, or if all thread pool threads are in use and the method is queued multiple times. - - - -## Examples - The following code example shows how to create a `TimerCallback` delegate and initialize a new instance of the `Timer` class. - + + The method specified for `callback` should be reentrant, because it is called on threads. The method can be executed simultaneously on two thread pool threads if the timer interval is less than the time required to execute the method, or if all thread pool threads are in use and the method is queued multiple times. + + + +## Examples + The following code example shows how to create a `TimerCallback` delegate and initialize a new instance of the `Timer` class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.Timer2/CPP/source2.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/Timer/.ctor/source2.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.Timer2/VB/source2.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.Timer2/VB/source2.vb" id="Snippet1"::: + ]]> The number of milliseconds in the value of or is negative and not equal to , or is greater than Int32.MaxValue. @@ -549,8 +549,8 @@ Sub TimerCallback(state As Object) - - + + [System.Runtime.CompilerServices.Nullable(2)] @@ -558,8 +558,8 @@ Sub TimerCallback(state As Object) - - + + A delegate representing a method to be executed. @@ -568,20 +568,20 @@ Sub TimerCallback(state As Object) The time interval between invocations of , in milliseconds. Specify to disable periodic signaling. Initializes a new instance of the class, using 32-bit unsigned integers to measure time intervals. - , `callback` is not invoked; the timer is disabled, but can be re-enabled by calling the method. - - Because the class has the same resolution as the system clock, which is approximately 15 milliseconds on Windows 7 and Windows 8 systems, the `callback` delegate executes at intervals defined by the resolution of the system clock if `period` is less than the resolution of the system clock. If `period` is zero (0) or and `dueTime` is not , `callback` is invoked once; the periodic behavior of the timer is disabled, but can be re-enabled using the method. + , `callback` is not invoked; the timer is disabled, but can be re-enabled by calling the method. + + Because the class has the same resolution as the system clock, which is approximately 15 milliseconds on Windows 7 and Windows 8 systems, the `callback` delegate executes at intervals defined by the resolution of the system clock if `period` is less than the resolution of the system clock. If `period` is zero (0) or and `dueTime` is not , `callback` is invoked once; the periodic behavior of the timer is disabled, but can be re-enabled using the method. > [!NOTE] > The system clock that is used is the same clock used by [GetTickCount](/windows/win32/api/sysinfoapi/nf-sysinfoapi-gettickcount), which is not affected by changes made with [timeBeginPeriod](/windows/win32/api/timeapi/nf-timeapi-timebeginperiod) and [timeEndPeriod](/windows/win32/api/timeapi/nf-timeapi-timeendperiod). - - The method specified for `callback` should be reentrant, because it is called on threads. The method can be executed simultaneously on two thread pool threads if the timer interval is less than the time required to execute the method, or if all thread pool threads are in use and the method is queued multiple times. - + + The method specified for `callback` should be reentrant, because it is called on threads. The method can be executed simultaneously on two thread pool threads if the timer interval is less than the time required to execute the method, or if all thread pool threads are in use and the method is queued multiple times. + ]]> The or parameter is negative and is not equal to . @@ -690,26 +690,26 @@ Sub TimerCallback(state As Object) if the timer was successfully updated; otherwise, . - , the callback method is never invoked; the timer is disabled, but can be re-enabled by calling and specifying a positive value for `dueTime`. - - If `period` is zero (0) or , and `dueTime` is not , the callback method is invoked once; the periodic behavior of the timer is disabled, but can be re-enabled by calling and specifying a positive value for `period`. - - The method can be called from the delegate. - - - -## Examples - The following code example demonstrates how to start a `Timer` and, after a set number of invocations, change its period. - + , the callback method is never invoked; the timer is disabled, but can be re-enabled by calling and specifying a positive value for `dueTime`. + + If `period` is zero (0) or , and `dueTime` is not , the callback method is invoked once; the periodic behavior of the timer is disabled, but can be re-enabled by calling and specifying a positive value for `period`. + + The method can be called from the delegate. + + + +## Examples + The following code example demonstrates how to start a `Timer` and, after a set number of invocations, change its period. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.Timer/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/Timer/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.Timer/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.Timer/VB/source.vb" id="Snippet1"::: + ]]> The has already been disposed. @@ -761,8 +761,8 @@ Sub TimerCallback(state As Object) System.Boolean - - + + The amount of time to delay before the invoking the callback method specified when the was constructed, in milliseconds. Specify to prevent the timer from restarting. Specify zero (0) to restart the timer immediately. This value must be less than or equal to 4294967294. @@ -771,23 +771,23 @@ Sub TimerCallback(state As Object) if the timer was successfully updated; otherwise, . - , the callback method is never invoked; the timer is disabled, but can be re-enabled by calling and specifying a positive value for `dueTime`. - - If `period` is zero (0) or , and `dueTime` is not , the callback method is invoked once; the periodic behavior of the timer is disabled, but can be re-enabled by calling and specifying a positive value for `period`. - - The method can be called from the delegate. - + , the callback method is never invoked; the timer is disabled, but can be re-enabled by calling and specifying a positive value for `dueTime`. + + If `period` is zero (0) or , and `dueTime` is not , the callback method is invoked once; the periodic behavior of the timer is disabled, but can be re-enabled by calling and specifying a positive value for `period`. + + The method can be called from the delegate. + ]]> The has already been disposed. or is less than -1. - + -or- or is greater than 4294967294. @@ -849,24 +849,24 @@ Sub TimerCallback(state As Object) if the timer was successfully updated; otherwise, . - , the callback method is invoked immediately. If `dueTime` is , the callback method is never invoked; the timer is disabled, but can be re-enabled by calling and specifying a positive value for `dueTime`. - - If `period` is or , and `dueTime` is positive, the callback method is invoked once; the periodic behavior of the timer is disabled, but can be re-enabled by calling and specifying a value greater than zero for `period`. - + , the callback method is invoked immediately. If `dueTime` is , the callback method is never invoked; the timer is disabled, but can be re-enabled by calling and specifying a positive value for `dueTime`. + + If `period` is or , and `dueTime` is positive, the callback method is invoked once; the periodic behavior of the timer is disabled, but can be re-enabled by calling and specifying a value greater than zero for `period`. + The method can be called from the delegate. - -## Examples - The following code example demonstrates how to start a `Timer` and, after a set number of invocations, change its period. - + +## Examples + The following code example demonstrates how to start a `Timer` and, after a set number of invocations, change its period. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.Timer2/CPP/source2.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/Timer/.ctor/source2.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.Timer2/VB/source2.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.Timer2/VB/source2.vb" id="Snippet1"::: + ]]> The has already been disposed. @@ -923,8 +923,8 @@ Sub TimerCallback(state As Object) System.Boolean - - + + The amount of time to delay before the invoking the callback method specified when the was constructed, in milliseconds. Specify to prevent the timer from restarting. Specify zero (0) to restart the timer immediately. @@ -933,17 +933,17 @@ Sub TimerCallback(state As Object) if the timer was successfully updated; otherwise, . - , the callback method is never invoked; the timer is disabled, but can be re-enabled by calling and specifying a positive value for `dueTime`. - - If `period` is zero (0) or , and `dueTime` is not , the callback method is invoked once; the periodic behavior of the timer is disabled, but can be re-enabled by calling and specifying a positive value for `period`. - - The method can be called from the delegate. - + , the callback method is never invoked; the timer is disabled, but can be re-enabled by calling and specifying a positive value for `dueTime`. + + If `period` is zero (0) or , and `dueTime` is not , the callback method is invoked once; the periodic behavior of the timer is disabled, but can be re-enabled by calling and specifying a positive value for `period`. + + The method can be called from the delegate. + ]]> The has already been disposed. @@ -1005,23 +1005,23 @@ Sub TimerCallback(state As Object) Releases all resources used by the current instance of . - to be reallocated for other purposes. For more information about `Dispose`, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). - + to be reallocated for other purposes. For more information about `Dispose`, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). + > [!NOTE] -> Callbacks can occur after the method overload has been called, because the timer queues callbacks for execution by thread pool threads. You can use the method overload to wait until all callbacks have completed. - - - -## Examples - The following code example shows how to free the resources held by a `Timer`. - +> Callbacks can occur after the method overload has been called, because the timer queues callbacks for execution by thread pool threads. You can use the method overload to wait until all callbacks have completed. + + + +## Examples + The following code example shows how to free the resources held by a `Timer`. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.Timer/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/Timer/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.Timer/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.Timer/VB/source.vb" id="Snippet1"::: + ]]> Timers @@ -1071,7 +1071,7 @@ Sub TimerCallback(state As Object) System.Boolean - + The to be signaled when the has been disposed of. @@ -1079,16 +1079,16 @@ Sub TimerCallback(state As Object) if the function succeeds; otherwise, . - to be reallocated for other purposes. For more information about `Dispose`, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). - - When this method completes, it signals the specified by the `notifyObject` parameter.Use this overload of the method if you want to be able to block until you are certain that the timer has been disposed. The timer is not disposed until all currently queued callbacks have completed. - + to be reallocated for other purposes. For more information about `Dispose`, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). + + When this method completes, it signals the specified by the `notifyObject` parameter.Use this overload of the method if you want to be able to block until you are certain that the timer has been disposed. The timer is not disposed until all currently queued callbacks have completed. + > [!NOTE] -> If the callback uses the method to set the `dueTime` parameter to zero, a race condition can occur when the method overload is called: If the timer queues a new callback before the method overload detects that there are no callbacks queued, continues to block; otherwise, the timer is disposed while the new callback is being queued, and an is thrown when the new callback calls the method. - +> If the callback uses the method to set the `dueTime` parameter to zero, a race condition can occur when the method overload is called: If the timer queues a new callback before the method overload detects that there are no callbacks queued, continues to block; otherwise, the timer is disposed while the new callback is being queued, and an is thrown when the new callback calls the method. + ]]> The parameter is . diff --git a/xml/System.Threading/WaitHandle.xml b/xml/System.Threading/WaitHandle.xml index 341afa93a3a..e9aae011a0d 100644 --- a/xml/System.Threading/WaitHandle.xml +++ b/xml/System.Threading/WaitHandle.xml @@ -629,8 +629,8 @@ Application code does not call this method; it is automatically invoked during g System.Boolean - - + + The to signal. @@ -707,10 +707,10 @@ Application code does not call this method; it is automatically invoked during g System.Boolean - - - - + + + + The to signal. @@ -781,10 +781,10 @@ If `millisecondsTimeout` is zero, the method does not block. It tests the state System.Boolean - - - - + + + + The to signal. @@ -1205,9 +1205,9 @@ Note: In the .NET for System.Boolean - - - + + + A array containing the objects for which the current instance will wait. This array cannot contain multiple references to the same object (duplicates). @@ -1300,9 +1300,9 @@ The method returns when the wait t System.Boolean - - - + + + A array containing the objects for which the current instance will wait. This array cannot contain multiple references to the same object. @@ -1687,9 +1687,9 @@ The maximum value for `timeout` is System.Int32 - - - + + + A array containing the objects for which the current instance will wait. @@ -1779,9 +1779,9 @@ The maximum number of the wait handles is 64, and 63 if the current thread is in System.Int32 - - - + + + A array containing the objects for which the current instance will wait. @@ -2102,8 +2102,8 @@ The maximum value for `timeout` is System.Boolean - - + + The number of milliseconds to wait, or (-1) to wait indefinitely. @@ -2178,8 +2178,8 @@ Override this method to customize the behavior of derived classes. System.Boolean - - + + A that represents the number of milliseconds to wait, or a that represents -1 milliseconds to wait indefinitely. diff --git a/xml/System.Threading/WaitHandleCannotBeOpenedException.xml b/xml/System.Threading/WaitHandleCannotBeOpenedException.xml index 6b4b280b056..a0b2d474c24 100644 --- a/xml/System.Threading/WaitHandleCannotBeOpenedException.xml +++ b/xml/System.Threading/WaitHandleCannotBeOpenedException.xml @@ -69,11 +69,11 @@ The exception that is thrown when an attempt is made to open a system mutex, semaphore, or event wait handle that does not exist. - , , and classes can represent named system synchronization objects. When you use the method, the method, or the method to open a named system object that does not exist, a exception is thrown. - + , , and classes can represent named system synchronization objects. When you use the method, the method, or the method to open a named system object that does not exist, a exception is thrown. + ]]> @@ -126,18 +126,18 @@ Initializes a new instance of the class with default values. - property of the new instance to a system-supplied message that describes the error, such as "No handle of the given name exists." This message takes into account the current system culture. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||`null`.| -||The system-supplied error message string.| - + property of the new instance to a system-supplied message that describes the error, such as "No handle of the given name exists." This message takes into account the current system culture. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||`null`.| +||The system-supplied error message string.| + ]]> @@ -182,18 +182,18 @@ The error message that explains the reason for the exception. Initializes a new instance of the class with a specified error message. - initialized with this constructor. - -|Property|Value| -|--------------|-----------| -||`null`.| -||`message`.| - + initialized with this constructor. + +|Property|Value| +|--------------|-----------| +||`null`.| +||`message`.| + ]]> @@ -247,19 +247,19 @@ - - + + The object that holds the serialized object data about the exception being thrown. The object that contains contextual information about the source or destination. Initializes a new instance of the class with serialized data. - @@ -306,11 +306,11 @@ The exception that is the cause of the current exception. If the parameter is not , the current exception is raised in a block that handles the inner exception. Initializes a new instance of the class with a specified error message and a reference to the inner exception that is the cause of this exception. - property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. - + property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. + ]]> diff --git a/xml/System.Web.Services.Protocols/HttpWebClientProtocol.xml b/xml/System.Web.Services.Protocols/HttpWebClientProtocol.xml index 8b8e43be67e..61712628f07 100644 --- a/xml/System.Web.Services.Protocols/HttpWebClientProtocol.xml +++ b/xml/System.Web.Services.Protocols/HttpWebClientProtocol.xml @@ -25,25 +25,25 @@ Represents the base class for all XML Web service client proxies that use the HTTP transport protocol. - . - - To communicate with an XML Web service using HTTP, you must create a proxy class deriving indirectly or directly from for the XML Web service. Instead of creating the proxy class manually, you can use the Wsdl.exe tool to create a proxy class for a given XML Web service's service description. - - Since HttpWebClientProtocol is the base class for all proxy classes, its properties are on your proxy classes. These properties are useful for controlling the request behavior of the underlying transport. For example, use the property for calling XML Web services through a firewall. Many of these properties are used to initialize the that makes the Web request. - - , , and derive directly or indirectly from to provide support for SOAP, HTTP-GET and HTTP-POST respectively. - - - -## Examples - The following example is an ASP.NET Web Form, which calls an XML Web service named `Math`. Within the `EnterBtn_Click` function, the Web Form allows the server to automatically redirect the client to other sites. It also sets client authentication credentials, proxy settings, the request encoding and the time out for the request before calling the XML Web service method. - + . + + To communicate with an XML Web service using HTTP, you must create a proxy class deriving indirectly or directly from for the XML Web service. Instead of creating the proxy class manually, you can use the Wsdl.exe tool to create a proxy class for a given XML Web service's service description. + + Since HttpWebClientProtocol is the base class for all proxy classes, its properties are on your proxy classes. These properties are useful for controlling the request behavior of the underlying transport. For example, use the property for calling XML Web services through a firewall. Many of these properties are used to initialize the that makes the Web request. + + , , and derive directly or indirectly from to provide support for SOAP, HTTP-GET and HTTP-POST respectively. + + + +## Examples + The following example is an ASP.NET Web Form, which calls an XML Web service named `Math`. Within the `EnterBtn_Click` function, the Web Form allows the server to automatically redirect the client to other sites. It also sets client authentication credentials, proxy settings, the request encoding and the time out for the request before calling the XML Web service method. + [!code-aspx-csharp[Classic HttpWebClientProtocol Example#1](~/snippets/csharp/System.Web.Services.Protocols/HttpWebClientProtocol/Overview/sourcecs.aspx#1)] - [!code-aspx-vb[Classic HttpWebClientProtocol Example#1](~/snippets/visualbasic/VS_Snippets_Remoting/Classic HttpWebClientProtocol Example/VB/sourcevb.aspx#1)] - + [!code-aspx-vb[Classic HttpWebClientProtocol Example#1](~/snippets/visualbasic/VS_Snippets_Remoting/Classic HttpWebClientProtocol Example/VB/sourcevb.aspx#1)] + ]]> The properties on this class are copied into a new instance of a object for each XML Web service method call. While you can call XML Web service methods on the same instance from different threads at the same time, there is no synchronization done to ensure that a consistent snapshot of the properties gets transferred to the object. Therefore, if you need to modify the properties and make concurrent method calls from different threads you should use a different instance of the XML Web service proxy or provide your own synchronization. @@ -101,13 +101,13 @@ to automatically redirect the client to follow server redirects; otherwise, . The default is . - is thrown if the property is `false` and the Web server attempts to redirect the request. The property contains an object, where both the and properties reflect details regarding the attempted redirect. The property contains an equivalent to one of the HTTP redirect status codes (301, 302, and 307) and the `Location` header within the collection points to the URI that the request attempted to be redirected to. - + is thrown if the property is `false` and the Web server attempts to redirect the request. The property contains an object, where both the and properties reflect details regarding the attempted redirect. The property contains an equivalent to one of the HTTP redirect status codes (301, 302, and 307) and the `Location` header within the collection points to the URI that the request attempted to be redirected to. + ]]> The property is and the Web server attempts to redirect the request. @@ -131,7 +131,7 @@ System.Void - + The object provided in the last parameter to the asynchronous call of the method. @@ -170,19 +170,19 @@ Gets the collection of client certificates. An that represents the client certificates. - property for calling an XML Web service method that uses client certificates for authentication. - + property for calling an XML Web service method that uses client certificates for authentication. + [!code-csharp[HttpWebClientProtocol.ClientCertificates#1](~/snippets/csharp/System.Web.Services.Protocols/HttpWebClientProtocol/ClientCertificates/certcs.aspx#1)] - [!code-vb[HttpWebClientProtocol.ClientCertificates#1](~/snippets/visualbasic/VS_Snippets_Remoting/HttpWebClientProtocol.ClientCertificates/VB/certvb.aspx#1)] - + [!code-vb[HttpWebClientProtocol.ClientCertificates#1](~/snippets/visualbasic/VS_Snippets_Remoting/HttpWebClientProtocol.ClientCertificates/VB/certvb.aspx#1)] + ]]> @@ -216,19 +216,19 @@ Gets or sets the collection of cookies. A that represents the cookies for a Web Services client. - and assigning that to the property of the proxy class before calling the XML Web service method. If you need to maintain session state beyond when the proxy class instance goes out of scope, the client must store the HTTP cookie between calls to the XML Web service. For instance, a Web Forms client can store the HTTP cookie by saving the in its own session state. Because not all XML Web services use session state and thus clients are not always required to use the property of a client proxy, the documentation for the XML Web service must state whether session state is used. - - - -## Examples - The following code example is a Web Forms client of an XML Web service that uses session state. The client stores the HTTP cookie that uniquely identifies the session by storing it in the client's session state. - + and assigning that to the property of the proxy class before calling the XML Web service method. If you need to maintain session state beyond when the proxy class instance goes out of scope, the client must store the HTTP cookie between calls to the XML Web service. For instance, a Web Forms client can store the HTTP cookie by saving the in its own session state. Because not all XML Web services use session state and thus clients are not always required to use the property of a client proxy, the documentation for the XML Web service must state whether session state is used. + + + +## Examples + The following code example is a Web Forms client of an XML Web service that uses session state. The client stores the HTTP cookie that uniquely identifies the session by storing it in the client's session state. + [!code-aspx-csharp[HttpWebClientProtocol.CookieContainer#1](~/snippets/csharp/System.Web.Services/WebMethodAttribute/EnableSession/serverusageclientcs.aspx#1)] - [!code-aspx-vb[HttpWebClientProtocol.CookieContainer#1](~/snippets/visualbasic/VS_Snippets_Remoting/HttpWebClientProtocol.CookieContainer/VB/serverusageclientvb.aspx#1)] - + [!code-aspx-vb[HttpWebClientProtocol.CookieContainer#1](~/snippets/visualbasic/VS_Snippets_Remoting/HttpWebClientProtocol.CookieContainer/VB/serverusageclientvb.aspx#1)] + ]]> @@ -291,14 +291,12 @@ System.Boolean - + - The that exposes the XML Web service methods. - An that is used to store the mappings. - An that is used to store the mappings. + An that's used to store the mappings. Gets the for each XML Web service method exposed by the specified type, and stores the mappings in the specified . if can be assigned to a ; otherwise, . @@ -322,14 +320,12 @@ System.Collections.Hashtable - + - An array of type that contains the types that expose the XML Web service methods. An that is used to store the mappings. - An that is used to store the mappings. Gets the for each XML Web service method exposed by the specified types, and stores the mappings in the specified , as well as in a that this method returns. A that contains the for each XML Web service method exposed by the specified types. The types contained in are used as keys. To be added. @@ -460,22 +456,22 @@ Gets or sets proxy information for making an XML Web service request through a firewall. An that contains the proxy information for making requests through a firewall. The default value is the operating system proxy settings. - property if a client needs to use different proxy settings than those in the system settings. Use the class to set the proxy settings, because it implements . - - Default proxy settings can be set in a configuration file. For details, see [Configuring Internet Applications](/dotnet/framework/network-programming/configuring-internet-applications). - - - -## Examples - The following example sets the following proxy settings prior to invoking the `Math` XML Web service: the proxy server to `http://proxyserver`, the proxy port to 80 and the bypass to the proxy server for local addresses. - + property if a client needs to use different proxy settings than those in the system settings. Use the class to set the proxy settings, because it implements . + + Default proxy settings can be set in a configuration file. For details, see [Configuring Internet Applications](/dotnet/framework/network-programming/configuring-internet-applications). + + + +## Examples + The following example sets the following proxy settings prior to invoking the `Math` XML Web service: the proxy server to `http://proxyserver`, the proxy port to 80 and the bypass to the proxy server for local addresses. + [!code-cpp[Classic HttpWebClientProtocol.Proxy Example#1](~/snippets/cpp/VS_Snippets_Remoting/Classic HttpWebClientProtocol.Proxy Example/CPP/source.cpp#1)] [!code-csharp[Classic HttpWebClientProtocol.Proxy Example#1](~/snippets/csharp/System.Web.Services.Protocols/HttpWebClientProtocol/Proxy/source.cs#1)] - [!code-vb[Classic HttpWebClientProtocol.Proxy Example#1](~/snippets/visualbasic/VS_Snippets_Remoting/Classic HttpWebClientProtocol.Proxy Example/VB/source.vb#1)] - + [!code-vb[Classic HttpWebClientProtocol.Proxy Example#1](~/snippets/visualbasic/VS_Snippets_Remoting/Classic HttpWebClientProtocol.Proxy Example/VB/source.vb#1)] + ]]> @@ -514,11 +510,11 @@ if connection sharing is enabled; otherwise, . The default is . - property of the used to communicate with the Web server. - + property of the used to communicate with the Web server. + ]]> @@ -556,18 +552,18 @@ Gets or sets the value for the user agent header that is sent with each request. The value of the HTTP protocol user agent header. The default is "MS Web Services Client Protocol ", where is the version of the common language runtime (for example, 1.0.3705.0). - diff --git a/xml/System.Web.Services.Protocols/SoapException.xml b/xml/System.Web.Services.Protocols/SoapException.xml index a2731a6b4c5..37b29e38011 100644 --- a/xml/System.Web.Services.Protocols/SoapException.xml +++ b/xml/System.Web.Services.Protocols/SoapException.xml @@ -26,28 +26,28 @@ Represents the exception that is thrown when an XML Web service method is called over SOAP and an exception occurs. - can either be thrown by the common language runtime or by an XML Web service method. The common language runtime can throw a if a response to a request is not formatted correctly. XML Web service methods can generate a by simply throwing an exception within the XML Web service method. If the client accessed the method over SOAP, the exception is caught on the server and wrapped inside a new . The thrown has the following property values: - -|Property|Value| -|--------------|-----------| -||The property of the original exception.| -||.| -||The URL of the XML Web service method.| -||`null`, but an empty detail element is present in the fault element.| - - An XML Web service method might throw a when clients call using SOAP. If an XML Web service throws the , other details can be added through the , and properties that cannot otherwise be set by an XML Web service method if another type of exception is thrown. - - - -## Examples - The following example throws a where the XML Web service method sets the property. - + can either be thrown by the common language runtime or by an XML Web service method. The common language runtime can throw a if a response to a request is not formatted correctly. XML Web service methods can generate a by simply throwing an exception within the XML Web service method. If the client accessed the method over SOAP, the exception is caught on the server and wrapped inside a new . The thrown has the following property values: + +|Property|Value| +|--------------|-----------| +||The property of the original exception.| +||.| +||The URL of the XML Web service method.| +||`null`, but an empty detail element is present in the fault element.| + + An XML Web service method might throw a when clients call using SOAP. If an XML Web service throws the , other details can be added through the , and properties that cannot otherwise be set by an XML Web service method if another type of exception is thrown. + + + +## Examples + The following example throws a where the XML Web service method sets the property. + :::code language="aspx-csharp" source="~/snippets/csharp/System.Web.Services.Protocols/SoapException/Overview/sourcecs.asmx"::: :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic SoapException Example/VB/sourcevb.asmx"::: - + ]]> @@ -94,8 +94,8 @@ 4.0.0.0 - - + + The that holds the serialized object data about the exception being thrown. @@ -267,16 +267,14 @@ 4.0.0.0 - - + + - A message that identifies the reason the exception occurred. This parameter sets the property. An that specifies the type of error that occurred. This parameter sets the property. An optional subcode for the SOAP fault. This parameter sets the property. - An optional subcode for the SOAP fault. This parameter sets the property. Initializes a new instance of the class with the specified exception message, exception code, and subcode. To be added. @@ -329,14 +327,13 @@ 4.0.0.0 - - - - - + + + + + - - + A message that identifies the reason the exception occurred. This parameter sets the property. @@ -345,7 +342,6 @@ A URI that represents the XML Web service's function in processing the SOAP message. This parameter sets the property. An that contains application specific exception information. This parameter sets the property. An optional subcode for the SOAP fault. This parameter sets the property. - An optional subcode for the SOAP fault. This parameter sets the property. An exception that is the root cause of the exception. This parameter sets the property. Initializes a new instance of the class with the specified exception message, exception code, URI that identifies the piece of code that caused the exception, application-specific exception information, and reference to the root cause of the exception. To be added. @@ -365,15 +361,14 @@ 4.0.0.0 - - - - - - + + + + + + - - + A message that identifies the reason the exception occurred. This parameter sets the property. @@ -383,7 +378,6 @@ A human language associated with the exception. This parameter sets the property. An that contains application specific exception information. This parameter sets the property. An optional subcode for the SOAP fault. This parameter sets the property. - An optional subcode for the SOAP fault. This parameter sets the property. An exception that is the root cause of the exception. This parameter sets the property. Initializes a new instance of the class with the specified exception message, exception code, URI that identifies the piece of code that caused the exception, URI that represents the XML Web service's function in processing the SOAP message, the human language associated with the exception, the application-specific exception information, the subcode for the SOAP fault and reference to the root cause of the exception. To be added. @@ -410,28 +404,28 @@ Gets the piece of code that caused the exception. The piece of code that caused the exception. - property can only be set using one of the constructors that accepts an argument. - - When a SOAP request is made, the message is sent to a recipient, which is specified in a SOAP actor attribute. If an exception occurs within an XML Web service, the value of the SOAP actor attribute is assigned to the property. For XML Web services created using ASP.NET, the URL to the XML Web service method is the value of the SOAP actor attribute and is returned in the property. - + property can only be set using one of the constructors that accepts an argument. + + When a SOAP request is made, the message is sent to a recipient, which is specified in a SOAP actor attribute. If an exception occurs within an XML Web service, the value of the SOAP actor attribute is assigned to the property. For XML Web services created using ASP.NET, the URL to the XML Web service method is the value of the SOAP actor attribute and is returned in the property. + For more information on the SOAP actor attribute, see the [SOAP](https://www.w3.org/TR/soap/) specification. - - - -## Examples - The following Web Form example calls the `Math` XML Web service method, which throws an exception if a division by zero occurs. When the exception is thrown, the Web Form catches the exception and outputs the exception details, including the and properties, into an control. - + + + +## Examples + The following Web Form example calls the `Math` XML Web service method, which throws an exception if a division by zero occurs. When the exception is thrown, the Web Form catches the exception and outputs the exception details, including the and properties, into an control. + :::code language="aspx-csharp" source="~/snippets/csharp/System.Web.Services.Protocols/SoapException/Actor/sourcecs.aspx" id="Snippet1"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic SoapException.Actor Example/VB/sourcevb.aspx" id="Snippet1"::: - - In order for the preceding Web Form to use the following `Math` Web Service example, a namespace of `MyMath` was specified during the creation of the proxy class. - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic SoapException.Actor Example/VB/sourcevb.aspx" id="Snippet1"::: + + In order for the preceding Web Form to use the following `Math` Web Service example, a namespace of `MyMath` was specified during the creation of the proxy class. + :::code language="aspx-csharp" source="~/snippets/csharp/System.Web.Services.Protocols/SoapException/Actor/sourcecs.asmx"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic SoapException.Actor Example/VB/sourcevb.asmx"::: - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic SoapException.Actor Example/VB/sourcevb.asmx"::: + ]]> @@ -458,13 +452,13 @@ Specifies a SOAP fault code that represents a client call that is not formatted correctly or does not contain the appropriate information. - can be generated, is when a client call does not have proper authentication or payment information. It is generally an indication that the client call must be changed before it is resent. + can be generated, is when a client call does not have proper authentication or payment information. It is generally an indication that the client call must be changed before it is resent. :::code language="aspx-csharp" source="~/snippets/csharp/System.Web.Services.Protocols/SoapException/ClientFaultCode/sourcecs.asmx"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic SoapException.Detail Example/VB/sourcevb.asmx"::: + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic SoapException.Detail Example/VB/sourcevb.asmx"::: ]]> @@ -491,35 +485,35 @@ Gets the type of SOAP fault code. An that specifies the SOAP fault code that occurred. - property can only be set when creating a new instance of the class. - - The class is for use by XML Web service clients that call XML Web service methods over SOAP. ASP.NET handles whether the client that calls uses SOAP. This is when an exception occurs in an XML Web service. If the client uses SOAP, ASP.NET wraps the specific exception into a and sets the and properties. - - The set of available codes, known as SOAP Fault Codes for SOAP protocol version 1.1, are the following: - -|Item|Description| -|----------|-----------------| -||An invalid namespace for a SOAP envelope was found.| -||Not all SOAP elements require processing. However, if a SOAP element is marked with the `MustUnderstand` attribute with a value of 1, it is required. Failure to process the element generates this exception.| -||A client call was not formatted correctly or did not contain the appropriate information. For example, the client call might not have the proper authentication or payment information. It is generally an indication that the message must be changed before it is resent.| -||An error occurred during the processing of a client call on the server, however, the problem is not due to the message contents. For example, an upstream server might not respond to a request due to network problems. Typically, with this type of exception, the client call might succeed later. If an XML Web service throws an exception, other than and the client calls using SOAP, ASP.NET converts the exception to a , setting the property to and throws it back to the client.| - - - -## Examples - The following Web Form example calls the `Math` Web Service method, which throws an exception if a division by zero occurs. Once the exception is thrown, the Web Form catches the exception and outputs the exception details, including the and properties into a control. - + property can only be set when creating a new instance of the class. + + The class is for use by XML Web service clients that call XML Web service methods over SOAP. ASP.NET handles whether the client that calls uses SOAP. This is when an exception occurs in an XML Web service. If the client uses SOAP, ASP.NET wraps the specific exception into a and sets the and properties. + + The set of available codes, known as SOAP Fault Codes for SOAP protocol version 1.1, are the following: + +|Item|Description| +|----------|-----------------| +||An invalid namespace for a SOAP envelope was found.| +||Not all SOAP elements require processing. However, if a SOAP element is marked with the `MustUnderstand` attribute with a value of 1, it is required. Failure to process the element generates this exception.| +||A client call was not formatted correctly or did not contain the appropriate information. For example, the client call might not have the proper authentication or payment information. It is generally an indication that the message must be changed before it is resent.| +||An error occurred during the processing of a client call on the server, however, the problem is not due to the message contents. For example, an upstream server might not respond to a request due to network problems. Typically, with this type of exception, the client call might succeed later. If an XML Web service throws an exception, other than and the client calls using SOAP, ASP.NET converts the exception to a , setting the property to and throws it back to the client.| + + + +## Examples + The following Web Form example calls the `Math` Web Service method, which throws an exception if a division by zero occurs. Once the exception is thrown, the Web Form catches the exception and outputs the exception details, including the and properties into a control. + :::code language="aspx-csharp" source="~/snippets/csharp/System.Web.Services.Protocols/SoapException/Actor/sourcecs.aspx" id="Snippet1"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic SoapException.Actor Example/VB/sourcevb.aspx" id="Snippet1"::: - - In order for the preceding Web Form to use the following `Math` XML Web service example, a namespace of `MyMath` was specified during the creation of the proxy class. - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic SoapException.Actor Example/VB/sourcevb.aspx" id="Snippet1"::: + + In order for the preceding Web Form to use the following `Math` XML Web service example, a namespace of `MyMath` was specified during the creation of the proxy class. + :::code language="aspx-csharp" source="~/snippets/csharp/System.Web.Services.Protocols/SoapException/Actor/sourcecs.asmx"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic SoapException.Actor Example/VB/sourcevb.asmx"::: - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic SoapException.Actor Example/VB/sourcevb.asmx"::: + ]]> @@ -549,25 +543,25 @@ Gets an that represents the application-specific error information details. The application-specific error information. - property can be set using one of the class constructors that accepts a value. - - The property is used to supply application-specific error details related to the `Body` element of the SOAP request. According to the SOAP specification, if an error occurs because the client request cannot be processed due to the `Body` element of the SOAP request, the property must be set. If an error occurs in the header entries of the SOAP request, you must throw a , so that the error details are returned in the SOAP header. If the error does not occur, due to the processing of the `Body` element, then the property must not be set. - - In building an for the property, the and properties of can be used to ensure consistency with the SOAP specification. - - All immediate child elements of the detail element are called detail entries and each detail entry is encoded as an independent element within the detail element. - - - -## Examples - The following example throws a , where the XML Web service method sets the property. - + property can be set using one of the class constructors that accepts a value. + + The property is used to supply application-specific error details related to the `Body` element of the SOAP request. According to the SOAP specification, if an error occurs because the client request cannot be processed due to the `Body` element of the SOAP request, the property must be set. If an error occurs in the header entries of the SOAP request, you must throw a , so that the error details are returned in the SOAP header. If the error does not occur, due to the processing of the `Body` element, then the property must not be set. + + In building an for the property, the and properties of can be used to ensure consistency with the SOAP specification. + + All immediate child elements of the detail element are called detail entries and each detail entry is encoded as an independent element within the detail element. + + + +## Examples + The following example throws a , where the XML Web service method sets the property. + :::code language="aspx-csharp" source="~/snippets/csharp/System.Web.Services.Protocols/SoapException/ClientFaultCode/sourcecs.asmx"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic SoapException.Detail Example/VB/sourcevb.asmx"::: - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic SoapException.Detail Example/VB/sourcevb.asmx"::: + ]]> @@ -594,19 +588,19 @@ Gets an that represents the element of a SOAP Fault code. - for the property, the and properties of can be used to ensure consistency with the SOAP specification. - - - -## Examples - The following example sets the property using the field and then throws a . - + for the property, the and properties of can be used to ensure consistency with the SOAP specification. + + + +## Examples + The following example sets the property using the field and then throws a . + :::code language="aspx-csharp" source="~/snippets/csharp/System.Web.Services.Protocols/SoapException/DetailElementName/sourcecs.asmx"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic SoapException.DetailElementName Example/VB/sourcevb.asmx"::: - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic SoapException.DetailElementName Example/VB/sourcevb.asmx"::: + ]]> @@ -628,8 +622,8 @@ System.Void - - + + The that holds the serialized object data about the exception being thrown. @@ -639,12 +633,12 @@ - - - - - - + + + + + + Method System.Web.Services @@ -653,10 +647,10 @@ 4.0.0.0 - System.Boolean + System.Boolean - + An that contains a SOAP fault code. @@ -664,11 +658,11 @@ if is equivalent to the SOAP fault code; otherwise, . - can use this method to determine whether the property is functionally equivalent to the `Client` SOAP fault code defined in SOAP 1.1 regardless of the version of the SOAP protocol used. Versions of the SOAP protocol later than 1.1 might use different names or namespaces for the `Client` SOAP fault code defined in SOAP version 1.1, which is represented by the field. SOAP 1.2 names the fault code `Sender`, which is represented by the field. - + can use this method to determine whether the property is functionally equivalent to the `Client` SOAP fault code defined in SOAP 1.1 regardless of the version of the SOAP protocol used. Versions of the SOAP protocol later than 1.1 might use different names or namespaces for the `Client` SOAP fault code defined in SOAP version 1.1, which is represented by the field. SOAP 1.2 names the fault code `Sender`, which is represented by the field. + ]]> @@ -677,12 +671,12 @@ - - - - - - + + + + + + Method System.Web.Services @@ -691,10 +685,10 @@ 4.0.0.0 - System.Boolean + System.Boolean - + An that contains a SOAP fault code. @@ -702,11 +696,11 @@ if is equivalent to the SOAP fault code; otherwise, . - can use this method to determine whether the property is functionally equivalent to the `MustUnderstand` SOAP fault code defined in SOAP 1.1 regardless of the version of the SOAP protocol used. Versions of the SOAP protocol later than 1.1 might use different names or namespaces for the `MustUnderstand` SOAP fault code defined in SOAP version 1.1, which is represented by the field. SOAP 1.2 names the fault code the same; however it is scoped by a different XML namespace and is represented by the field. - + can use this method to determine whether the property is functionally equivalent to the `MustUnderstand` SOAP fault code defined in SOAP 1.1 regardless of the version of the SOAP protocol used. Versions of the SOAP protocol later than 1.1 might use different names or namespaces for the `MustUnderstand` SOAP fault code defined in SOAP version 1.1, which is represented by the field. SOAP 1.2 names the fault code the same; however it is scoped by a different XML namespace and is represented by the field. + ]]> @@ -715,12 +709,12 @@ - - - - - - + + + + + + Method System.Web.Services @@ -729,10 +723,10 @@ 4.0.0.0 - System.Boolean + System.Boolean - + An that contains a SOAP fault code. @@ -740,11 +734,11 @@ if is equivalent to the SOAP fault code; otherwise, . - can use this method to determine whether the property is functionally equivalent to the `Server` SOAP fault code defined in SOAP 1.1 regardless of the version of the SOAP protocol used. Versions of the SOAP protocol later than 1.1 might use different names or namespaces for the `Server` SOAP fault code defined in SOAP version 1.1, which is represented by the field. SOAP 1.2 names the fault code `Receiver`, which is represented by the field. - + can use this method to determine whether the property is functionally equivalent to the `Server` SOAP fault code defined in SOAP 1.1 regardless of the version of the SOAP protocol used. Versions of the SOAP protocol later than 1.1 might use different names or namespaces for the `Server` SOAP fault code defined in SOAP version 1.1, which is represented by the field. SOAP 1.2 names the fault code `Receiver`, which is represented by the field. + ]]> @@ -753,12 +747,12 @@ - - - - - - + + + + + + Method System.Web.Services @@ -767,10 +761,10 @@ 4.0.0.0 - System.Boolean + System.Boolean - + An that contains a SOAP fault code. @@ -778,11 +772,11 @@ if is equivalent to the SOAP fault code; otherwise, . - can use this method to determine whether the property is functionally equivalent to the `VersionMismatch` SOAP fault code defined in SOAP 1.1 regardless of the version of the SOAP protocol used. Versions of the SOAP protocol later than 1.1 might use different names or namespaces for the `VersionMismatch` SOAP fault code defined in SOAP version 1.1, which is represented by the field. SOAP 1.2 names the fault code the same; however, it is scoped by a different XML namespace and is represented by the field. - + can use this method to determine whether the property is functionally equivalent to the `VersionMismatch` SOAP fault code defined in SOAP 1.1 regardless of the version of the SOAP protocol used. Versions of the SOAP protocol later than 1.1 might use different names or namespaces for the `VersionMismatch` SOAP fault code defined in SOAP version 1.1, which is represented by the field. SOAP 1.2 names the fault code the same; however, it is scoped by a different XML namespace and is represented by the field. + ]]> @@ -816,11 +810,11 @@ Gets the human language associated with the exception. A value that identifies the human language associated with the exception. - @@ -845,11 +839,11 @@ A SOAP Fault Code that represents a SOAP element marked with the attribute was not processed. - with a . - + with a . + ]]> @@ -880,13 +874,13 @@ Gets a URI that represents the piece of code that caused the exception. The piece of code that caused the exception. - property is ignored when the SOAP protocol version 1.1 is used to communicate with an XML Web service. When SOAP 1.2 is used, the property sets the `node` element within a `fault` element of a SOAP message. - - The and properties both identify the piece of code that caused the exception; they just refer to their SOAP 1.1 and SOAP 1.2 names respectively. Because they both refer to the same property value, applications can just access the property. The value of these properties is set by the constructors that accept an `actor` parameter. - + property is ignored when the SOAP protocol version 1.1 is used to communicate with an XML Web service. When SOAP 1.2 is used, the property sets the `node` element within a `fault` element of a SOAP message. + + The and properties both identify the piece of code that caused the exception; they just refer to their SOAP 1.1 and SOAP 1.2 names respectively. Because they both refer to the same property value, applications can just access the property. The value of these properties is set by the constructors that accept an `actor` parameter. + ]]> @@ -917,11 +911,11 @@ Gets a URI that represents the XML Web service's function in processing the SOAP message. The role of the XML Web service throwing the . The default is . - property is ignored when the SOAP protocol version 1.1 is used to communicate with an XML Web service. When SOAP 1.2 is used, the property sets the `role` element within a `fault` element of a SOAP message. - + property is ignored when the SOAP protocol version 1.1 is used to communicate with an XML Web service. When SOAP 1.2 is used, the property sets the `role` element within a `fault` element of a SOAP message. + ]]> @@ -946,13 +940,13 @@ Specifies that a SOAP fault code that represents an error occurred during the processing of a client call on the server, where the problem is not due to the message contents. - might occur, for example, if a server being called cannot respond to a request due to network problems. Typically, with this type of exception, the client call might succeed later. - - If an XML Web service throws an exception, other than the , and the client is communicating with the XML Web service using the SOAP protocol, ASP.NET returns a SOAP fault. The .NET Framework running on the client machine converts that SOAP fault into a , setting the property to , and throws that exception to the client. - + might occur, for example, if a server being called cannot respond to a request due to network problems. Typically, with this type of exception, the client call might succeed later. + + If an XML Web service throws an exception, other than the , and the client is communicating with the XML Web service using the SOAP protocol, ASP.NET returns a SOAP fault. The .NET Framework running on the client machine converts that SOAP fault into a , setting the property to , and throws that exception to the client. + ]]> @@ -984,11 +978,11 @@ Gets the optional error information contained in the XML element of a SOAP fault. A that represents the contents of the XML element of a SOAP fault. - property is ignored when the SOAP protocol version 1.1 is used to communicate with an XML Web service. The property that represents the contents of the `code` element specifies the type of error that occurred using a limited number of pre-defined error codes specified by the SOAP protocol, whereas the optional `subcode` element allows an application to provide user-defined error codes specific to the application. ASP.NET defines two such codes that are represented by the and fields. - + property is ignored when the SOAP protocol version 1.1 is used to communicate with an XML Web service. The property that represents the contents of the `code` element specifies the type of error that occurred using a limited number of pre-defined error codes specified by the SOAP protocol, whereas the optional `subcode` element allows an application to provide user-defined error codes specific to the application. ASP.NET defines two such codes that are represented by the and fields. + ]]> @@ -1013,11 +1007,11 @@ A SOAP fault code that represents an invalid namespace for a SOAP envelope was found during the processing of the SOAP message. - diff --git a/xml/System.Web.Services.Protocols/SoapHttpClientProtocol.xml b/xml/System.Web.Services.Protocols/SoapHttpClientProtocol.xml index 6bb8c243da1..b7601829213 100644 --- a/xml/System.Web.Services.Protocols/SoapHttpClientProtocol.xml +++ b/xml/System.Web.Services.Protocols/SoapHttpClientProtocol.xml @@ -282,8 +282,8 @@ The proxy class does not have a binding defined. System.Xml.XmlReader - - + + A that provides the to initialize the . @@ -350,8 +350,8 @@ The proxy class does not have a binding defined. System.Xml.XmlWriter - - + + A that provides the to initialize the . @@ -447,9 +447,9 @@ The proxy class does not have a binding defined. System.Void - - - + + + The name of the method to invoke. @@ -476,10 +476,10 @@ The proxy class does not have a binding defined. System.Void - - - - + + + + The name of the method to invoke. diff --git a/xml/System.Xml.Linq/XDocument.xml b/xml/System.Xml.Linq/XDocument.xml index 7461615c089..cd58dc84c80 100644 --- a/xml/System.Xml.Linq/XDocument.xml +++ b/xml/System.Xml.Linq/XDocument.xml @@ -54,79 +54,79 @@ Represents an XML document. For the components and usage of an object, see XDocument Class Overview. - , see [Valid Content of XElement and XDocument Objects](/dotnet/standard/linq/valid-content-xelement-xdocument-objects). - - - -## Examples - The following example creates a document, and then adds a comment and an element to it. It then composes another document using the results of a query. - -```csharp -XDocument srcTree = new XDocument( - new XComment("This is a comment"), - new XElement("Root", - new XElement("Child1", "data1"), - new XElement("Child2", "data2"), - new XElement("Child3", "data3"), - new XElement("Child2", "data4"), - new XElement("Info5", "info5"), - new XElement("Info6", "info6"), - new XElement("Info7", "info7"), - new XElement("Info8", "info8") - ) -); - -XDocument doc = new XDocument( - new XComment("This is a comment"), - new XElement("Root", - from el in srcTree.Element("Root").Elements() - where ((string)el).StartsWith("data") - select el - ) -); -Console.WriteLine(doc); -``` - -```vb -Dim srcTree As XDocument = _ - - - - data1 - data2 - data3 - data4 - info5 - info6 - info7 - info8 - -Dim doc As XDocument = _ - - - - <%= From el In srcTree..Elements _ - Where CStr(el).StartsWith("data") _ - Select el %> - -Console.WriteLine(doc) -``` - - This example produces the following output: - -```xml - - - data1 - data2 - data3 - data4 - -``` - + , see [Valid Content of XElement and XDocument Objects](/dotnet/standard/linq/valid-content-xelement-xdocument-objects). + + + +## Examples + The following example creates a document, and then adds a comment and an element to it. It then composes another document using the results of a query. + +```csharp +XDocument srcTree = new XDocument( + new XComment("This is a comment"), + new XElement("Root", + new XElement("Child1", "data1"), + new XElement("Child2", "data2"), + new XElement("Child3", "data3"), + new XElement("Child2", "data4"), + new XElement("Info5", "info5"), + new XElement("Info6", "info6"), + new XElement("Info7", "info7"), + new XElement("Info8", "info8") + ) +); + +XDocument doc = new XDocument( + new XComment("This is a comment"), + new XElement("Root", + from el in srcTree.Element("Root").Elements() + where ((string)el).StartsWith("data") + select el + ) +); +Console.WriteLine(doc); +``` + +```vb +Dim srcTree As XDocument = _ + + + + data1 + data2 + data3 + data4 + info5 + info6 + info7 + info8 + +Dim doc As XDocument = _ + + + + <%= From el In srcTree..Elements _ + Where CStr(el).StartsWith("data") _ + Select el %> + +Console.WriteLine(doc) +``` + + This example produces the following output: + +```xml + + + data1 + data2 + data3 + data4 + +``` + ]]> @@ -146,83 +146,83 @@ Console.WriteLine(doc) Initializes a new instance of the class. - ; to create an with some specified initial content; and to create an as a copy of another object. - - There are not many scenarios that require you to create an . Instead, you can usually create your XML trees with an root node. Unless you have a specific requirement to create a document (for example, because you have to create processing instructions and comments at the top level, or you have to support document types), it is often more convenient to use as your root node. - - For details about the valid content of an , see [Valid Content of XElement and XDocument Objects](/dotnet/standard/linq/valid-content-xelement-xdocument-objects). - - - -## Examples - The following example creates a document, and then adds a comment and an element to it. It then composes another document using the results of a query. - -```csharp -XDocument srcTree = new XDocument( - new XComment("This is a comment"), - new XElement("Root", - new XElement("Child1", "data1"), - new XElement("Child2", "data2"), - new XElement("Child3", "data3"), - new XElement("Child2", "data4"), - new XElement("Info5", "info5"), - new XElement("Info6", "info6"), - new XElement("Info7", "info7"), - new XElement("Info8", "info8") - ) -); - -XDocument doc = new XDocument( - new XComment("This is a comment"), - new XElement("Root", - from el in srcTree.Element("Root").Elements() - where ((string)el).StartsWith("data") - select el - ) -); -Console.WriteLine(doc); -``` - -```vb -Dim srcTree As XDocument = _ - - - - data1 - data2 - data3 - data4 - info5 - info6 - info7 - info8 - -Dim doc As XDocument = _ - - - - <%= From el In srcTree..Elements _ - Where CStr(el).StartsWith("data") _ - Select el %> - -Console.WriteLine(doc) -``` - - This example produces the following output: - -```xml - - - data1 - data2 - data3 - data4 - -``` - + ; to create an with some specified initial content; and to create an as a copy of another object. + + There are not many scenarios that require you to create an . Instead, you can usually create your XML trees with an root node. Unless you have a specific requirement to create a document (for example, because you have to create processing instructions and comments at the top level, or you have to support document types), it is often more convenient to use as your root node. + + For details about the valid content of an , see [Valid Content of XElement and XDocument Objects](/dotnet/standard/linq/valid-content-xelement-xdocument-objects). + + + +## Examples + The following example creates a document, and then adds a comment and an element to it. It then composes another document using the results of a query. + +```csharp +XDocument srcTree = new XDocument( + new XComment("This is a comment"), + new XElement("Root", + new XElement("Child1", "data1"), + new XElement("Child2", "data2"), + new XElement("Child3", "data3"), + new XElement("Child2", "data4"), + new XElement("Info5", "info5"), + new XElement("Info6", "info6"), + new XElement("Info7", "info7"), + new XElement("Info8", "info8") + ) +); + +XDocument doc = new XDocument( + new XComment("This is a comment"), + new XElement("Root", + from el in srcTree.Element("Root").Elements() + where ((string)el).StartsWith("data") + select el + ) +); +Console.WriteLine(doc); +``` + +```vb +Dim srcTree As XDocument = _ + + + + data1 + data2 + data3 + data4 + info5 + info6 + info7 + info8 + +Dim doc As XDocument = _ + + + + <%= From el In srcTree..Elements _ + Where CStr(el).StartsWith("data") _ + Select el %> + +Console.WriteLine(doc) +``` + + This example produces the following output: + +```xml + + + data1 + data2 + data3 + data4 + +``` + ]]> @@ -271,39 +271,39 @@ Console.WriteLine(doc) Initializes a new instance of the class. - . Instead, you can usually create your XML trees with an root node. Unless you have a specific requirement to create a document (for example, because you have to create processing instructions and comments at the top level, or you have to support document types), it is often more convenient to use as your root node. - - For details about the valid content of an , see [Valid Content of XElement and XDocument Objects](/dotnet/standard/linq/valid-content-xelement-xdocument-objects). - - - -## Examples - The following example creates a new document, and then adds a comment and an element to it. - -```csharp -XDocument doc = new XDocument(); -doc.Add(new XComment("This is a comment")); -doc.Add(new XElement("Root", "content")); -Console.WriteLine(doc); -``` - -```vb -Dim doc As XDocument = New XDocument() -doc.Add() -doc.Add(content) -Console.WriteLine(doc) -``` - - This example produces the following output: - -```xml - -content -``` - + . Instead, you can usually create your XML trees with an root node. Unless you have a specific requirement to create a document (for example, because you have to create processing instructions and comments at the top level, or you have to support document types), it is often more convenient to use as your root node. + + For details about the valid content of an , see [Valid Content of XElement and XDocument Objects](/dotnet/standard/linq/valid-content-xelement-xdocument-objects). + + + +## Examples + The following example creates a new document, and then adds a comment and an element to it. + +```csharp +XDocument doc = new XDocument(); +doc.Add(new XComment("This is a comment")); +doc.Add(new XElement("Root", "content")); +Console.WriteLine(doc); +``` + +```vb +Dim doc As XDocument = New XDocument() +doc.Add() +doc.Add(content) +Console.WriteLine(doc) +``` + + This example produces the following output: + +```xml + +content +``` + ]]> @@ -362,81 +362,81 @@ Console.WriteLine(doc) A parameter list of content objects to add to this document. Initializes a new instance of the class with the specified content. - . Instead, you can usually create your XML trees with an root node. Unless you have a specific requirement to create a document (for example, because you have to create processing instructions and comments at the top level, or you have to support document types), it is often more convenient to use as your root node. - - For details about the valid content of an , see [Valid Content of XElement and XDocument Objects](/dotnet/standard/linq/valid-content-xelement-xdocument-objects). - - - -## Examples - The following example creates a document, and then adds a comment and an element to it. It then composes another document using the results of a query. - -```csharp -XDocument srcTree = new XDocument( - new XComment("This is a comment"), - new XElement("Root", - new XElement("Child1", "data1"), - new XElement("Child2", "data2"), - new XElement("Child3", "data3"), - new XElement("Child2", "data4"), - new XElement("Info5", "info5"), - new XElement("Info6", "info6"), - new XElement("Info7", "info7"), - new XElement("Info8", "info8") - ) -); - -XDocument doc = new XDocument( - new XComment("This is a comment"), - new XElement("Root", - from el in srcTree.Element("Root").Elements() - where ((string)el).StartsWith("data") - select el - ) -); -Console.WriteLine(doc); -``` - -```vb -Dim srcTree As XDocument = _ - - - - data1 - data2 - data3 - data4 - info5 - info6 - info7 - info8 - -Dim doc As XDocument = _ - - - - <%= From el In srcTree..Elements _ - Where CStr(el).StartsWith("data") _ - Select el %> - -Console.WriteLine(doc) -``` - - This example produces the following output: - -```xml - - - data1 - data2 - data3 - data4 - -``` - + . Instead, you can usually create your XML trees with an root node. Unless you have a specific requirement to create a document (for example, because you have to create processing instructions and comments at the top level, or you have to support document types), it is often more convenient to use as your root node. + + For details about the valid content of an , see [Valid Content of XElement and XDocument Objects](/dotnet/standard/linq/valid-content-xelement-xdocument-objects). + + + +## Examples + The following example creates a document, and then adds a comment and an element to it. It then composes another document using the results of a query. + +```csharp +XDocument srcTree = new XDocument( + new XComment("This is a comment"), + new XElement("Root", + new XElement("Child1", "data1"), + new XElement("Child2", "data2"), + new XElement("Child3", "data3"), + new XElement("Child2", "data4"), + new XElement("Info5", "info5"), + new XElement("Info6", "info6"), + new XElement("Info7", "info7"), + new XElement("Info8", "info8") + ) +); + +XDocument doc = new XDocument( + new XComment("This is a comment"), + new XElement("Root", + from el in srcTree.Element("Root").Elements() + where ((string)el).StartsWith("data") + select el + ) +); +Console.WriteLine(doc); +``` + +```vb +Dim srcTree As XDocument = _ + + + + data1 + data2 + data3 + data4 + info5 + info6 + info7 + info8 + +Dim doc As XDocument = _ + + + + <%= From el In srcTree..Elements _ + Where CStr(el).StartsWith("data") _ + Select el %> + +Console.WriteLine(doc) +``` + + This example produces the following output: + +```xml + + + data1 + data2 + data3 + data4 + +``` + ]]> @@ -483,13 +483,13 @@ Console.WriteLine(doc) The object that will be copied. Initializes a new instance of the class from an existing object. - . - - This constructor traverses all nodes and attributes in the document specified in the `other` parameter, and creates copies of all nodes as it assembles the newly initialized . - + . + + This constructor traverses all nodes and attributes in the document specified in the `other` parameter, and creates copies of all nodes as it assembles the newly initialized . + ]]> @@ -561,85 +561,85 @@ Console.WriteLine(doc) The content of the document. Initializes a new instance of the class with the specified and content. - . Instead, you can usually create your XML trees with an root node. Unless you have a specific requirement to create a document (for example, because you have to create processing instructions and comments at the top level, or you have to support document types), it is often more convenient to use as your root node. - - For details about the valid content of an , see [Valid Content of XElement and XDocument Objects](/dotnet/standard/linq/valid-content-xelement-xdocument-objects). - - - -## Examples - The following example uses this constructor to create a document. - -```csharp -XDocument srcTree = new XDocument( - new XComment("This is a comment"), - new XElement("Root", - new XElement("Child1", "data1"), - new XElement("Child2", "data2"), - new XElement("Child3", "data3"), - new XElement("Child2", "data4"), - new XElement("Info5", "info5"), - new XElement("Info6", "info6"), - new XElement("Info7", "info7"), - new XElement("Info8", "info8") - ) -); - -XDocument doc = new XDocument( - new XDeclaration("1.0", "utf-8", "yes"), - new XComment("This is a new comment"), - new XElement("Root", - from el in srcTree.Element("Root").Elements() - where ((string)el).StartsWith("data") - select el - ) -); -doc.Save("Test.xml"); -Console.WriteLine(File.ReadAllText("Test.xml")); -``` - -```vb -Dim srcTree As XDocument = _ - - - - data1 - data2 - data3 - data4 - info5 - info6 - info7 - info8 - -Dim doc As XDocument = _ - - - - <%= From el In srcTree..Elements _ - Where CStr(el).StartsWith("data") _ - Select el %> - -doc.Save("Test.xml") -Console.WriteLine(File.ReadAllText("Test.xml")) -``` - - This example produces the following output: - -```xml - - - - data1 - data2 - data3 - data4 - -``` - + . Instead, you can usually create your XML trees with an root node. Unless you have a specific requirement to create a document (for example, because you have to create processing instructions and comments at the top level, or you have to support document types), it is often more convenient to use as your root node. + + For details about the valid content of an , see [Valid Content of XElement and XDocument Objects](/dotnet/standard/linq/valid-content-xelement-xdocument-objects). + + + +## Examples + The following example uses this constructor to create a document. + +```csharp +XDocument srcTree = new XDocument( + new XComment("This is a comment"), + new XElement("Root", + new XElement("Child1", "data1"), + new XElement("Child2", "data2"), + new XElement("Child3", "data3"), + new XElement("Child2", "data4"), + new XElement("Info5", "info5"), + new XElement("Info6", "info6"), + new XElement("Info7", "info7"), + new XElement("Info8", "info8") + ) +); + +XDocument doc = new XDocument( + new XDeclaration("1.0", "utf-8", "yes"), + new XComment("This is a new comment"), + new XElement("Root", + from el in srcTree.Element("Root").Elements() + where ((string)el).StartsWith("data") + select el + ) +); +doc.Save("Test.xml"); +Console.WriteLine(File.ReadAllText("Test.xml")); +``` + +```vb +Dim srcTree As XDocument = _ + + + + data1 + data2 + data3 + data4 + info5 + info6 + info7 + info8 + +Dim doc As XDocument = _ + + + + <%= From el In srcTree..Elements _ + Where CStr(el).StartsWith("data") _ + Select el %> + +doc.Save("Test.xml") +Console.WriteLine(File.ReadAllText("Test.xml")) +``` + + This example produces the following output: + +```xml + + + + data1 + data2 + data3 + data4 + +``` + ]]> @@ -709,41 +709,41 @@ Console.WriteLine(File.ReadAllText("Test.xml")) Gets or sets the XML declaration for this document. An that contains the XML declaration for this document. - . Another approach for encoding a document is to specify the encoding on an that you pass to LINQ to XML for writing. - - - -## Examples - The following example uses this property to retrieve the XML declaration of a document. - -```csharp -XDocument doc = new XDocument( - new XDeclaration("1.0", "utf-8", "yes"), - new XComment("This is a comment"), - new XElement("Root", "content") -); - -Console.WriteLine(doc.Declaration); -``` - -```vb -Dim doc As XDocument = _ - - - content - -Console.WriteLine(doc.Declaration) -``` - - This example produces the following output: - -``` - -``` - + . Another approach for encoding a document is to specify the encoding on an that you pass to LINQ to XML for writing. + + + +## Examples + The following example uses this property to retrieve the XML declaration of a document. + +```csharp +XDocument doc = new XDocument( + new XDeclaration("1.0", "utf-8", "yes"), + new XComment("This is a comment"), + new XElement("Root", "content") +); + +Console.WriteLine(doc.Declaration); +``` + +```vb +Dim doc As XDocument = _ + + + content + +Console.WriteLine(doc.Declaration) +``` + + This example produces the following output: + +``` + +``` + ]]> @@ -805,104 +805,104 @@ Console.WriteLine(doc.Declaration) Gets the Document Type Definition (DTD) for this document. A that contains the DTD for this document. - node. When you serialize or save the tree, the DTD will also be serialized. LINQ to XML will expand any entities in the DTD. When you serialize or save the XML tree, the entity references are not saved; instead, the nodes are saved with the entity references replaced by the text of the entity. - - If the DTD contains default attributes, the attributes are created in the XML tree as ordinary attributes. - - By default, LINQ to XML does not validate a document based on its DTD. To validate a document based on a DTD, create an that will validate based on a DTD, and then create an XML tree from the . - - - -## Examples - The following example creates a document that contains an . - - Visual Basic does not support document types within XML literals. However, it is possible to create a document that contains a document type by first creating the document using XML literals, and then creating and adding an node in the appropriate place in the XML tree. - -```csharp -string internalSubset = @" - - -"; - -string target = "xml-stylesheet"; -string data = "href='mystyle.css' title='Compact' type='text/css'"; - -XDocument doc = new XDocument( - new XComment("This is a comment."), - new XProcessingInstruction(target, data), - new XDocumentType("Pubs", null, null, internalSubset), - new XElement("Pubs", - new XElement("Book", - new XElement("Title", "Artifacts of Roman Civilization"), - new XElement("Author", "Moreno, Jordao") - ), - new XElement("Book", - new XElement("Title", "Midieval Tools and Implements"), - new XElement("Author", "Gazit, Inbar") - ) - ), - new XComment("This is another comment.") -); -doc.Declaration = new XDeclaration("1.0", "utf-8", "true"); -Console.WriteLine(doc); - -doc.Save("test.xml"); -``` - -```vb -Dim internalSubset = _ - "" & Environment.NewLine & _ - "" & Environment.NewLine & _ - "" & Environment.NewLine & _ - "" - -Dim doc As XDocument = _ - - - - - - Artifacts of Roman Civilization - Moreno, Jordao - - - Midieval Tools and Implements - Gazit, Inbar - - - - -doc.Nodes().Skip(1).First().AddAfterSelf(New XDocumentType("Pubs", Nothing, Nothing, internalSubset)) -Console.WriteLine(doc) -``` - - This example produces the following output: - -```xml - - - - - -]> - - - Artifacts of Roman Civilization - Moreno, Jordao - - - Midieval Tools and Implements - Gazit, Inbar - - - -``` - + node. When you serialize or save the tree, the DTD will also be serialized. LINQ to XML will expand any entities in the DTD. When you serialize or save the XML tree, the entity references are not saved; instead, the nodes are saved with the entity references replaced by the text of the entity. + + If the DTD contains default attributes, the attributes are created in the XML tree as ordinary attributes. + + By default, LINQ to XML does not validate a document based on its DTD. To validate a document based on a DTD, create an that will validate based on a DTD, and then create an XML tree from the . + + + +## Examples + The following example creates a document that contains an . + + Visual Basic does not support document types within XML literals. However, it is possible to create a document that contains a document type by first creating the document using XML literals, and then creating and adding an node in the appropriate place in the XML tree. + +```csharp +string internalSubset = @" + + +"; + +string target = "xml-stylesheet"; +string data = "href='mystyle.css' title='Compact' type='text/css'"; + +XDocument doc = new XDocument( + new XComment("This is a comment."), + new XProcessingInstruction(target, data), + new XDocumentType("Pubs", null, null, internalSubset), + new XElement("Pubs", + new XElement("Book", + new XElement("Title", "Artifacts of Roman Civilization"), + new XElement("Author", "Moreno, Jordao") + ), + new XElement("Book", + new XElement("Title", "Midieval Tools and Implements"), + new XElement("Author", "Gazit, Inbar") + ) + ), + new XComment("This is another comment.") +); +doc.Declaration = new XDeclaration("1.0", "utf-8", "true"); +Console.WriteLine(doc); + +doc.Save("test.xml"); +``` + +```vb +Dim internalSubset = _ + "" & Environment.NewLine & _ + "" & Environment.NewLine & _ + "" & Environment.NewLine & _ + "" + +Dim doc As XDocument = _ + + + + + + Artifacts of Roman Civilization + Moreno, Jordao + + + Midieval Tools and Implements + Gazit, Inbar + + + + +doc.Nodes().Skip(1).First().AddAfterSelf(New XDocumentType("Pubs", Nothing, Nothing, internalSubset)) +Console.WriteLine(doc) +``` + + This example produces the following output: + +```xml + + + + + +]> + + + Artifacts of Roman Civilization + Moreno, Jordao + + + Midieval Tools and Implements + Gazit, Inbar + + + +``` + ]]> @@ -919,13 +919,13 @@ Console.WriteLine(doc) Creates a new from a file specified by a URI, from an , or from an . - from a file, a , or an . - - To create an from a string that contains XML, use . - + from a file, a , or an . + + To create an from a string that contains XML, use . + ]]> @@ -983,19 +983,19 @@ Console.WriteLine(doc) Creates a new instance by using the specified stream. An object that reads the data that is contained in the stream. - overload that takes as a parameter. - - The loading functionality of LINQ to XML is built upon . Therefore, you might catch any exceptions that are thrown by the overload methods and the methods that read and parse the document. - - If you have to modify , follow these steps: - -1. Create an by calling one of the overloads that take as a parameter. - -2. Pass the to one of the overloads of that takes as a parameter. - + overload that takes as a parameter. + + The loading functionality of LINQ to XML is built upon . Therefore, you might catch any exceptions that are thrown by the overload methods and the methods that read and parse the document. + + If you have to modify , follow these steps: + +1. Create an by calling one of the overloads that take as a parameter. + +2. Pass the to one of the overloads of that takes as a parameter. + ]]> @@ -1049,34 +1049,34 @@ Console.WriteLine(doc) Creates a new from a . An that contains the contents of the specified . - . Therefore, you might catch any exceptions that are thrown by the overload methods and the methods that read and parse the document. - - - -## Examples - The following example creates a document from a . - -```csharp -TextReader tr = new StringReader("Content"); -XDocument doc = XDocument.Load(tr); -Console.WriteLine(doc); -``` - -```vb -Dim tr As TextReader = New StringReader("Content") -Dim doc As XDocument = XDocument.Load(tr) -Console.WriteLine(doc) -``` - - This example produces the following output: - -```xml -Content -``` - + . Therefore, you might catch any exceptions that are thrown by the overload methods and the methods that read and parse the document. + + + +## Examples + The following example creates a document from a . + +```csharp +TextReader tr = new StringReader("Content"); +XDocument doc = XDocument.Load(tr); +Console.WriteLine(doc); +``` + +```vb +Dim tr As TextReader = New StringReader("Content") +Dim doc As XDocument = XDocument.Load(tr) +Console.WriteLine(doc) +``` + + This example produces the following output: + +```xml +Content +``` + ]]> @@ -1142,72 +1142,72 @@ Console.WriteLine(doc) Creates a new from a file. An that contains the contents of the specified file. - to read the XML into an XML tree. - - Use to create an from a string that contains XML. - - LINQ to XML's loading functionality is built upon . Therefore, you might catch any exceptions that are thrown by the overload methods and the methods that read and parse the document. - - - -## Examples - The following example shows how to load an from a file. - - This example uses the following XML document: - - [Sample XML File: Typical Purchase Order (LINQ to XML)](/dotnet/standard/linq/sample-xml-file-typical-purchase-order) - -```csharp -XDocument doc = XDocument.Load("PurchaseOrder.xml"); -Console.WriteLine(doc); -``` - -```vb -Dim doc As XDocument = XDocument.Load("PurchaseOrder.xml") -Console.WriteLine(doc) -``` - - This example produces the following output: - -``` - -
- Ellen Adams - 123 Maple Street - Mill Valley - CA - 10999 - USA -
-
- Tai Yee - 8 Oak Avenue - Old Town - PA - 95819 - USA -
- Please leave packages in shed by driveway. - - - Lawnmower - 1 - 148.95 - Confirm this is electric - - - Baby Monitor - 2 - 39.98 - 1999-05-21 - - -
-``` - + to read the XML into an XML tree. + + Use to create an from a string that contains XML. + + LINQ to XML's loading functionality is built upon . Therefore, you might catch any exceptions that are thrown by the overload methods and the methods that read and parse the document. + + + +## Examples + The following example shows how to load an from a file. + + This example uses the following XML document: + + [Sample XML File: Typical Purchase Order (LINQ to XML)](/dotnet/standard/linq/sample-xml-file-typical-purchase-order) + +```csharp +XDocument doc = XDocument.Load("PurchaseOrder.xml"); +Console.WriteLine(doc); +``` + +```vb +Dim doc As XDocument = XDocument.Load("PurchaseOrder.xml") +Console.WriteLine(doc) +``` + + This example produces the following output: + +``` + +
+ Ellen Adams + 123 Maple Street + Mill Valley + CA + 10999 + USA +
+
+ Tai Yee + 8 Oak Avenue + Old Town + PA + 95819 + USA +
+ Please leave packages in shed by driveway. + + + Lawnmower + 1 + 148.95 + Confirm this is electric + + + Baby Monitor + 2 + 39.98 + 1999-05-21 + + +
+``` + ]]>
@@ -1266,66 +1266,66 @@ Console.WriteLine(doc) Creates a new from an . An that contains the contents of the specified . - from a DOM document, and then use the to create an . - - LINQ to XML's loading functionality is built upon . Therefore, you might catch any exceptions that are thrown by the overload methods and the methods that read and parse the document. - - - -## Examples - The following example creates a DOM document, creates an from the DOM document, creates an using the . - -```csharp -// Create a DOM document with some content. -XmlDocument doc = new XmlDocument(); -XmlElement child = doc.CreateElement("Child"); -child.InnerText = "child contents"; -XmlElement root = doc.CreateElement("Root"); -root.AppendChild(child); -doc.AppendChild(root); - -// create a reader and move to the content -using (XmlNodeReader nodeReader = new XmlNodeReader(doc)) { - // the reader must be in the Interactive state in order to - // create a LINQ to XML tree from it. - nodeReader.MoveToContent(); - - XDocument xRoot = XDocument.Load(nodeReader); - Console.WriteLine(xRoot); -} -``` - -```vb -' Create a DOM document with some content. -Dim doc As XmlDocument = New XmlDocument() -Dim child As XmlElement = doc.CreateElement("Child") -child.InnerText = "child contents" -Dim root As XmlElement = doc.CreateElement("Root") -root.AppendChild(child) -doc.AppendChild(root) - -' create a reader and move to the content -Using nodeReader = New XmlNodeReader(doc) - ' the reader must be in the Interactive state in order to - ' create a LINQ to XML tree from it. - nodeReader.MoveToContent() - - Dim xRoot As XDocument = XDocument.Load(nodeReader) - Console.WriteLine(xRoot) -End Using -``` - - This example produces the following output: - -```xml - - child contents - -``` - + from a DOM document, and then use the to create an . + + LINQ to XML's loading functionality is built upon . Therefore, you might catch any exceptions that are thrown by the overload methods and the methods that read and parse the document. + + + +## Examples + The following example creates a DOM document, creates an from the DOM document, creates an using the . + +```csharp +// Create a DOM document with some content. +XmlDocument doc = new XmlDocument(); +XmlElement child = doc.CreateElement("Child"); +child.InnerText = "child contents"; +XmlElement root = doc.CreateElement("Root"); +root.AppendChild(child); +doc.AppendChild(root); + +// create a reader and move to the content +using (XmlNodeReader nodeReader = new XmlNodeReader(doc)) { + // the reader must be in the Interactive state in order to + // create a LINQ to XML tree from it. + nodeReader.MoveToContent(); + + XDocument xRoot = XDocument.Load(nodeReader); + Console.WriteLine(xRoot); +} +``` + +```vb +' Create a DOM document with some content. +Dim doc As XmlDocument = New XmlDocument() +Dim child As XmlElement = doc.CreateElement("Child") +child.InnerText = "child contents" +Dim root As XmlElement = doc.CreateElement("Root") +root.AppendChild(child) +doc.AppendChild(root) + +' create a reader and move to the content +Using nodeReader = New XmlNodeReader(doc) + ' the reader must be in the Interactive state in order to + ' create a LINQ to XML tree from it. + nodeReader.MoveToContent() + + Dim xRoot As XDocument = XDocument.Load(nodeReader) + Console.WriteLine(xRoot) +End Using +``` + + This example produces the following output: + +```xml + + child contents + +``` + ]]> @@ -1379,17 +1379,17 @@ End Using Creates a new instance by using the specified stream, optionally preserving white space, setting the base URI, and retaining line information. An object that reads the data that is contained in the stream. - . Therefore, you might catch any exceptions that are thrown by the overload methods and the methods that read and parse the document. - - If you have to modify , follow these steps: - -1. Create an by calling one of the overloads that takes as a parameter. - -2. Pass the to one of the overloads of that takes as a parameter. - + . Therefore, you might catch any exceptions that are thrown by the overload methods and the methods that read and parse the document. + + If you have to modify , follow these steps: + +1. Create an by calling one of the overloads that takes as a parameter. + +2. Pass the to one of the overloads of that takes as a parameter. + ]]>
@@ -1439,93 +1439,93 @@ End Using Creates a new from a , optionally preserving white space, setting the base URI, and retaining line information. An that contains the XML that was read from the specified . - flag in `options` causes the reader to read all white space in the source XML. Nodes of type are created for both significant and insignificant white space. - - If the source XML is indented, not setting the flag in `options` causes the reader to ignore all of the insignificant white space in the source XML. The XML tree is created without any text nodes for insignificant white space. - - If the source XML is not indented, setting the flag in `options` has no effect. Significant white space is still preserved, and there are no spans of insignificant white space that could cause the creation of more white space text nodes. - - For more information, see [Preserve white space while loading or parsing XML](/dotnet/standard/linq/preserve-white-space-loading-parsing-xml) and [Preserve white space while serializing](/dotnet/standard/linq/preserve-white-space-serializing). - - Use to create an from a string that contains XML. - - Setting is not valid when loading from a . - - There is a performance penalty if you set the flag. - - The line information is accurate immediately after loading the XML document. If you modify the XML tree after loading the document, the line information may become meaningless. - - LINQ to XML's loading functionality is built upon . Therefore, you might catch any exceptions that are thrown by the overload methods and the methods that read and parse the document. - - - -## Examples - The following example creates a document from a . - -```csharp -TextReader sr; -int whiteSpaceNodes; - -sr = new StringReader(" "); -XDocument xmlTree1 = XDocument.Load(sr, LoadOptions.None); -sr.Close(); -whiteSpaceNodes = xmlTree1 - .Element("Root") - .DescendantNodesAndSelf() - .OfType() - .Where(tNode => tNode.ToString().Trim().Length == 0) - .Count(); -Console.WriteLine("Count of white space nodes (not preserving whitespace): {0}", whiteSpaceNodes); - -sr = new StringReader(" "); -XDocument xmlTree2 = XDocument.Load(sr, LoadOptions.PreserveWhitespace); -sr.Close(); -whiteSpaceNodes = xmlTree2 - .Element("Root") - .DescendantNodesAndSelf() - .OfType() - .Where(tNode => tNode.ToString().Trim().Length == 0) - .Count(); -Console.WriteLine("Count of white space nodes (preserving whitespace): {0}", whiteSpaceNodes); -``` - -```vb -Dim sr As TextReader -Dim whiteSpaceNodes As Integer - -sr = New StringReader(" ") -Dim xmlTree1 As XDocument = XDocument.Load(sr, LoadOptions.None) -sr.Close() -whiteSpaceNodes = xmlTree1 _ - .Element("Root") _ - .DescendantNodesAndSelf() _ - .OfType(Of XText)() _ - .Where(Function(ByVal tNode As XNode) tNode. _ - ToString().Trim().Length = 0).Count() -Console.WriteLine("Count of white space nodes (not preserving whitespace): {0}", whiteSpaceNodes) - -sr = New StringReader(" ") -Dim xmlTree2 As XDocument = XDocument.Load(sr, LoadOptions.PreserveWhitespace) -sr.Close() -whiteSpaceNodes = xmlTree2 _ - .Element("Root") _ - .DescendantNodesAndSelf() _ - .OfType(Of XText)() _ - .Where(Function(ByVal tNode As XNode) tNode. _ - ToString().Trim().Length = 0).Count() -Console.WriteLine("Count of white space nodes (preserving whitespace): {0}", whiteSpaceNodes) -``` - - This example produces the following output: - -``` -Count of white space nodes (not preserving whitespace): 0 -Count of white space nodes (preserving whitespace): 3 -``` - + flag in `options` causes the reader to read all white space in the source XML. Nodes of type are created for both significant and insignificant white space. + + If the source XML is indented, not setting the flag in `options` causes the reader to ignore all of the insignificant white space in the source XML. The XML tree is created without any text nodes for insignificant white space. + + If the source XML is not indented, setting the flag in `options` has no effect. Significant white space is still preserved, and there are no spans of insignificant white space that could cause the creation of more white space text nodes. + + For more information, see [Preserve white space while loading or parsing XML](/dotnet/standard/linq/preserve-white-space-loading-parsing-xml) and [Preserve white space while serializing](/dotnet/standard/linq/preserve-white-space-serializing). + + Use to create an from a string that contains XML. + + Setting is not valid when loading from a . + + There is a performance penalty if you set the flag. + + The line information is accurate immediately after loading the XML document. If you modify the XML tree after loading the document, the line information may become meaningless. + + LINQ to XML's loading functionality is built upon . Therefore, you might catch any exceptions that are thrown by the overload methods and the methods that read and parse the document. + + + +## Examples + The following example creates a document from a . + +```csharp +TextReader sr; +int whiteSpaceNodes; + +sr = new StringReader(" "); +XDocument xmlTree1 = XDocument.Load(sr, LoadOptions.None); +sr.Close(); +whiteSpaceNodes = xmlTree1 + .Element("Root") + .DescendantNodesAndSelf() + .OfType() + .Where(tNode => tNode.ToString().Trim().Length == 0) + .Count(); +Console.WriteLine("Count of white space nodes (not preserving whitespace): {0}", whiteSpaceNodes); + +sr = new StringReader(" "); +XDocument xmlTree2 = XDocument.Load(sr, LoadOptions.PreserveWhitespace); +sr.Close(); +whiteSpaceNodes = xmlTree2 + .Element("Root") + .DescendantNodesAndSelf() + .OfType() + .Where(tNode => tNode.ToString().Trim().Length == 0) + .Count(); +Console.WriteLine("Count of white space nodes (preserving whitespace): {0}", whiteSpaceNodes); +``` + +```vb +Dim sr As TextReader +Dim whiteSpaceNodes As Integer + +sr = New StringReader(" ") +Dim xmlTree1 As XDocument = XDocument.Load(sr, LoadOptions.None) +sr.Close() +whiteSpaceNodes = xmlTree1 _ + .Element("Root") _ + .DescendantNodesAndSelf() _ + .OfType(Of XText)() _ + .Where(Function(ByVal tNode As XNode) tNode. _ + ToString().Trim().Length = 0).Count() +Console.WriteLine("Count of white space nodes (not preserving whitespace): {0}", whiteSpaceNodes) + +sr = New StringReader(" ") +Dim xmlTree2 As XDocument = XDocument.Load(sr, LoadOptions.PreserveWhitespace) +sr.Close() +whiteSpaceNodes = xmlTree2 _ + .Element("Root") _ + .DescendantNodesAndSelf() _ + .OfType(Of XText)() _ + .Where(Function(ByVal tNode As XNode) tNode. _ + ToString().Trim().Length = 0).Count() +Console.WriteLine("Count of white space nodes (preserving whitespace): {0}", whiteSpaceNodes) +``` + + This example produces the following output: + +``` +Count of white space nodes (not preserving whitespace): 0 +Count of white space nodes (preserving whitespace): 3 +``` + ]]> @@ -1587,57 +1587,57 @@ Count of white space nodes (preserving whitespace): 3 Creates a new from a file, optionally preserving white space, setting the base URI, and retaining line information. An that contains the contents of the specified file. - flag in `options` causes the reader to read all white space in the source XML. Nodes of type are created for both significant and insignificant white space. - - If the source XML is indented, not setting the flag in `options` causes the reader to ignore all of the insignificant white space in the source XML. The XML tree is created without any text nodes for insignificant white space. - - If the source XML is not indented, setting the flag in `options` has no effect. Significant white space is still preserved, and there are no spans of insignificant white space that could cause the creation of more white space text nodes. - - For more information, see [Preserve white space while loading or parsing XML](/dotnet/standard/linq/preserve-white-space-loading-parsing-xml) and [Preserve white space while serializing](/dotnet/standard/linq/preserve-white-space-serializing). - - Use to create an from a string that contains XML. - - There is a performance penalty if you set the and the flags. - - The base URI and the line information are accurate immediately after loading the XML document. If you modify the XML tree after loading the document, the base URI and line information may become meaningless. - - LINQ to XML's loading functionality is built upon . Therefore, you might catch any exceptions that are thrown by the overload methods and the methods that read and parse the document. - - - -## Examples - The following example shows how to load an from a file. - - This example uses the following XML document: - - [Sample XML File: Typical Purchase Order (LINQ to XML)](/dotnet/standard/linq/sample-xml-file-typical-purchase-order) - -```csharp -XDocument doc1 = XDocument.Load("PurchaseOrder.xml", LoadOptions.None); -Console.WriteLine("nodes if not preserving whitespace: {0}", doc1.DescendantNodes().Count()); - -XDocument doc2 = XDocument.Load("PurchaseOrder.xml", LoadOptions.PreserveWhitespace); -Console.WriteLine("nodes if preserving whitespace: {0}", doc2.DescendantNodes().Count()); -``` - -```vb -Dim doc1 As XDocument = XDocument.Load("PurchaseOrder.xml", LoadOptions.None) -Console.WriteLine("nodes if not preserving whitespace: {0}", doc1.DescendantNodes().Count()) - -Dim doc2 As XDocument = XDocument.Load("PurchaseOrder.xml", LoadOptions.PreserveWhitespace) -Console.WriteLine("nodes if preserving whitespace: {0}", doc2.DescendantNodes().Count()) -``` - - This example produces the following output: - -``` -nodes if not preserving whitespace: 48 -nodes if preserving whitespace: 82 -``` - + flag in `options` causes the reader to read all white space in the source XML. Nodes of type are created for both significant and insignificant white space. + + If the source XML is indented, not setting the flag in `options` causes the reader to ignore all of the insignificant white space in the source XML. The XML tree is created without any text nodes for insignificant white space. + + If the source XML is not indented, setting the flag in `options` has no effect. Significant white space is still preserved, and there are no spans of insignificant white space that could cause the creation of more white space text nodes. + + For more information, see [Preserve white space while loading or parsing XML](/dotnet/standard/linq/preserve-white-space-loading-parsing-xml) and [Preserve white space while serializing](/dotnet/standard/linq/preserve-white-space-serializing). + + Use to create an from a string that contains XML. + + There is a performance penalty if you set the and the flags. + + The base URI and the line information are accurate immediately after loading the XML document. If you modify the XML tree after loading the document, the base URI and line information may become meaningless. + + LINQ to XML's loading functionality is built upon . Therefore, you might catch any exceptions that are thrown by the overload methods and the methods that read and parse the document. + + + +## Examples + The following example shows how to load an from a file. + + This example uses the following XML document: + + [Sample XML File: Typical Purchase Order (LINQ to XML)](/dotnet/standard/linq/sample-xml-file-typical-purchase-order) + +```csharp +XDocument doc1 = XDocument.Load("PurchaseOrder.xml", LoadOptions.None); +Console.WriteLine("nodes if not preserving whitespace: {0}", doc1.DescendantNodes().Count()); + +XDocument doc2 = XDocument.Load("PurchaseOrder.xml", LoadOptions.PreserveWhitespace); +Console.WriteLine("nodes if preserving whitespace: {0}", doc2.DescendantNodes().Count()); +``` + +```vb +Dim doc1 As XDocument = XDocument.Load("PurchaseOrder.xml", LoadOptions.None) +Console.WriteLine("nodes if not preserving whitespace: {0}", doc1.DescendantNodes().Count()) + +Dim doc2 As XDocument = XDocument.Load("PurchaseOrder.xml", LoadOptions.PreserveWhitespace) +Console.WriteLine("nodes if preserving whitespace: {0}", doc2.DescendantNodes().Count()) +``` + + This example produces the following output: + +``` +nodes if not preserving whitespace: 48 +nodes if preserving whitespace: 82 +``` + ]]> @@ -1692,105 +1692,105 @@ nodes if preserving whitespace: 82 Loads an from an , optionally setting the base URI, and retaining line information. An that contains the XML that was read from the specified . - from a DOM document, and then using the to create an , this method can be used to create a copy of a DOM document in a LINQ to XML tree. - - Use to create an from a string that contains XML. - - Setting is not valid when loading from a . The will be configured to either read whitespace or not. The LINQ to XML tree will be populated with the whitespace nodes that the reader surfaces. This will be the behavior regardless of whether is set or not. - - The may have a valid base URI or not. If you set , the base URI will be set in the XML tree from the base URI that is reported by the . - - The may have a valid line information or not. If you set , the line information will be set in the XML tree from the line information that is reported by the . - - There is a performance penalty if you set the flag. - - The line information is accurate immediately after loading the XML document. If you modify the XML tree after loading the document, the line information may become meaningless. - - LINQ to XML's loading functionality is built upon . Therefore, you might catch any exceptions that are thrown by the overload methods and the methods that read and parse the document. - - - -## Examples - The following example loads the line information that it loads from the . It then prints the line information. - -```csharp -string markup = -@" - - - -"; - -// Create a reader and move to the content. -using (XmlReader nodeReader = XmlReader.Create(new StringReader(markup))) -{ - // the reader must be in the Interactive state in order to - // Create a LINQ to XML tree from it. - nodeReader.MoveToContent(); - - XDocument xRoot = XDocument.Load(nodeReader, LoadOptions.SetLineInfo); - Console.WriteLine("{0}{1}{2}", - "Element Name".PadRight(20), - "Line".PadRight(5), - "Position"); - Console.WriteLine("{0}{1}{2}", - "------------".PadRight(20), - "----".PadRight(5), - "--------"); - foreach (XElement e in xRoot.Elements("Root").DescendantsAndSelf()) - Console.WriteLine("{0}{1}{2}", - ("".PadRight(e.Ancestors().Count() * 2) + e.Name).PadRight(20), - ((IXmlLineInfo)e).LineNumber.ToString().PadRight(5), - ((IXmlLineInfo)e).LinePosition); -} -``` - -```vb -Dim markup As String = _ - "" & Environment.NewLine & _ - " " & Environment.NewLine & _ - " " & Environment.NewLine & _ - " " & Environment.NewLine & _ - "" - -' Create a reader and move to the content. -Using nodeReader As XmlReader = XmlReader.Create(New StringReader(markup)) - - ' The reader must be in the Interactive state in order to - ' create a LINQ to XML tree from it. - nodeReader.MoveToContent() - - Dim xRoot As XDocument = XDocument.Load(nodeReader, LoadOptions.SetLineInfo) - Console.WriteLine("{0}{1}{2}", _ - "Element Name".PadRight(20), _ - "Line".PadRight(5), _ - "Position") - Console.WriteLine("{0}{1}{2}", _ - "------------".PadRight(20), _ - "----".PadRight(5), _ - "--------") - For Each e As XElement In xRoot.Elements("Root").DescendantsAndSelf() - Console.WriteLine("{0}{1}{2}", _ - ("".PadRight(e.Ancestors().Count() * 2) & e.Name.ToString()).PadRight(20), _ - (DirectCast(e, IXmlLineInfo)).LineNumber.ToString().PadRight(5), _ - (DirectCast(e, IXmlLineInfo)).LinePosition) - Next -End Using -``` - - This example produces the following output: - -``` -Element Name Line Position ------------- ---- -------- -Root 1 2 - Child 2 6 - GrandChild 3 10 -``` - + from a DOM document, and then using the to create an , this method can be used to create a copy of a DOM document in a LINQ to XML tree. + + Use to create an from a string that contains XML. + + Setting is not valid when loading from a . The will be configured to either read whitespace or not. The LINQ to XML tree will be populated with the whitespace nodes that the reader surfaces. This will be the behavior regardless of whether is set or not. + + The may have a valid base URI or not. If you set , the base URI will be set in the XML tree from the base URI that is reported by the . + + The may have a valid line information or not. If you set , the line information will be set in the XML tree from the line information that is reported by the . + + There is a performance penalty if you set the flag. + + The line information is accurate immediately after loading the XML document. If you modify the XML tree after loading the document, the line information may become meaningless. + + LINQ to XML's loading functionality is built upon . Therefore, you might catch any exceptions that are thrown by the overload methods and the methods that read and parse the document. + + + +## Examples + The following example loads the line information that it loads from the . It then prints the line information. + +```csharp +string markup = +@" + + + +"; + +// Create a reader and move to the content. +using (XmlReader nodeReader = XmlReader.Create(new StringReader(markup))) +{ + // the reader must be in the Interactive state in order to + // Create a LINQ to XML tree from it. + nodeReader.MoveToContent(); + + XDocument xRoot = XDocument.Load(nodeReader, LoadOptions.SetLineInfo); + Console.WriteLine("{0}{1}{2}", + "Element Name".PadRight(20), + "Line".PadRight(5), + "Position"); + Console.WriteLine("{0}{1}{2}", + "------------".PadRight(20), + "----".PadRight(5), + "--------"); + foreach (XElement e in xRoot.Elements("Root").DescendantsAndSelf()) + Console.WriteLine("{0}{1}{2}", + ("".PadRight(e.Ancestors().Count() * 2) + e.Name).PadRight(20), + ((IXmlLineInfo)e).LineNumber.ToString().PadRight(5), + ((IXmlLineInfo)e).LinePosition); +} +``` + +```vb +Dim markup As String = _ + "" & Environment.NewLine & _ + " " & Environment.NewLine & _ + " " & Environment.NewLine & _ + " " & Environment.NewLine & _ + "" + +' Create a reader and move to the content. +Using nodeReader As XmlReader = XmlReader.Create(New StringReader(markup)) + + ' The reader must be in the Interactive state in order to + ' create a LINQ to XML tree from it. + nodeReader.MoveToContent() + + Dim xRoot As XDocument = XDocument.Load(nodeReader, LoadOptions.SetLineInfo) + Console.WriteLine("{0}{1}{2}", _ + "Element Name".PadRight(20), _ + "Line".PadRight(5), _ + "Position") + Console.WriteLine("{0}{1}{2}", _ + "------------".PadRight(20), _ + "----".PadRight(5), _ + "--------") + For Each e As XElement In xRoot.Elements("Root").DescendantsAndSelf() + Console.WriteLine("{0}{1}{2}", _ + ("".PadRight(e.Ancestors().Count() * 2) & e.Name.ToString()).PadRight(20), _ + (DirectCast(e, IXmlLineInfo)).LineNumber.ToString().PadRight(5), _ + (DirectCast(e, IXmlLineInfo)).LinePosition) + Next +End Using +``` + + This example produces the following output: + +``` +Element Name Line Position +------------ ---- -------- +Root 1 2 + Child 2 6 + GrandChild 3 10 +``` + ]]> @@ -1991,39 +1991,39 @@ This method stores in the task it returns all non-usage exceptions that the meth Gets the node type for this node. The node type. For objects, this value is . - contain a property, you can write code that operates on collections of objects where the type of each is a subclass of . Your code can then test for the node type of each object in the collection. - - - -## Examples - The following example shows the use of this property. - -```csharp -// Note that this property uses XmlNodeType, which is in the System.Xml namespace. -XDocument xmlTree = new XDocument( - new XDeclaration("1.0", "utf-8", "yes"), - new XElement("Root", "content") -); -Console.WriteLine(xmlTree.NodeType); -``` - -```vb -' Note that this property uses XmlNodeType, which is in the System.Xml namespace. -Dim xmlTree As XDocument = _ - - content -Console.WriteLine("{0}", xmlTree.NodeType) -``` - - This example produces the following output: - -``` -Document -``` - + contain a property, you can write code that operates on collections of objects where the type of each is a subclass of . Your code can then test for the node type of each object in the collection. + + + +## Examples + The following example shows the use of this property. + +```csharp +// Note that this property uses XmlNodeType, which is in the System.Xml namespace. +XDocument xmlTree = new XDocument( + new XDeclaration("1.0", "utf-8", "yes"), + new XElement("Root", "content") +); +Console.WriteLine(xmlTree.NodeType); +``` + +```vb +' Note that this property uses XmlNodeType, which is in the System.Xml namespace. +Dim xmlTree As XDocument = _ + + content +Console.WriteLine("{0}", xmlTree.NodeType) +``` + + This example produces the following output: + +``` +Document +``` + ]]> @@ -2040,48 +2040,48 @@ Document Creates a new from a string, optionally preserving white space, setting the base URI, and retaining line information. - . - -```csharp -string str = -@" - - - Content -"; -XDocument doc = XDocument.Parse(str); -Console.WriteLine(doc); -``` - -```vb -Dim str As String = _ - "" & _ - "" & _ - "" & _ - " Content" & _ - "" - -Dim doc As XDocument = XDocument.Parse(str) -Console.WriteLine(doc) -``` - - This example produces the following output: - -```xml - - - Content - -``` - + . + +```csharp +string str = +@" + + + Content +"; +XDocument doc = XDocument.Parse(str); +Console.WriteLine(doc); +``` + +```vb +Dim str As String = _ + "" & _ + "" & _ + "" & _ + " Content" & _ + "" + +Dim doc As XDocument = XDocument.Parse(str) +Console.WriteLine(doc) +``` + + This example produces the following output: + +```xml + + + Content + +``` + ]]> @@ -2140,52 +2140,52 @@ Console.WriteLine(doc) Creates a new from a string. An populated from the string that contains XML. - that takes as a parameter. - - For more information, see [Preserve white space while loading or parsing XML](/dotnet/standard/linq/preserve-white-space-loading-parsing-xml) and [Preserve white space while serializing](/dotnet/standard/linq/preserve-white-space-serializing). - - LINQ to XML's loading functionality is built upon . Therefore, you might catch any exceptions that are thrown by the overload methods and the methods that read and parse the document. - - - -## Examples - The following example creates a string that contains XML. It then parses the string into an . - -```csharp -string str = -@" - - - Content -"; -XDocument doc = XDocument.Parse(str); -Console.WriteLine(doc); -``` - -```vb -Dim str As String = _ - "" & _ - "" & _ - "" & _ - " Content" & _ - "" - -Dim doc As XDocument = XDocument.Parse(str) -Console.WriteLine(doc) -``` - - This example produces the following output: - -```xml - - - Content - -``` - + that takes as a parameter. + + For more information, see [Preserve white space while loading or parsing XML](/dotnet/standard/linq/preserve-white-space-loading-parsing-xml) and [Preserve white space while serializing](/dotnet/standard/linq/preserve-white-space-serializing). + + LINQ to XML's loading functionality is built upon . Therefore, you might catch any exceptions that are thrown by the overload methods and the methods that read and parse the document. + + + +## Examples + The following example creates a string that contains XML. It then parses the string into an . + +```csharp +string str = +@" + + + Content +"; +XDocument doc = XDocument.Parse(str); +Console.WriteLine(doc); +``` + +```vb +Dim str As String = _ + "" & _ + "" & _ + "" & _ + " Content" & _ + "" + +Dim doc As XDocument = XDocument.Parse(str) +Console.WriteLine(doc) +``` + + This example produces the following output: + +```xml + + + Content + +``` + ]]> @@ -2240,64 +2240,64 @@ Console.WriteLine(doc) Creates a new from a string, optionally preserving white space, setting the base URI, and retaining line information. An populated from the string that contains XML. - flag in `options` causes the reader to read all white space in the source XML. Nodes of type are created for both significant and insignificant white space. - - If the source XML is indented, not setting the flag in `options` causes the reader to ignore all of the insignificant white space in the source XML. The XML tree is created without any text nodes for insignificant white space. - - If the source XML is not indented, setting the flag in `options` has no effect. Significant white space is still preserved, and there are no spans of insignificant white space that could cause the creation of more white space text nodes. - - For more information, see [Preserve white space while loading or parsing XML](/dotnet/standard/linq/preserve-white-space-loading-parsing-xml) and [Preserve white space while serializing](/dotnet/standard/linq/preserve-white-space-serializing). - - Setting is not valid when parsing from a . - - There is a performance penalty if you set the flag. - - The line information is accurate immediately after loading the XML document. If you modify the XML tree after loading the document, the line information may become meaningless. - - LINQ to XML's loading functionality is built upon . Therefore, you might catch any exceptions that are thrown by the overload methods and the methods that read and parse the document. - - - -## Examples - The following example parses a string into an . - -```csharp -string str = -@" - - - Content -"; -XDocument doc1 = XDocument.Parse(str, LoadOptions.PreserveWhitespace); -Console.WriteLine("nodes when preserving whitespace: {0}", doc1.DescendantNodes().Count()); -XDocument doc2 = XDocument.Parse(str, LoadOptions.None); -Console.WriteLine("nodes when not preserving whitespace: {0}", doc2.DescendantNodes().Count()); -``` - -```vb -Dim str As String = _ -"" & Environment.NewLine & _ -"" & Environment.NewLine & _ -"" & Environment.NewLine & _ -" Content" & Environment.NewLine & _ -"" - -Dim doc1 As XDocument = XDocument.Parse(str, LoadOptions.PreserveWhitespace) -Console.WriteLine("nodes when preserving whitespace: {0}", doc1.DescendantNodes().Count()) -Dim doc2 As XDocument = XDocument.Parse(str, LoadOptions.None) -Console.WriteLine("nodes when not preserving whitespace: {0}", doc2.DescendantNodes().Count()) -``` - - This example produces the following output: - -``` -nodes when preserving whitespace: 8 -nodes when not preserving whitespace: 4 -``` - + flag in `options` causes the reader to read all white space in the source XML. Nodes of type are created for both significant and insignificant white space. + + If the source XML is indented, not setting the flag in `options` causes the reader to ignore all of the insignificant white space in the source XML. The XML tree is created without any text nodes for insignificant white space. + + If the source XML is not indented, setting the flag in `options` has no effect. Significant white space is still preserved, and there are no spans of insignificant white space that could cause the creation of more white space text nodes. + + For more information, see [Preserve white space while loading or parsing XML](/dotnet/standard/linq/preserve-white-space-loading-parsing-xml) and [Preserve white space while serializing](/dotnet/standard/linq/preserve-white-space-serializing). + + Setting is not valid when parsing from a . + + There is a performance penalty if you set the flag. + + The line information is accurate immediately after loading the XML document. If you modify the XML tree after loading the document, the line information may become meaningless. + + LINQ to XML's loading functionality is built upon . Therefore, you might catch any exceptions that are thrown by the overload methods and the methods that read and parse the document. + + + +## Examples + The following example parses a string into an . + +```csharp +string str = +@" + + + Content +"; +XDocument doc1 = XDocument.Parse(str, LoadOptions.PreserveWhitespace); +Console.WriteLine("nodes when preserving whitespace: {0}", doc1.DescendantNodes().Count()); +XDocument doc2 = XDocument.Parse(str, LoadOptions.None); +Console.WriteLine("nodes when not preserving whitespace: {0}", doc2.DescendantNodes().Count()); +``` + +```vb +Dim str As String = _ +"" & Environment.NewLine & _ +"" & Environment.NewLine & _ +"" & Environment.NewLine & _ +" Content" & Environment.NewLine & _ +"" + +Dim doc1 As XDocument = XDocument.Parse(str, LoadOptions.PreserveWhitespace) +Console.WriteLine("nodes when preserving whitespace: {0}", doc1.DescendantNodes().Count()) +Dim doc2 As XDocument = XDocument.Parse(str, LoadOptions.None) +Console.WriteLine("nodes when not preserving whitespace: {0}", doc2.DescendantNodes().Count()) +``` + + This example produces the following output: + +``` +nodes when preserving whitespace: 8 +nodes when not preserving whitespace: 4 +``` + ]]> @@ -2361,59 +2361,59 @@ nodes when not preserving whitespace: 4 Gets the root element of the XML Tree for this document. The root of the XML tree. - . See [Query an XDocument vs. query an XElement](/dotnet/standard/linq/query-xdocument-vs-query-xelement) for more details. - - - -## Examples - The following example uses this property to get the root element of a document. - -```csharp -XDocument doc = new XDocument( - new XComment("This is a comment."), - new XElement("Pubs", - new XElement("Book", - new XElement("Title", "Artifacts of Roman Civilization"), - new XElement("Author", "Moreno, Jordao") - ), - new XElement("Book", - new XElement("Title", "Midieval Tools and Implements"), - new XElement("Author", "Gazit, Inbar") - ) - ), - new XComment("This is another comment.") -); -Console.WriteLine(doc.Root.Name.ToString()); -``` - -```vb -Dim doc As XDocument = _ - - - - - Artifacts of Roman Civilization - Moreno, Jordao - - - Midieval Tools and Implements - Gazit, Inbar - - - - -Console.WriteLine(doc.Root.Name.ToString()) -``` - - This example produces the following output: - -``` -Pubs -``` - + . See [Query an XDocument vs. query an XElement](/dotnet/standard/linq/query-xdocument-vs-query-xelement) for more details. + + + +## Examples + The following example uses this property to get the root element of a document. + +```csharp +XDocument doc = new XDocument( + new XComment("This is a comment."), + new XElement("Pubs", + new XElement("Book", + new XElement("Title", "Artifacts of Roman Civilization"), + new XElement("Author", "Moreno, Jordao") + ), + new XElement("Book", + new XElement("Title", "Midieval Tools and Implements"), + new XElement("Author", "Gazit, Inbar") + ) + ), + new XComment("This is another comment.") +); +Console.WriteLine(doc.Root.Name.ToString()); +``` + +```vb +Dim doc As XDocument = _ + + + + + Artifacts of Roman Civilization + Moreno, Jordao + + + Midieval Tools and Implements + Gazit, Inbar + + + + +Console.WriteLine(doc.Root.Name.ToString()) +``` + + This example produces the following output: + +``` +Pubs +``` + ]]> LINQ to XML overview @@ -2477,15 +2477,15 @@ Pubs The stream to output this to. Outputs this to the specified . - that takes as a parameter. Use the option to save unindented XML. This will cause the writer to write all white spaces exactly as represented in the XML tree. - - Use option if you want to remove duplicate namespace declarations. - + that takes as a parameter. Use the option to save unindented XML. This will cause the writer to write all white spaces exactly as represented in the XML tree. + + Use option if you want to remove duplicate namespace declarations. + ]]> @@ -2532,52 +2532,52 @@ Pubs A that the will be written to. Serialize this to a . - that takes as a parameter. For more information, see [Preserve white space while loading or parsing XML](/dotnet/standard/linq/preserve-white-space-loading-parsing-xml) and [Preserve white space while serializing](/dotnet/standard/linq/preserve-white-space-serializing). - - - -## Examples - The following example creates an , saves the document to a , and then prints the string to the console. - -```csharp -StringBuilder sb = new StringBuilder(); - -XDocument doc = new XDocument( - new XElement("Root", - new XElement("Child", "content") - ) -); -TextWriter tr = new StringWriter(sb); -doc.Save(tr); -Console.WriteLine(sb.ToString()); -``` - -```vb -Dim sb As StringBuilder = New StringBuilder() - -Dim doc As XDocument = _ - - content - -Dim tr As TextWriter = New StringWriter(sb) -doc.Save(tr) -Console.WriteLine(sb.ToString()) -``` - - This example produces the following output: - -```xml - - - content - -``` - + that takes as a parameter. For more information, see [Preserve white space while loading or parsing XML](/dotnet/standard/linq/preserve-white-space-loading-parsing-xml) and [Preserve white space while serializing](/dotnet/standard/linq/preserve-white-space-serializing). + + + +## Examples + The following example creates an , saves the document to a , and then prints the string to the console. + +```csharp +StringBuilder sb = new StringBuilder(); + +XDocument doc = new XDocument( + new XElement("Root", + new XElement("Child", "content") + ) +); +TextWriter tr = new StringWriter(sb); +doc.Save(tr); +Console.WriteLine(sb.ToString()); +``` + +```vb +Dim sb As StringBuilder = New StringBuilder() + +Dim doc As XDocument = _ + + content + +Dim tr As TextWriter = New StringWriter(sb) +doc.Save(tr) +Console.WriteLine(sb.ToString()) +``` + + This example produces the following output: + +```xml + + + content + +``` + ]]> @@ -2621,52 +2621,52 @@ Console.WriteLine(sb.ToString()) System.Void - + A string that contains the name of the file. Serialize this to a file, overwriting an existing file, if it exists. - that takes as a parameter. For more information, see [Preserve white space while loading or parsing XML](/dotnet/standard/linq/preserve-white-space-loading-parsing-xml) and [Preserve white space while serializing](/dotnet/standard/linq/preserve-white-space-serializing). - - - -## Examples - The following example creates an , saves the document to a file, and then prints the file to the console. - -```csharp -XDocument doc = new XDocument( - new XElement("Root", - new XElement("Child", "content") - ) -); -doc.Save("Root.xml"); -Console.WriteLine(File.ReadAllText("Root.xml")); -``` - -```vb -Dim doc As XDocument = _ - - content - -doc.Save("Root.xml") -Console.WriteLine(File.ReadAllText("Root.xml")) -``` - - This example produces the following output: - -```xml - - - content - -``` - + that takes as a parameter. For more information, see [Preserve white space while loading or parsing XML](/dotnet/standard/linq/preserve-white-space-loading-parsing-xml) and [Preserve white space while serializing](/dotnet/standard/linq/preserve-white-space-serializing). + + + +## Examples + The following example creates an , saves the document to a file, and then prints the file to the console. + +```csharp +XDocument doc = new XDocument( + new XElement("Root", + new XElement("Child", "content") + ) +); +doc.Save("Root.xml"); +Console.WriteLine(File.ReadAllText("Root.xml")); +``` + +```vb +Dim doc As XDocument = _ + + content + +doc.Save("Root.xml") +Console.WriteLine(File.ReadAllText("Root.xml")) +``` + + This example produces the following output: + +```xml + + + content + +``` + ]]> @@ -2718,52 +2718,52 @@ Console.WriteLine(File.ReadAllText("Root.xml")) A that the will be written to. Serialize this to an . - to an . - -```csharp -StringBuilder sb = new StringBuilder(); -XmlWriterSettings xws = new XmlWriterSettings(); -xws.OmitXmlDeclaration = true; -xws.Indent = true; - -using (XmlWriter xw = XmlWriter.Create(sb, xws)) { - XDocument doc = new XDocument( - new XElement("Child", - new XElement("GrandChild", "some content") - ) - ); - doc.Save(xw); -} - -Console.WriteLine(sb.ToString()); -``` - -```vb -Dim sb As StringBuilder = New StringBuilder() -Dim xws As XmlWriterSettings = New XmlWriterSettings() -xws.OmitXmlDeclaration = True -xws.Indent = True - -Using xw = XmlWriter.Create(sb, xws) - Dim doc As XDocument = New XDocument(some content) - doc.Save(xw) - -End Using - -Console.WriteLine(sb.ToString()) -``` - - This example produces the following output: - -```xml - - some content - -``` - + to an . + +```csharp +StringBuilder sb = new StringBuilder(); +XmlWriterSettings xws = new XmlWriterSettings(); +xws.OmitXmlDeclaration = true; +xws.Indent = true; + +using (XmlWriter xw = XmlWriter.Create(sb, xws)) { + XDocument doc = new XDocument( + new XElement("Child", + new XElement("GrandChild", "some content") + ) + ); + doc.Save(xw); +} + +Console.WriteLine(sb.ToString()); +``` + +```vb +Dim sb As StringBuilder = New StringBuilder() +Dim xws As XmlWriterSettings = New XmlWriterSettings() +xws.OmitXmlDeclaration = True +xws.Indent = True + +Using xw = XmlWriter.Create(sb, xws) + Dim doc As XDocument = New XDocument(some content) + doc.Save(xw) + +End Using + +Console.WriteLine(sb.ToString()) +``` + + This example produces the following output: + +```xml + + some content + +``` + ]]> @@ -2816,15 +2816,15 @@ Console.WriteLine(sb.ToString()) A that specifies formatting behavior. Outputs this to the specified , optionally specifying formatting behavior. - . This option will remove all extraneous insignificant white space, and add appropriate insignificant white space so that the XML is properly indented. - - If you want to save unindented XML, specify the flag for `options`. This will cause the writer to write all white spaces exactly as represented in the XML tree. - - Use option if you want to remove duplicate namespace declarations. - + . This option will remove all extraneous insignificant white space, and add appropriate insignificant white space so that the XML is properly indented. + + If you want to save unindented XML, specify the flag for `options`. This will cause the writer to write all white spaces exactly as represented in the XML tree. + + Use option if you want to remove duplicate namespace declarations. + ]]> @@ -2873,69 +2873,69 @@ Console.WriteLine(sb.ToString()) A that specifies formatting behavior. Serialize this to a , optionally disabling formatting. - flag for `options`. This will cause the writer to write all white space exactly as represented in the XML tree. - - If you want to save indented XML, do not specify the flag for `options`. This will remove all extraneous insignificant white space, and add appropriate insignificant white space so that the XML is properly indented. This is the default behavior, and the behavior of the overloads of the methods that do not take `options` as a parameter. - - For more information, see [Preserve white space while loading or parsing XML](/dotnet/standard/linq/preserve-white-space-loading-parsing-xml) and [Preserve white space while serializing](/dotnet/standard/linq/preserve-white-space-serializing). - - - -## Examples - The following example shows two uses of this method. The first use serializes the with formatting. The second preserves white space. Because the document has no white space in it as constructed, preserving white space outputs the XML without any indenting. - -```csharp -XDocument doc = new XDocument( - new XElement("Root", - new XElement("Child", "content") - ) -); -StringBuilder sb1 = new StringBuilder(); -using (StringWriter sr1 = new StringWriter(sb1)) { - doc.Save(sr1, SaveOptions.None); - Console.WriteLine(sb1.ToString()); -} - -StringBuilder sb2 = new StringBuilder(); -using (StringWriter sr2 = new StringWriter(sb2)) { - doc.Save(sr2, SaveOptions.DisableFormatting); - Console.WriteLine(sb2.ToString()); -} -``` - -```vb -Dim doc As XDocument = _ - - content - -Dim sb1 As StringBuilder = New StringBuilder() - -Using sr1 = New StringWriter(sb1) - doc.Save(sr1, SaveOptions.None) - Console.WriteLine(sb1.ToString()) -End Using - -Dim sb2 As StringBuilder = New StringBuilder() - -Using sr2 = New StringWriter(sb2) - doc.Save(sr2, SaveOptions.DisableFormatting) - Console.WriteLine(sb2.ToString()) -End Using -``` - - This example produces the following output: - -``` - - - content - -content -``` - + flag for `options`. This will cause the writer to write all white space exactly as represented in the XML tree. + + If you want to save indented XML, do not specify the flag for `options`. This will remove all extraneous insignificant white space, and add appropriate insignificant white space so that the XML is properly indented. This is the default behavior, and the behavior of the overloads of the methods that do not take `options` as a parameter. + + For more information, see [Preserve white space while loading or parsing XML](/dotnet/standard/linq/preserve-white-space-loading-parsing-xml) and [Preserve white space while serializing](/dotnet/standard/linq/preserve-white-space-serializing). + + + +## Examples + The following example shows two uses of this method. The first use serializes the with formatting. The second preserves white space. Because the document has no white space in it as constructed, preserving white space outputs the XML without any indenting. + +```csharp +XDocument doc = new XDocument( + new XElement("Root", + new XElement("Child", "content") + ) +); +StringBuilder sb1 = new StringBuilder(); +using (StringWriter sr1 = new StringWriter(sb1)) { + doc.Save(sr1, SaveOptions.None); + Console.WriteLine(sb1.ToString()); +} + +StringBuilder sb2 = new StringBuilder(); +using (StringWriter sr2 = new StringWriter(sb2)) { + doc.Save(sr2, SaveOptions.DisableFormatting); + Console.WriteLine(sb2.ToString()); +} +``` + +```vb +Dim doc As XDocument = _ + + content + +Dim sb1 As StringBuilder = New StringBuilder() + +Using sr1 = New StringWriter(sb1) + doc.Save(sr1, SaveOptions.None) + Console.WriteLine(sb1.ToString()) +End Using + +Dim sb2 As StringBuilder = New StringBuilder() + +Using sr2 = New StringWriter(sb2) + doc.Save(sr2, SaveOptions.DisableFormatting) + Console.WriteLine(sb2.ToString()) +End Using +``` + + This example produces the following output: + +``` + + + content + +content +``` + ]]> @@ -2979,61 +2979,61 @@ End Using System.Void - - + + A string that contains the name of the file. A that specifies formatting behavior. Serialize this to a file, optionally disabling formatting. - flag for `options`. This will cause the writer to write all white space exactly as represented in the XML tree. - - If you want to save indented XML, do not specify the flag for `options`. This will remove all extraneous insignificant white space, and add appropriate insignificant white space so that the XML is properly indented. This is the default behavior, and the behavior of the overloads of the methods that do not take `options` as a parameter. - - For more information, see [Preserve white space while loading or parsing XML](/dotnet/standard/linq/preserve-white-space-loading-parsing-xml) and [Preserve white space while serializing](/dotnet/standard/linq/preserve-white-space-serializing). - - - -## Examples - The following example shows two uses of this method. The first use preserves white space. The second one serializes the with indenting. - -```csharp -XDocument doc = new XDocument( - new XElement("Root", - new XElement("Child", "content") - ) -); -doc.Save("Root1.xml", SaveOptions.DisableFormatting); -Console.WriteLine(File.ReadAllText("Root1.xml")); -doc.Save("Root2.xml", SaveOptions.None); -Console.WriteLine(File.ReadAllText("Root2.xml")); -``` - -```vb -Dim doc As XDocument = _ - - content - -doc.Save("Root1.xml", SaveOptions.DisableFormatting) -Console.WriteLine(File.ReadAllText("Root1.xml")) -doc.Save("Root2.xml", SaveOptions.None) -Console.WriteLine(File.ReadAllText("Root2.xml")) -``` - - This example produces the following output: - -``` -content - - - content - -``` - + flag for `options`. This will cause the writer to write all white space exactly as represented in the XML tree. + + If you want to save indented XML, do not specify the flag for `options`. This will remove all extraneous insignificant white space, and add appropriate insignificant white space so that the XML is properly indented. This is the default behavior, and the behavior of the overloads of the methods that do not take `options` as a parameter. + + For more information, see [Preserve white space while loading or parsing XML](/dotnet/standard/linq/preserve-white-space-loading-parsing-xml) and [Preserve white space while serializing](/dotnet/standard/linq/preserve-white-space-serializing). + + + +## Examples + The following example shows two uses of this method. The first use preserves white space. The second one serializes the with indenting. + +```csharp +XDocument doc = new XDocument( + new XElement("Root", + new XElement("Child", "content") + ) +); +doc.Save("Root1.xml", SaveOptions.DisableFormatting); +Console.WriteLine(File.ReadAllText("Root1.xml")); +doc.Save("Root2.xml", SaveOptions.None); +Console.WriteLine(File.ReadAllText("Root2.xml")); +``` + +```vb +Dim doc As XDocument = _ + + content + +doc.Save("Root1.xml", SaveOptions.DisableFormatting) +Console.WriteLine(File.ReadAllText("Root1.xml")) +doc.Save("Root2.xml", SaveOptions.None) +Console.WriteLine(File.ReadAllText("Root2.xml")) +``` + + This example produces the following output: + +``` +content + + + content + +``` + ]]> @@ -3126,7 +3126,7 @@ Console.WriteLine(File.ReadAllText("Root2.xml")) Output this to a . A task representing the asynchronous save operation. - An into which this method will write. Write this document to an . - to an . Note that the example did not write an XML declaration. - -```csharp -StringBuilder sb = new StringBuilder(); -XmlWriterSettings xws = new XmlWriterSettings(); -xws.OmitXmlDeclaration = true; -xws.Indent = true; - -using (XmlWriter xw = XmlWriter.Create(sb, xws)) -{ - XDocument doc = new XDocument( - new XElement("Child", - new XElement("GrandChild", "some content") - ) - ); - doc.WriteTo(xw); -} - -Console.WriteLine(sb.ToString()); -``` - -```vb -Dim sb As StringBuilder = New StringBuilder() -Dim xws As XmlWriterSettings = New XmlWriterSettings() -xws.OmitXmlDeclaration = True -xws.Indent = True - -Using xw = XmlWriter.Create(sb, xws) - Dim doc As XDocument = New XDocument(some content) - doc.WriteTo(xw) -End Using - -Console.WriteLine(sb.ToString()) -``` - - This example produces the following output: - -```xml - - some content - -``` - + to an . Note that the example did not write an XML declaration. + +```csharp +StringBuilder sb = new StringBuilder(); +XmlWriterSettings xws = new XmlWriterSettings(); +xws.OmitXmlDeclaration = true; +xws.Indent = true; + +using (XmlWriter xw = XmlWriter.Create(sb, xws)) +{ + XDocument doc = new XDocument( + new XElement("Child", + new XElement("GrandChild", "some content") + ) + ); + doc.WriteTo(xw); +} + +Console.WriteLine(sb.ToString()); +``` + +```vb +Dim sb As StringBuilder = New StringBuilder() +Dim xws As XmlWriterSettings = New XmlWriterSettings() +xws.OmitXmlDeclaration = True +xws.Indent = True + +Using xw = XmlWriter.Create(sb, xws) + Dim doc As XDocument = New XDocument(some content) + doc.WriteTo(xw) +End Using + +Console.WriteLine(sb.ToString()) +``` + + This example produces the following output: + +```xml + + some content + +``` + ]]> diff --git a/xml/System.Xml.Linq/XElement.xml b/xml/System.Xml.Linq/XElement.xml index 98f10fe30a6..fde739c9a25 100644 --- a/xml/System.Xml.Linq/XElement.xml +++ b/xml/System.Xml.Linq/XElement.xml @@ -79,141 +79,141 @@ Represents an XML element. See XElement Class Overview and the Remarks section on this page for usage information and examples. - , optionally one or more attributes, and can optionally contain content (for more information, see ). - - An can contain the following types of content: - -- - -- - -- - -- - - For details about the valid content of an , see [Valid Content of XElement and XDocument Objects](/dotnet/standard/linq/valid-content-xelement-xdocument-objects). - - derives from , which derives from . - - Some methods can be used from XAML. For more information, see [LINQ to XML Dynamic Properties](/dotnet/desktop/wpf/data/linq-to-xml-dynamic-properties). - - - -## Examples - The following example creates an XML tree. The content of the new element comes from a LINQ query. - -```csharp -XElement xmlTree1 = new XElement("Root", - new XElement("Child1", 1), - new XElement("Child2", 2), - new XElement("Child3", 3), - new XElement("Child4", 4), - new XElement("Child5", 5), - new XElement("Child6", 6) -); - -XElement xmlTree2 = new XElement("Root", - from el in xmlTree1.Elements() - where((int)el >= 3 && (int)el <= 5) - select el -); -Console.WriteLine(xmlTree2); -``` - -```vb -Dim xmlTree1 As XElement = _ - - 1 - 2 - 3 - 4 - 5 - 6 - - -Dim xmlTree2 As XElement = _ - - <%= From el In xmlTree1.Elements() _ - Where el.Value >= 3 And el.Value <= 5 _ - Select el %> - - -Console.WriteLine(xmlTree2) -``` - - This example produces the following output: - -```xml - - 3 - 4 - 5 - -``` - - The following is the same example, but in this case the XML is in a namespace. For more information, see [Work with XML Namespaces](/dotnet/standard/linq/namespaces-overview). - -```csharp -XNamespace aw = "http://www.adventure-works.com"; -XElement xmlTree1 = new XElement(aw + "Root", - new XElement(aw + "Child1", 1), - new XElement(aw + "Child2", 2), - new XElement(aw + "Child3", 3), - new XElement(aw + "Child4", 4), - new XElement(aw + "Child5", 5), - new XElement(aw + "Child6", 6) -); - -XElement xmlTree2 = new XElement(aw + "Root", - from el in xmlTree1.Elements() - where((int)el >= 3 && (int)el <= 5) - select el -); -Console.WriteLine(xmlTree2); -``` - -```vb -Imports - -Module Module1 - Sub Main() - Dim xmlTree1 As XElement = _ - - 1 - 2 - 3 - 4 - 5 - 6 - - - Dim xmlTree2 As XElement = _ - - <%= From el In xmlTree1.Elements() _ - Where el.Value >= 3 And el.Value <= 5 _ - Select el %> - - - Console.WriteLine(xmlTree2) - End SUb -End Module -``` - - This example produces the following output: - -```xml - - 3 - 4 - 5 - -``` - + , optionally one or more attributes, and can optionally contain content (for more information, see ). + + An can contain the following types of content: + +- + +- + +- + +- + + For details about the valid content of an , see [Valid Content of XElement and XDocument Objects](/dotnet/standard/linq/valid-content-xelement-xdocument-objects). + + derives from , which derives from . + + Some methods can be used from XAML. For more information, see [LINQ to XML Dynamic Properties](/dotnet/desktop/wpf/data/linq-to-xml-dynamic-properties). + + + +## Examples + The following example creates an XML tree. The content of the new element comes from a LINQ query. + +```csharp +XElement xmlTree1 = new XElement("Root", + new XElement("Child1", 1), + new XElement("Child2", 2), + new XElement("Child3", 3), + new XElement("Child4", 4), + new XElement("Child5", 5), + new XElement("Child6", 6) +); + +XElement xmlTree2 = new XElement("Root", + from el in xmlTree1.Elements() + where((int)el >= 3 && (int)el <= 5) + select el +); +Console.WriteLine(xmlTree2); +``` + +```vb +Dim xmlTree1 As XElement = _ + + 1 + 2 + 3 + 4 + 5 + 6 + + +Dim xmlTree2 As XElement = _ + + <%= From el In xmlTree1.Elements() _ + Where el.Value >= 3 And el.Value <= 5 _ + Select el %> + + +Console.WriteLine(xmlTree2) +``` + + This example produces the following output: + +```xml + + 3 + 4 + 5 + +``` + + The following is the same example, but in this case the XML is in a namespace. For more information, see [Work with XML Namespaces](/dotnet/standard/linq/namespaces-overview). + +```csharp +XNamespace aw = "http://www.adventure-works.com"; +XElement xmlTree1 = new XElement(aw + "Root", + new XElement(aw + "Child1", 1), + new XElement(aw + "Child2", 2), + new XElement(aw + "Child3", 3), + new XElement(aw + "Child4", 4), + new XElement(aw + "Child5", 5), + new XElement(aw + "Child6", 6) +); + +XElement xmlTree2 = new XElement(aw + "Root", + from el in xmlTree1.Elements() + where((int)el >= 3 && (int)el <= 5) + select el +); +Console.WriteLine(xmlTree2); +``` + +```vb +Imports + +Module Module1 + Sub Main() + Dim xmlTree1 As XElement = _ + + 1 + 2 + 3 + 4 + 5 + 6 + + + Dim xmlTree2 As XElement = _ + + <%= From el In xmlTree1.Elements() _ + Where el.Value >= 3 And el.Value <= 5 _ + Select el %> + + + Console.WriteLine(xmlTree2) + End SUb +End Module +``` + + This example produces the following output: + +```xml + + 3 + 4 + 5 + +``` + ]]> LINQ to XML overview @@ -229,69 +229,69 @@ End Module Initializes a new instance of the class. - . Typical use of this constructor is to specify a string as the parameter instead of creating a new . - - When creating an element in a namespace, typical use is to use the addition operator overload with an and a string to create an . For more information, see [Work with XML Namespaces](/dotnet/standard/linq/namespaces-overview). - - - -## Examples - The following example creates an XML tree. The content of the new element comes from a LINQ query. - -```csharp -XElement xmlTree1 = new XElement("Root", - new XElement("Child", 1), - new XElement("Child", 2), - new XElement("Child", 3), - new XElement("Child", 4), - new XElement("Child", 5), - new XElement("Child", 6) -); - -XElement xmlTree2 = new XElement("Root", - from el in xmlTree1.Elements() - where((int)el >= 3 && (int)el <= 5) - select el -); -Console.WriteLine(xmlTree2); -``` - -```vb -Dim xmlTree1 As XElement = _ - - 1 - 2 - 3 - 4 - 5 - 6 - - -Dim xmlTree2 As XElement = _ - - <%= From el In xmlTree1.Elements() _ - Where el.Value >= 3 And el.Value <= 5 _ - Select el %> - - -Console.WriteLine(xmlTree2) -``` - - This example produces the following output: - -```xml - - 3 - 4 - 5 - -``` - + . Typical use of this constructor is to specify a string as the parameter instead of creating a new . + + When creating an element in a namespace, typical use is to use the addition operator overload with an and a string to create an . For more information, see [Work with XML Namespaces](/dotnet/standard/linq/namespaces-overview). + + + +## Examples + The following example creates an XML tree. The content of the new element comes from a LINQ query. + +```csharp +XElement xmlTree1 = new XElement("Root", + new XElement("Child", 1), + new XElement("Child", 2), + new XElement("Child", 3), + new XElement("Child", 4), + new XElement("Child", 5), + new XElement("Child", 6) +); + +XElement xmlTree2 = new XElement("Root", + from el in xmlTree1.Elements() + where((int)el >= 3 && (int)el <= 5) + select el +); +Console.WriteLine(xmlTree2); +``` + +```vb +Dim xmlTree1 As XElement = _ + + 1 + 2 + 3 + 4 + 5 + 6 + + +Dim xmlTree2 As XElement = _ + + <%= From el In xmlTree1.Elements() _ + Where el.Value >= 3 And el.Value <= 5 _ + Select el %> + + +Console.WriteLine(xmlTree2) +``` + + This example produces the following output: + +```xml + + 3 + 4 + 5 + +``` + ]]> LINQ to XML overview @@ -336,59 +336,59 @@ Console.WriteLine(xmlTree2) An object to copy from. Initializes a new instance of the class from another object. - , which tests whether the two XML trees are equal. - -```csharp -XElement xmlTree = new XElement("Root", - new XAttribute("Att1", 1), - new XElement("Child1", 1), - new XElement("Child2", 2) -); - -// Create a clone of the tree. -XElement treeClone = new XElement(xmlTree); - -Console.WriteLine("xmlTree = treeClone: {0}", XNode.DeepEquals(xmlTree, treeClone)); - -// Do some work with xmlTree, perhaps pass it to other methods. -xmlTree.Add(new XElement("Child3", 3)); - -Console.WriteLine("xmlTree = treeClone: {0}", XNode.DeepEquals(xmlTree, treeClone)); -``` - -```vb -Dim xmlTree As XElement = _ - - 1 - 2 - - -' Create a clone of the tree. -Dim treeClone As XElement = New XElement(xmlTree) - -Console.WriteLine("xmlTree = treeClone: {0}", XNode.DeepEquals(xmlTree, treeClone)) - -' Do some work with xmlTree, perhaps pass it to other methods. -xmlTree.Add(New XElement("Child3", 3)) - -Console.WriteLine("xmlTree = treeClone: {0}", XNode.DeepEquals(xmlTree, treeClone)) -``` - - This example produces the following output: - -``` -xmlTree = treeClone: True -xmlTree = treeClone: False -``` - + , which tests whether the two XML trees are equal. + +```csharp +XElement xmlTree = new XElement("Root", + new XAttribute("Att1", 1), + new XElement("Child1", 1), + new XElement("Child2", 2) +); + +// Create a clone of the tree. +XElement treeClone = new XElement(xmlTree); + +Console.WriteLine("xmlTree = treeClone: {0}", XNode.DeepEquals(xmlTree, treeClone)); + +// Do some work with xmlTree, perhaps pass it to other methods. +xmlTree.Add(new XElement("Child3", 3)); + +Console.WriteLine("xmlTree = treeClone: {0}", XNode.DeepEquals(xmlTree, treeClone)); +``` + +```vb +Dim xmlTree As XElement = _ + + 1 + 2 + + +' Create a clone of the tree. +Dim treeClone As XElement = New XElement(xmlTree) + +Console.WriteLine("xmlTree = treeClone: {0}", XNode.DeepEquals(xmlTree, treeClone)) + +' Do some work with xmlTree, perhaps pass it to other methods. +xmlTree.Add(New XElement("Child3", 3)) + +Console.WriteLine("xmlTree = treeClone: {0}", XNode.DeepEquals(xmlTree, treeClone)) +``` + + This example produces the following output: + +``` +xmlTree = treeClone: True +xmlTree = treeClone: False +``` + ]]> LINQ to XML overview @@ -433,59 +433,59 @@ xmlTree = treeClone: False An that contains the name of the element. Initializes a new instance of the class with the specified name. - . Typical use of this constructor is to specify a string as the parameter instead of creating a new . When creating an element in a namespace, typical use is to use the addition operator overload with an and a string to create an . For more information, see [Work with XML Namespaces](/dotnet/standard/linq/namespaces-overview). - - - -## Examples - The following example creates an element with no content. - -```csharp -XElement el = new XElement("Root"); -Console.WriteLine(el); -``` - -```vb -Dim el As XElement = -Console.WriteLine(el) -``` - - This example produces the following output: - -```xml - -``` - - The following example creates an element in a namespace with no content. For more information, see [Work with XML Namespaces](/dotnet/standard/linq/namespaces-overview). - + . Typical use of this constructor is to specify a string as the parameter instead of creating a new . When creating an element in a namespace, typical use is to use the addition operator overload with an and a string to create an . For more information, see [Work with XML Namespaces](/dotnet/standard/linq/namespaces-overview). + + + +## Examples + The following example creates an element with no content. + ```csharp -XNamespace aw = "http://www.adventure-works.com"; -XElement root = new XElement(aw + "Root"); -Console.WriteLine(root); -``` - -```vb -Imports - -Module Module1 - Sub Main() - Dim root = - Console.WriteLine(root) - End Sub -End Module -``` - - This example produces the following output: - -```xml - -``` - +XElement el = new XElement("Root"); +Console.WriteLine(el); +``` + +```vb +Dim el As XElement = +Console.WriteLine(el) +``` + + This example produces the following output: + +```xml + +``` + + The following example creates an element in a namespace with no content. For more information, see [Work with XML Namespaces](/dotnet/standard/linq/namespaces-overview). + +```csharp +XNamespace aw = "http://www.adventure-works.com"; +XElement root = new XElement(aw + "Root"); +Console.WriteLine(root); +``` + +```vb +Imports + +Module Module1 + Sub Main() + Dim root = + Console.WriteLine(root) + End Sub +End Module +``` + + This example produces the following output: + +```xml + +``` + ]]> LINQ to XML overview @@ -530,66 +530,66 @@ End Module An that contains unevaluated queries that will be iterated for the contents of this . Initializes a new instance of the class from an object. - , and creates an element with its contents. - - - -## Examples - The following example creates a source XML tree, and then creates an from a query on the source XML tree. It then serializes the to the console, adds a new element to the source XML tree, and then serializes the again. You can see that element newly added to the source XML tree is not included in the first serialization, but is included in the second. - -```csharp -XElement src = new XElement("Root", - new XElement("Child1", 1), - new XElement("Child2", 2), - new XElement("Child3", 3) - ); -XStreamingElement xse = new XStreamingElement("NewRoot", - from el in src.Elements() - where (int)el >= 2 - select el - ); -Console.WriteLine(xse); -src.Add(new XElement("Child4", 4)); -Console.WriteLine("----"); -Console.WriteLine(xse); -``` - -```vb -Dim src As XElement = _ - - 1 - 2 - 3 - -Dim xse As XStreamingElement = New XStreamingElement("NewRoot", _ - From el In src.Elements() _ - Where (CInt(el) >= 2) _ - Select el _ -) -Console.WriteLine(xse) -src.Add(New XElement("Child4", 4)) -Console.WriteLine("----") -Console.WriteLine(xse) -``` - - This example produces the following output: - -``` - - 2 - 3 - ----- - - 2 - 3 - 4 - -``` - + , and creates an element with its contents. + + + +## Examples + The following example creates a source XML tree, and then creates an from a query on the source XML tree. It then serializes the to the console, adds a new element to the source XML tree, and then serializes the again. You can see that element newly added to the source XML tree is not included in the first serialization, but is included in the second. + +```csharp +XElement src = new XElement("Root", + new XElement("Child1", 1), + new XElement("Child2", 2), + new XElement("Child3", 3) + ); +XStreamingElement xse = new XStreamingElement("NewRoot", + from el in src.Elements() + where (int)el >= 2 + select el + ); +Console.WriteLine(xse); +src.Add(new XElement("Child4", 4)); +Console.WriteLine("----"); +Console.WriteLine(xse); +``` + +```vb +Dim src As XElement = _ + + 1 + 2 + 3 + +Dim xse As XStreamingElement = New XStreamingElement("NewRoot", _ + From el In src.Elements() _ + Where (CInt(el) >= 2) _ + Select el _ +) +Console.WriteLine(xse) +src.Add(New XElement("Child4", 4)) +Console.WriteLine("----") +Console.WriteLine(xse) +``` + + This example produces the following output: + +``` + + 2 + 3 + +---- + + 2 + 3 + 4 + +``` + ]]> LINQ to XML overview @@ -644,277 +644,277 @@ Console.WriteLine(xse) The contents of the element. Initializes a new instance of the class with the specified name and content. - . Typical use of this constructor is to specify a string as the parameter instead of creating a new . - - When creating an element in a namespace, typical use is to use the addition operator overload with an and a string to create an . For more information, see [Work with XML Namespaces](/dotnet/standard/linq/namespaces-overview). - - For details about the valid content that can be passed to this constructor, see [Valid Content of XElement and XDocument Objects](/dotnet/standard/linq/valid-content-xelement-xdocument-objects). - - - -## Examples - The following example creates an XML tree. The content of the new element comes from a LINQ query. - -```csharp -XElement xmlTree1 = new XElement("Root", - new XElement("Child1", 1), - new XElement("Child2", 2), - new XElement("Child3", 3), - new XElement("Child4", 4), - new XElement("Child5", 5), - new XElement("Child6", 6) -); - -XElement xmlTree2 = new XElement("Root", - from el in xmlTree1.Elements() - where((int)el >= 3 && (int)el <= 5) - select el -); -Console.WriteLine(xmlTree2); -``` - -```vb -Dim xmlTree1 As XElement = _ - - 1 - 2 - 3 - 4 - 5 - 6 - - -Dim xmlTree2 As XElement = _ - - <%= From el In xmlTree1.Elements() _ - Where el.Value >= 3 And el.Value <= 5 _ - Select el %> - - -Console.WriteLine(xmlTree2) -``` - - This example produces the following output: - -```xml - - 3 - 4 - 5 - -``` - - The following example creates an XML tree with a variety of types of content. - -```csharp -XElement root; - -// String content: -root = new XElement("Root", "Some text"); -Console.WriteLine(root); - -// XElement object content: -root = new XElement("Root", - new XElement("NewChild", "n") -); -Console.WriteLine(root); - -// XAttribute object content: -root = new XElement("Root", - new XAttribute("NewAttribute", "n") -); -Console.WriteLine(root); - -// Double content: -double dbl = 12.345; -root = new XElement("Root", dbl); -Console.WriteLine(root); - -// DateTime content: -DateTime dt = new DateTime(2006, 10, 6, 12, 30, 00); -root = new XElement("Root", dt); -Console.WriteLine(root); - -// String array content: -// Any collection other than a collection of XElement or XAttribute objects -// are converted to strings. The strings are concatenated and added. -string[] stringArray = { - "abc", - "def", - "ghi" -}; -root = new XElement("Root", stringArray); -Console.WriteLine(root); - -// XElement object array content: -XElement[] ellArray = { - new XElement("NewChild1", 1), - new XElement("NewChild2", 2), - new XElement("NewChild3", 3) -}; -root = new XElement("Root", ellArray); -Console.WriteLine(root); - -// XAttribute object array content: -XAttribute[] attArray = { - new XAttribute("NewAtt1", 1), - new XAttribute("NewAtt2", 2), - new XAttribute("NewAtt3", 3) -}; -root = new XElement("Root", attArray); -Console.WriteLine(root); -``` - -```vb -Dim root As XElement - -' String content: -root = Some text -Console.WriteLine(root) - -' XElement object content: -root = - n - -Console.WriteLine(root) - -' XAttribute object content: -root = -Console.WriteLine(root) - -' Double content: -Dim dbl As Double = 12.345 -root = <%= dbl %> -Console.WriteLine(root) - -' DateTime content: -Dim dt As DateTime = New DateTime(2006, 10, 6, 12, 30, 0) -root = <%= dt %> -Console.WriteLine(root) - -' String array content: -' Any collection other than a collection of XElement or XAttribute objects -' are converted to strings. The strings are concatenated and added. - -Dim stringArray As String() = { _ - "abc", _ - "def", _ - "ghi" _ -} -root = <%= stringArray %> -Console.WriteLine(root) - -' XElement object array content: -Dim ellArray As XElement() = { _ - 1, _ - 2, _ - 3 _ -} - -root = <%= ellArray %> -Console.WriteLine(root) - -' XAttribute object array content -Dim attArray As XAttribute() = { _ - New XAttribute("NewAtt1", 1), _ - New XAttribute("NewAtt2", 2), _ - New XAttribute("NewAtt3", 3) _ -} -root = <%= attArray %> -Console.WriteLine(root) -``` - - This example produces the following output: - + . Typical use of this constructor is to specify a string as the parameter instead of creating a new . + + When creating an element in a namespace, typical use is to use the addition operator overload with an and a string to create an . For more information, see [Work with XML Namespaces](/dotnet/standard/linq/namespaces-overview). + + For details about the valid content that can be passed to this constructor, see [Valid Content of XElement and XDocument Objects](/dotnet/standard/linq/valid-content-xelement-xdocument-objects). + + + +## Examples + The following example creates an XML tree. The content of the new element comes from a LINQ query. + +```csharp +XElement xmlTree1 = new XElement("Root", + new XElement("Child1", 1), + new XElement("Child2", 2), + new XElement("Child3", 3), + new XElement("Child4", 4), + new XElement("Child5", 5), + new XElement("Child6", 6) +); + +XElement xmlTree2 = new XElement("Root", + from el in xmlTree1.Elements() + where((int)el >= 3 && (int)el <= 5) + select el +); +Console.WriteLine(xmlTree2); +``` + +```vb +Dim xmlTree1 As XElement = _ + + 1 + 2 + 3 + 4 + 5 + 6 + + +Dim xmlTree2 As XElement = _ + + <%= From el In xmlTree1.Elements() _ + Where el.Value >= 3 And el.Value <= 5 _ + Select el %> + + +Console.WriteLine(xmlTree2) +``` + + This example produces the following output: + ```xml -Some text - - n - - -12.345 -2006-10-06T12:30:00 -abcdefghi - - 1 - 2 - 3 - - -``` - - The following example creates an XML tree in a namespace. - -```csharp -// Create an XML tree in a namespace. -XNamespace aw = "http://www.adventure-works.com"; -XElement root = new XElement(aw + "Root", - new XElement(aw + "Child", "child content") -); -Console.WriteLine(root); -``` - -```vb -' Create an XML tree in a namespace. -Dim root As XElement = _ - - child content - -Console.WriteLine(root) -``` - - This example produces the following output: - -```xml - - child content - -``` - - The following example creates an XML tree with nested namespaces. - -```csharp -// Create an XML tree with nested namespaces. -XNamespace aw = "http://www.adventure-works.com"; -XNamespace fc = "www.fourthcoffee.com"; -XDocument root = new XDocument( - new XDeclaration("1.0", "utf-8", "yes"), - new XElement(aw + "Root", - new XElement(fc + "Child", - new XElement(aw + "DifferentChild", "other content") - ) - ) -); -Console.WriteLine(root); -``` - -```vb -' Create an XML tree with nested namespaces. -Dim root As XDocument = _ - - - - other content - - -Console.WriteLine(root) -``` - - This example produces the following output: - -```xml - - - other content - - -``` - + + 3 + 4 + 5 + +``` + + The following example creates an XML tree with a variety of types of content. + +```csharp +XElement root; + +// String content: +root = new XElement("Root", "Some text"); +Console.WriteLine(root); + +// XElement object content: +root = new XElement("Root", + new XElement("NewChild", "n") +); +Console.WriteLine(root); + +// XAttribute object content: +root = new XElement("Root", + new XAttribute("NewAttribute", "n") +); +Console.WriteLine(root); + +// Double content: +double dbl = 12.345; +root = new XElement("Root", dbl); +Console.WriteLine(root); + +// DateTime content: +DateTime dt = new DateTime(2006, 10, 6, 12, 30, 00); +root = new XElement("Root", dt); +Console.WriteLine(root); + +// String array content: +// Any collection other than a collection of XElement or XAttribute objects +// are converted to strings. The strings are concatenated and added. +string[] stringArray = { + "abc", + "def", + "ghi" +}; +root = new XElement("Root", stringArray); +Console.WriteLine(root); + +// XElement object array content: +XElement[] ellArray = { + new XElement("NewChild1", 1), + new XElement("NewChild2", 2), + new XElement("NewChild3", 3) +}; +root = new XElement("Root", ellArray); +Console.WriteLine(root); + +// XAttribute object array content: +XAttribute[] attArray = { + new XAttribute("NewAtt1", 1), + new XAttribute("NewAtt2", 2), + new XAttribute("NewAtt3", 3) +}; +root = new XElement("Root", attArray); +Console.WriteLine(root); +``` + +```vb +Dim root As XElement + +' String content: +root = Some text +Console.WriteLine(root) + +' XElement object content: +root = + n + +Console.WriteLine(root) + +' XAttribute object content: +root = +Console.WriteLine(root) + +' Double content: +Dim dbl As Double = 12.345 +root = <%= dbl %> +Console.WriteLine(root) + +' DateTime content: +Dim dt As DateTime = New DateTime(2006, 10, 6, 12, 30, 0) +root = <%= dt %> +Console.WriteLine(root) + +' String array content: +' Any collection other than a collection of XElement or XAttribute objects +' are converted to strings. The strings are concatenated and added. + +Dim stringArray As String() = { _ + "abc", _ + "def", _ + "ghi" _ +} +root = <%= stringArray %> +Console.WriteLine(root) + +' XElement object array content: +Dim ellArray As XElement() = { _ + 1, _ + 2, _ + 3 _ +} + +root = <%= ellArray %> +Console.WriteLine(root) + +' XAttribute object array content +Dim attArray As XAttribute() = { _ + New XAttribute("NewAtt1", 1), _ + New XAttribute("NewAtt2", 2), _ + New XAttribute("NewAtt3", 3) _ +} +root = <%= attArray %> +Console.WriteLine(root) +``` + + This example produces the following output: + +```xml +Some text + + n + + +12.345 +2006-10-06T12:30:00 +abcdefghi + + 1 + 2 + 3 + + +``` + + The following example creates an XML tree in a namespace. + +```csharp +// Create an XML tree in a namespace. +XNamespace aw = "http://www.adventure-works.com"; +XElement root = new XElement(aw + "Root", + new XElement(aw + "Child", "child content") +); +Console.WriteLine(root); +``` + +```vb +' Create an XML tree in a namespace. +Dim root As XElement = _ + + child content + +Console.WriteLine(root) +``` + + This example produces the following output: + +```xml + + child content + +``` + + The following example creates an XML tree with nested namespaces. + +```csharp +// Create an XML tree with nested namespaces. +XNamespace aw = "http://www.adventure-works.com"; +XNamespace fc = "www.fourthcoffee.com"; +XDocument root = new XDocument( + new XDeclaration("1.0", "utf-8", "yes"), + new XElement(aw + "Root", + new XElement(fc + "Child", + new XElement(aw + "DifferentChild", "other content") + ) + ) +); +Console.WriteLine(root); +``` + +```vb +' Create an XML tree with nested namespaces. +Dim root As XDocument = _ + + + + other content + + +Console.WriteLine(root) +``` + + This example produces the following output: + +```xml + + + other content + + +``` + ]]> LINQ to XML overview @@ -979,274 +979,274 @@ Console.WriteLine(root) The initial content of the element. Initializes a new instance of the class with the specified name and content. - . Typical use of this constructor is to specify a string as the parameter instead of creating a new . - - When creating an element in a namespace, typical use is to use the addition operator overload with an and a string to create an . For more information, see [Work with XML Namespaces](/dotnet/standard/linq/namespaces-overview). - - For details about the valid content that can be passed to this constructor, see [Valid Content of XElement and XDocument Objects](/dotnet/standard/linq/valid-content-xelement-xdocument-objects). - - - -## Examples - The following example creates an XML tree. The content of the new element comes from a LINQ query. - -```csharp -XElement xmlTree1 = new XElement("Root", - new XElement("Child1", 1), - new XElement("Child2", 2), - new XElement("Child3", 3), - new XElement("Child4", 4), - new XElement("Child5", 5), - new XElement("Child6", 6) -); - -XElement xmlTree2 = new XElement("Root", - from el in xmlTree1.Elements() - where((int)el >= 3 && (int)el <= 5) - select el -); -Console.WriteLine(xmlTree2); -``` - -```vb -Dim xmlTree1 As XElement = _ - - 1 - 2 - 3 - 4 - 5 - 6 - - -Dim xmlTree2 As XElement = _ - - <%= From el In xmlTree1.Elements() _ - Where el.Value >= 3 And el.Value <= 5 _ - Select el %> - - -Console.WriteLine(xmlTree2) -``` - - This example produces the following output: - -```xml - - 3 - 4 - 5 - -``` - - The following example creates an XML tree with a variety of types of content. - -```csharp -XElement root; - -// String content: -root = new XElement("Root", "Some text"); -Console.WriteLine(root); - -// XElement object content: -root = new XElement("Root", - new XElement("NewChild", "n") -); -Console.WriteLine(root); - -// XAttribute object content: -root = new XElement("Root", - new XAttribute("NewAttribute", "n") -); -Console.WriteLine(root); - -// Double content: -double dbl = 12.345; -root = new XElement("Root", dbl); -Console.WriteLine(root); - -// DateTime content: -DateTime dt = new DateTime(2006, 10, 6, 12, 30, 00); -root = new XElement("Root", dt); -Console.WriteLine(root); - -// String array content: -// Any collection other than a collection of XElement or XAttribute objects -// are converted to strings. The strings are concatenated and added. -string[] stringArray = { - "abc", - "def", - "ghi" -}; -root = new XElement("Root", stringArray); -Console.WriteLine(root); - -// XElement object array content: -XElement[] ellArray = { - new XElement("NewChild1", 1), - new XElement("NewChild2", 2), - new XElement("NewChild3", 3) -}; -root = new XElement("Root", ellArray); -Console.WriteLine(root); - -// XAttribute object array content: -XAttribute[] attArray = { - new XAttribute("NewAtt1", 1), - new XAttribute("NewAtt2", 2), - new XAttribute("NewAtt3", 3) -}; -root = new XElement("Root", attArray); -Console.WriteLine(root); -``` - -```vb -Dim root As XElement - -' String content: -root = Some text -Console.WriteLine(root) - -' XElement object content: -root = - n - -Console.WriteLine(root) - -' XAttribute object content: -root = -Console.WriteLine(root) - -' Double content: -Dim dbl As Double = 12.345 -root = <%= dbl %> -Console.WriteLine(root) - -' DateTime content: -Dim dt As DateTime = New DateTime(2006, 10, 6, 12, 30, 0) -root = <%= dt %> -Console.WriteLine(root) - -' String array content: -' Any collection other than a collection of XElement or XAttribute objects -' are converted to strings. The strings are concatenated and added. - -Dim stringArray As String() = { _ - "abc", _ - "def", _ - "ghi" _ -} -root = <%= stringArray %> -Console.WriteLine(root) - -' XElement object array content: -Dim ellArray As XElement() = { _ - 1, _ - 2, _ - 3 _ -} - -root = <%= ellArray %> -Console.WriteLine(root) - -' XAttribute object array content -Dim attArray As XAttribute() = { _ - New XAttribute("NewAtt1", 1), _ - New XAttribute("NewAtt2", 2), _ - New XAttribute("NewAtt3", 3) _ -} -root = <%= attArray %> -Console.WriteLine(root) -``` - - This example produces the following output: - + . Typical use of this constructor is to specify a string as the parameter instead of creating a new . + + When creating an element in a namespace, typical use is to use the addition operator overload with an and a string to create an . For more information, see [Work with XML Namespaces](/dotnet/standard/linq/namespaces-overview). + + For details about the valid content that can be passed to this constructor, see [Valid Content of XElement and XDocument Objects](/dotnet/standard/linq/valid-content-xelement-xdocument-objects). + + + +## Examples + The following example creates an XML tree. The content of the new element comes from a LINQ query. + +```csharp +XElement xmlTree1 = new XElement("Root", + new XElement("Child1", 1), + new XElement("Child2", 2), + new XElement("Child3", 3), + new XElement("Child4", 4), + new XElement("Child5", 5), + new XElement("Child6", 6) +); + +XElement xmlTree2 = new XElement("Root", + from el in xmlTree1.Elements() + where((int)el >= 3 && (int)el <= 5) + select el +); +Console.WriteLine(xmlTree2); +``` + +```vb +Dim xmlTree1 As XElement = _ + + 1 + 2 + 3 + 4 + 5 + 6 + + +Dim xmlTree2 As XElement = _ + + <%= From el In xmlTree1.Elements() _ + Where el.Value >= 3 And el.Value <= 5 _ + Select el %> + + +Console.WriteLine(xmlTree2) +``` + + This example produces the following output: + ```xml -Some text - - n - - -12.345 -2006-10-06T12:30:00 -abcdefghi - - 1 - 2 - 3 - - -``` - - The following example creates an XML tree in a namespace. - -```csharp -// Create an XML tree in a namespace. -XNamespace aw = "http://www.adventure-works.com"; -XElement root = new XElement(aw + "Root", - new XElement(aw + "Child", "child content") -); -Console.WriteLine(root); -``` - -```vb -' Create an XML tree in a namespace. -Dim root As XElement = _ - - child content - -Console.WriteLine(root) -``` - - This example produces the following output: - -```xml - - child content - -``` - - The following example creates an XML tree with nested namespaces. - -```csharp -// Create an XML tree with nested namespaces. -XNamespace aw = "http://www.adventure-works.com"; -XNamespace fc = "www.fourthcoffee.com"; -XElement root = new XElement(aw + "Root", - new XElement(fc + "Child", - new XElement(aw + "DifferentChild", "other content") - ) -); -Console.WriteLine(root); -``` - -```vb -' Create an XML tree with nested namespaces. -Dim root As XDocument = _ - - - - other content - - -Console.WriteLine(root) -``` - - This example produces the following output: - -```xml - - - other content - - -``` - + + 3 + 4 + 5 + +``` + + The following example creates an XML tree with a variety of types of content. + +```csharp +XElement root; + +// String content: +root = new XElement("Root", "Some text"); +Console.WriteLine(root); + +// XElement object content: +root = new XElement("Root", + new XElement("NewChild", "n") +); +Console.WriteLine(root); + +// XAttribute object content: +root = new XElement("Root", + new XAttribute("NewAttribute", "n") +); +Console.WriteLine(root); + +// Double content: +double dbl = 12.345; +root = new XElement("Root", dbl); +Console.WriteLine(root); + +// DateTime content: +DateTime dt = new DateTime(2006, 10, 6, 12, 30, 00); +root = new XElement("Root", dt); +Console.WriteLine(root); + +// String array content: +// Any collection other than a collection of XElement or XAttribute objects +// are converted to strings. The strings are concatenated and added. +string[] stringArray = { + "abc", + "def", + "ghi" +}; +root = new XElement("Root", stringArray); +Console.WriteLine(root); + +// XElement object array content: +XElement[] ellArray = { + new XElement("NewChild1", 1), + new XElement("NewChild2", 2), + new XElement("NewChild3", 3) +}; +root = new XElement("Root", ellArray); +Console.WriteLine(root); + +// XAttribute object array content: +XAttribute[] attArray = { + new XAttribute("NewAtt1", 1), + new XAttribute("NewAtt2", 2), + new XAttribute("NewAtt3", 3) +}; +root = new XElement("Root", attArray); +Console.WriteLine(root); +``` + +```vb +Dim root As XElement + +' String content: +root = Some text +Console.WriteLine(root) + +' XElement object content: +root = + n + +Console.WriteLine(root) + +' XAttribute object content: +root = +Console.WriteLine(root) + +' Double content: +Dim dbl As Double = 12.345 +root = <%= dbl %> +Console.WriteLine(root) + +' DateTime content: +Dim dt As DateTime = New DateTime(2006, 10, 6, 12, 30, 0) +root = <%= dt %> +Console.WriteLine(root) + +' String array content: +' Any collection other than a collection of XElement or XAttribute objects +' are converted to strings. The strings are concatenated and added. + +Dim stringArray As String() = { _ + "abc", _ + "def", _ + "ghi" _ +} +root = <%= stringArray %> +Console.WriteLine(root) + +' XElement object array content: +Dim ellArray As XElement() = { _ + 1, _ + 2, _ + 3 _ +} + +root = <%= ellArray %> +Console.WriteLine(root) + +' XAttribute object array content +Dim attArray As XAttribute() = { _ + New XAttribute("NewAtt1", 1), _ + New XAttribute("NewAtt2", 2), _ + New XAttribute("NewAtt3", 3) _ +} +root = <%= attArray %> +Console.WriteLine(root) +``` + + This example produces the following output: + +```xml +Some text + + n + + +12.345 +2006-10-06T12:30:00 +abcdefghi + + 1 + 2 + 3 + + +``` + + The following example creates an XML tree in a namespace. + +```csharp +// Create an XML tree in a namespace. +XNamespace aw = "http://www.adventure-works.com"; +XElement root = new XElement(aw + "Root", + new XElement(aw + "Child", "child content") +); +Console.WriteLine(root); +``` + +```vb +' Create an XML tree in a namespace. +Dim root As XElement = _ + + child content + +Console.WriteLine(root) +``` + + This example produces the following output: + +```xml + + child content + +``` + + The following example creates an XML tree with nested namespaces. + +```csharp +// Create an XML tree with nested namespaces. +XNamespace aw = "http://www.adventure-works.com"; +XNamespace fc = "www.fourthcoffee.com"; +XElement root = new XElement(aw + "Root", + new XElement(fc + "Child", + new XElement(aw + "DifferentChild", "other content") + ) +); +Console.WriteLine(root); +``` + +```vb +' Create an XML tree with nested namespaces. +Dim root As XDocument = _ + + + + other content + + +Console.WriteLine(root) +``` + + This example produces the following output: + +```xml + + + other content + + +``` + ]]> LINQ to XML overview @@ -1261,13 +1261,13 @@ Console.WriteLine(root) Returns a collection of elements that contain this element, and the ancestors of this element. - @@ -1314,59 +1314,59 @@ Console.WriteLine(root) Returns a collection of elements that contain this element, and the ancestors of this element. An of of elements that contain this element, and the ancestors of this element. - aas = - from el in gc.AncestorsAndSelf() - select el; -foreach (XElement el in aas) - Console.WriteLine(el.Name); -``` - -```vb -Dim xmlTree As XElement = _ - - - element content - - - -Dim GC As XElement = xmlTree..(0) - -Dim aas As IEnumerable(Of XElement) = _ - From el In GC.AncestorsAndSelf() _ - Select el - -For Each el In aas - Console.WriteLine(el.Name) -Next -``` - - This example produces the following output: - -``` -GrandChild -Child -Root -``` - + aas = + from el in gc.AncestorsAndSelf() + select el; +foreach (XElement el in aas) + Console.WriteLine(el.Name); +``` + +```vb +Dim xmlTree As XElement = _ + + + element content + + + +Dim GC As XElement = xmlTree..(0) + +Dim aas As IEnumerable(Of XElement) = _ + From el In GC.AncestorsAndSelf() _ + Select el + +For Each el In aas + Console.WriteLine(el.Name) +Next +``` + + This example produces the following output: + +``` +GrandChild +Child +Root +``` + ]]> @@ -1424,51 +1424,51 @@ Root Returns a filtered collection of elements that contain this element, and the ancestors of this element. Only elements that have a matching are included in the collection. An of that contain this element, and the ancestors of this element. Only elements that have a matching are included in the collection. - aas = gc.AncestorsAndSelf("Child"); -foreach (XElement el in aas) - Console.WriteLine(el.Name); -``` - -```vb -Dim xmlTree As XElement = _ - - - element content - - - -Dim GC As XElement = xmlTree..(0) -Dim aas As IEnumerable(Of XElement) = GC.AncestorsAndSelf("Child") -For Each el In aas - Console.WriteLine(el.Name) -Next -``` - - This example produces the following output: - -``` -Child -``` - + aas = gc.AncestorsAndSelf("Child"); +foreach (XElement el in aas) + Console.WriteLine(el.Name); +``` + +```vb +Dim xmlTree As XElement = _ + + + element content + + + +Dim GC As XElement = xmlTree..(0) +Dim aas As IEnumerable(Of XElement) = GC.AncestorsAndSelf("Child") +For Each el In aas + Console.WriteLine(el.Name) +Next +``` + + This example produces the following output: + +``` +Child +``` + ]]> @@ -1519,70 +1519,70 @@ Child Returns the of this that has the specified . An that has the specified ; if there is no attribute with the specified name. - - -Dim att As XAttribute = xmlTree.Attribute("Att") -Console.WriteLine(att) -``` - - This example produces the following output: - -``` -Att="attribute content" -``` - - The following is the same example, but in this case the XML is in a namespace. For more information, see [Work with XML Namespaces](/dotnet/standard/linq/namespaces-overview). - -```csharp -XNamespace aw = "http://www.adventure-works.com"; -XElement xmlTree = new XElement(aw + "Root", - new XAttribute(XNamespace.Xmlns + "aw", "http://www.adventure-works.com"), - new XAttribute(aw + "Att", "attribute content") -); -XAttribute att = xmlTree.Attribute(aw + "Att"); -Console.WriteLine(att); -``` - -```vb -Imports - -Module Module1 - Sub Main() - Dim xmlTree As XElement = - - Dim att As XAttribute = xmlTree.Attribute(GetXmlNamespace(aw) + "Att") - Console.WriteLine(att) - End Sub -End Module -``` - - This example produces the following output: - -``` -aw:Att="attribute content" -``` - + + +Dim att As XAttribute = xmlTree.Attribute("Att") +Console.WriteLine(att) +``` + + This example produces the following output: + +``` +Att="attribute content" +``` + + The following is the same example, but in this case the XML is in a namespace. For more information, see [Work with XML Namespaces](/dotnet/standard/linq/namespaces-overview). + +```csharp +XNamespace aw = "http://www.adventure-works.com"; +XElement xmlTree = new XElement(aw + "Root", + new XAttribute(XNamespace.Xmlns + "aw", "http://www.adventure-works.com"), + new XAttribute(aw + "Att", "attribute content") +); +XAttribute att = xmlTree.Attribute(aw + "Att"); +Console.WriteLine(att); +``` + +```vb +Imports + +Module Module1 + Sub Main() + Dim xmlTree As XElement = + + Dim att As XAttribute = xmlTree.Attribute(GetXmlNamespace(aw) + "Att") + Console.WriteLine(att) + End Sub +End Module +``` + + This example produces the following output: + +``` +aw:Att="attribute content" +``` + ]]> LINQ to XML overview @@ -1597,11 +1597,11 @@ aw:Att="attribute content" Returns a collection of attributes of this element. - LINQ to XML overview @@ -1653,91 +1653,91 @@ aw:Att="attribute content" Returns a collection of attributes of this element. An of of attributes of this element. - attList = - from at in xmlTree.Attributes() - select at; -foreach (XAttribute att in attList) - Console.WriteLine(att); -``` - -```vb -Dim xmlTree As XElement = - -Dim attList As IEnumerable(Of XAttribute) = _ -From at In xmlTree.Attributes() _ -Select at - -For Each att In attList - Console.WriteLine(att) -Next -``` - - This example produces the following output: - -``` -Att1="content1" -Att2="content2" -``` - - The following is the same example, but in this case the XML is in a namespace. For more information, see [Work with XML Namespaces](/dotnet/standard/linq/namespaces-overview). - -```csharp -XNamespace aw = "http://www.adventure-works.com"; -XElement xmlTree = new XElement(aw + "Root", - new XAttribute(aw + "Att1", "content1"), - new XAttribute(aw + "Att2", "content2"), - new XAttribute(XNamespace.Xmlns + "aw", "http://www.adventure-works.com") -); -IEnumerable attList = - from at in xmlTree.Attributes() - select at; -foreach (XAttribute att in attList) - Console.WriteLine(att); -``` - -```vb -Imports - -Module Module1 - Sub Main() - Dim xmlTree As XElement = - - Dim attList As IEnumerable(Of XAttribute) = _ - From at In xmlTree.Attributes() _ - Select at - - For Each att In attList - Console.WriteLine(att) - Next - End Sub -End Module -``` - - This example produces the following output: - -``` -aw:Att1="content1" -aw:Att2="content2" -xmlns:aw="http://www.adventure-works.com" -``` - + attList = + from at in xmlTree.Attributes() + select at; +foreach (XAttribute att in attList) + Console.WriteLine(att); +``` + +```vb +Dim xmlTree As XElement = + +Dim attList As IEnumerable(Of XAttribute) = _ +From at In xmlTree.Attributes() _ +Select at + +For Each att In attList + Console.WriteLine(att) +Next +``` + + This example produces the following output: + +``` +Att1="content1" +Att2="content2" +``` + + The following is the same example, but in this case the XML is in a namespace. For more information, see [Work with XML Namespaces](/dotnet/standard/linq/namespaces-overview). + +```csharp +XNamespace aw = "http://www.adventure-works.com"; +XElement xmlTree = new XElement(aw + "Root", + new XAttribute(aw + "Att1", "content1"), + new XAttribute(aw + "Att2", "content2"), + new XAttribute(XNamespace.Xmlns + "aw", "http://www.adventure-works.com") +); +IEnumerable attList = + from at in xmlTree.Attributes() + select at; +foreach (XAttribute att in attList) + Console.WriteLine(att); +``` + +```vb +Imports + +Module Module1 + Sub Main() + Dim xmlTree As XElement = + + Dim attList As IEnumerable(Of XAttribute) = _ + From at In xmlTree.Attributes() _ + Select at + + For Each att In attList + Console.WriteLine(att) + Next + End Sub +End Module +``` + + This example produces the following output: + +``` +aw:Att1="content1" +aw:Att2="content2" +xmlns:aw="http://www.adventure-works.com" +``` + ]]> @@ -1795,80 +1795,80 @@ xmlns:aw="http://www.adventure-works.com" Returns a filtered collection of attributes of this element. Only attributes that have a matching are included in the collection. An of that contains the attributes of this element. Only attributes that have a matching are included in the collection. - attList = xmlTree.Attributes("Att1"); -foreach (XAttribute att in attList) - Console.WriteLine(att); -``` - -```vb -Dim xmlTree As XElement = - -Dim attList As IEnumerable(Of XAttribute) = xmlTree.Attributes("Att1") - -For Each att In attList - Console.WriteLine(att) -Next -``` - - This example produces the following output: - -``` -Att1="content1" -``` - - The following is the same example, but in this case the XML is in a namespace. For more information, see [Work with XML Namespaces](/dotnet/standard/linq/namespaces-overview). - -```csharp -XNamespace aw = "http://www.adventure-works.com"; -XElement xmlTree = new XElement(aw + "Root", - new XAttribute(XNamespace.Xmlns + "aw", "http://www.adventure-works.com"), - new XAttribute(aw + "Att1", "content1"), - new XAttribute(aw + "Att2", "content2") -); -IEnumerable attList = xmlTree.Attributes(aw + "Att1"); -foreach (XAttribute att in attList) - Console.WriteLine(att); -``` - -```vb -Imports - -Module Module1 - Sub Main() - Dim xmlTree As XElement = - - Dim attList As IEnumerable(Of XAttribute) = xmlTree.Attributes(GetXmlNamespace(aw) + "Att1") - - For Each att In attList - Console.WriteLine(att) - Next - End Sub -End Module -``` - - This example produces the following output: - -``` -aw:Att1="content1" -``` - + attList = xmlTree.Attributes("Att1"); +foreach (XAttribute att in attList) + Console.WriteLine(att); +``` + +```vb +Dim xmlTree As XElement = + +Dim attList As IEnumerable(Of XAttribute) = xmlTree.Attributes("Att1") + +For Each att In attList + Console.WriteLine(att) +Next +``` + + This example produces the following output: + +``` +Att1="content1" +``` + + The following is the same example, but in this case the XML is in a namespace. For more information, see [Work with XML Namespaces](/dotnet/standard/linq/namespaces-overview). + +```csharp +XNamespace aw = "http://www.adventure-works.com"; +XElement xmlTree = new XElement(aw + "Root", + new XAttribute(XNamespace.Xmlns + "aw", "http://www.adventure-works.com"), + new XAttribute(aw + "Att1", "content1"), + new XAttribute(aw + "Att2", "content2") +); +IEnumerable attList = xmlTree.Attributes(aw + "Att1"); +foreach (XAttribute att in attList) + Console.WriteLine(att); +``` + +```vb +Imports + +Module Module1 + Sub Main() + Dim xmlTree As XElement = + + Dim attList As IEnumerable(Of XAttribute) = xmlTree.Attributes(GetXmlNamespace(aw) + "Att1") + + For Each att In attList + Console.WriteLine(att) + Next + End Sub +End Module +``` + + This example produces the following output: + +``` +aw:Att1="content1" +``` + ]]> LINQ to XML overview @@ -1914,67 +1914,67 @@ aw:Att1="content1" Returns a collection of nodes that contain this element, and all descendant nodes of this element, in document order. An of that contain this element, and all descendant nodes of this element, in document order. - dnas = - from node in xmlTree.DescendantNodesAndSelf() - select node; -foreach (XNode node in dnas) -{ - if (node is XElement) - Console.WriteLine((node as XElement).Name); - else - Console.WriteLine(node); -} -``` - -```vb -Dim xmlTree As XElement = _ - - Some textelement content - - - -Dim dnas As IEnumerable(Of XNode) = _ - From node In xmlTree.DescendantNodesAndSelf() _ - Select node - -For Each node In dnas - If TypeOf node Is XElement Then - Console.WriteLine(DirectCast(node, XElement).Name) - Else - Console.WriteLine(node) - End If -Next -``` - - This example produces the following output: - -``` -Root -Child -Some text -GrandChild -element content -``` - + dnas = + from node in xmlTree.DescendantNodesAndSelf() + select node; +foreach (XNode node in dnas) +{ + if (node is XElement) + Console.WriteLine((node as XElement).Name); + else + Console.WriteLine(node); +} +``` + +```vb +Dim xmlTree As XElement = _ + + Some textelement content + + + +Dim dnas As IEnumerable(Of XNode) = _ + From node In xmlTree.DescendantNodesAndSelf() _ + Select node + +For Each node In dnas + If TypeOf node Is XElement Then + Console.WriteLine(DirectCast(node, XElement).Name) + Else + Console.WriteLine(node) + End If +Next +``` + + This example produces the following output: + +``` +Root +Child +Some text +GrandChild +element content +``` + ]]> LINQ to XML overview @@ -1989,11 +1989,11 @@ element content Returns a collection of elements that contain this element, and all descendant elements of this element, in document order. - LINQ to XML overview @@ -2039,56 +2039,56 @@ element content Returns a collection of elements that contain this element, and all descendant elements of this element, in document order. An of of elements that contain this element, and all descendant elements of this element, in document order. - das = - from el in xmlTree.DescendantsAndSelf() - select el; -foreach (XElement el in das) - Console.WriteLine(el.Name); -``` - -```vb -Dim xmlTree As XElement = _ - - Some text - element content - - - -Dim das As IEnumerable(Of XElement) = _ - From el In xmlTree.DescendantsAndSelf() _ - Select el - -For Each el In das - Console.WriteLine(el.Name) -Next -``` - - This example produces the following output: - -``` -Root -Child -GrandChild -``` - + das = + from el in xmlTree.DescendantsAndSelf() + select el; +foreach (XElement el in das) + Console.WriteLine(el.Name); +``` + +```vb +Dim xmlTree As XElement = _ + + Some text + element content + + + +Dim das As IEnumerable(Of XElement) = _ + From el In xmlTree.DescendantsAndSelf() _ + Select el + +For Each el In das + Console.WriteLine(el.Name) +Next +``` + + This example produces the following output: + +``` +Root +Child +GrandChild +``` + ]]> LINQ to XML overview @@ -2145,50 +2145,50 @@ GrandChild Returns a filtered collection of elements that contain this element, and all descendant elements of this element, in document order. Only elements that have a matching are included in the collection. An of that contain this element, and all descendant elements of this element, in document order. Only elements that have a matching are included in the collection. - das = xmlTree.DescendantsAndSelf("Child"); -foreach (XElement el in das) - Console.WriteLine(el.Name); -``` - -```vb -Dim xmlTree As XElement = _ - - Some text - element content - - - -Dim das As IEnumerable(Of XElement) = xmlTree.DescendantsAndSelf("Child") - -For Each el In das - Console.WriteLine(el.Name) -Next -``` - - This example produces the following output: - -``` -Child -``` - + das = xmlTree.DescendantsAndSelf("Child"); +foreach (XElement el in das) + Console.WriteLine(el.Name); +``` + +```vb +Dim xmlTree As XElement = _ + + Some text + element content + + + +Dim das As IEnumerable(Of XElement) = xmlTree.DescendantsAndSelf("Child") + +For Each el In das + Console.WriteLine(el.Name) +Next +``` + + This example produces the following output: + +``` +Child +``` + ]]> LINQ to XML overview @@ -2233,11 +2233,11 @@ Child Gets an empty collection of elements. An of that contains an empty collection. - objects. - + objects. + ]]> LINQ to XML overview @@ -2293,36 +2293,36 @@ Child Gets the first attribute of this element. An that contains the first attribute of this element. - -Console.WriteLine(xmlTree.FirstAttribute) -``` - - This example produces the following output: - -``` -Att1="1" -``` - + +Console.WriteLine(xmlTree.FirstAttribute) +``` + + This example produces the following output: + +``` +Att1="1" +``` + ]]> LINQ to XML overview @@ -2368,45 +2368,45 @@ Att1="1" Gets the default of this . An that contains the default namespace of this . - for the default namespace. - - If there is no attribute that declares the default namespace, then this method returns . - - When creating XML trees using C#, even if an XML tree would be serialized with a default namespace, if the namespace is not persisted in the XML tree as an attribute, this method will not report the namespace as the default namespace. - - When creating XML trees using Visual Basic and XML literals, if you create the XML in a default namespace using the Imports statement, then a namespace attribute will be created in the tree by the Visual Basic compiler, and this method will report that namespace. - - - -## Examples - The following example creates an XML tree that has a default namespace. It then uses this method to retrieve the default namespace. - -```csharp -String xml = ""; -XElement e = XElement.Parse(xml); -Console.WriteLine("Default namespace: {0}", e.GetDefaultNamespace()); -``` - -```vb -Imports - -Module Module1 - Sub Main() - Dim e As XElement = - Console.WriteLine("Default namespace: {0}", e.GetDefaultNamespace()) - End Sub -End Module -``` - - This example produces the following output: - -``` -Default namespace: http://www.adventure-works.com -``` - + for the default namespace. + + If there is no attribute that declares the default namespace, then this method returns . + + When creating XML trees using C#, even if an XML tree would be serialized with a default namespace, if the namespace is not persisted in the XML tree as an attribute, this method will not report the namespace as the default namespace. + + When creating XML trees using Visual Basic and XML literals, if you create the XML in a default namespace using the Imports statement, then a namespace attribute will be created in the tree by the Visual Basic compiler, and this method will report that namespace. + + + +## Examples + The following example creates an XML tree that has a default namespace. It then uses this method to retrieve the default namespace. + +```csharp +String xml = ""; +XElement e = XElement.Parse(xml); +Console.WriteLine("Default namespace: {0}", e.GetDefaultNamespace()); +``` + +```vb +Imports + +Module Module1 + Sub Main() + Dim e As XElement = + Console.WriteLine("Default namespace: {0}", e.GetDefaultNamespace()) + End Sub +End Module +``` + + This example produces the following output: + +``` +Default namespace: http://www.adventure-works.com +``` + ]]> LINQ to XML overview @@ -2456,42 +2456,42 @@ Default namespace: http://www.adventure-works.com Gets the namespace associated with a particular prefix for this . An for the namespace associated with the prefix for this . - for the prefix. - -```csharp -XElement xmlTree = XElement.Parse(""); -XNamespace awNamespace = xmlTree.GetNamespaceOfPrefix("aw"); -Console.WriteLine("Namespace: {0}", awNamespace); -``` - - When using Visual Basic, you would typically use the [GetXmlNamespace Operator](/dotnet/visual-basic/language-reference/operators/getxmlnamespace-operator) operator, as follows - -```vb -Imports - -Module Module1 - Sub Main() - Dim xmlTree As XElement = - Dim awNamespace As XNamespace = GetXmlNamespace(aw) - Console.WriteLine("Namespace: {0}", awNamespace) - End Sub -End Module -``` - - This example produces the following output: - -``` -Namespace: http://www.adventure-works.com -``` - + for the prefix. + +```csharp +XElement xmlTree = XElement.Parse(""); +XNamespace awNamespace = xmlTree.GetNamespaceOfPrefix("aw"); +Console.WriteLine("Namespace: {0}", awNamespace); +``` + + When using Visual Basic, you would typically use the [GetXmlNamespace Operator](/dotnet/visual-basic/language-reference/operators/getxmlnamespace-operator) operator, as follows + +```vb +Imports + +Module Module1 + Sub Main() + Dim xmlTree As XElement = + Dim awNamespace As XNamespace = GetXmlNamespace(aw) + Console.WriteLine("Namespace: {0}", awNamespace) + End Sub +End Module +``` + + This example produces the following output: + +``` +Namespace: http://www.adventure-works.com +``` + ]]> LINQ to XML overview @@ -2541,42 +2541,42 @@ Namespace: http://www.adventure-works.com Gets the prefix associated with a namespace for this . A that contains the namespace prefix. - when calling this method. - -```csharp -XElement xmlTree = XElement.Parse(""); -string prefix = xmlTree.GetPrefixOfNamespace("http://www.adventure-works.com"); -Console.WriteLine("Prefix: {0}", prefix); -``` - -```vb -Imports - -Module Module1 - Sub Main() - Dim xmlTree As XElement = - Dim prefix As String = xmlTree.GetPrefixOfNamespace("http://www.adventure-works.com") - Console.WriteLine("Prefix: {0}", prefix) - End Sub -End Module -``` - - This example produces the following output: - -``` -Prefix: aw -``` - + when calling this method. + +```csharp +XElement xmlTree = XElement.Parse(""); +string prefix = xmlTree.GetPrefixOfNamespace("http://www.adventure-works.com"); +Console.WriteLine("Prefix: {0}", prefix); +``` + +```vb +Imports + +Module Module1 + Sub Main() + Dim xmlTree As XElement = + Dim prefix As String = xmlTree.GetPrefixOfNamespace("http://www.adventure-works.com") + Console.WriteLine("Prefix: {0}", prefix) + End Sub +End Module +``` + + This example produces the following output: + +``` +Prefix: aw +``` + ]]> LINQ to XML overview @@ -2622,35 +2622,35 @@ Prefix: aw if this element has at least one attribute; otherwise . - -Console.WriteLine(xmlTree1.HasAttributes) - -Dim xmlTree2 As XElement = -Console.WriteLine(xmlTree2.HasAttributes) -``` - - This example produces the following output: - -``` -True -False -``` - + +Console.WriteLine(xmlTree1.HasAttributes) + +Dim xmlTree2 As XElement = +Console.WriteLine(xmlTree2.HasAttributes) +``` + + This example produces the following output: + +``` +True +False +``` + ]]> LINQ to XML overview @@ -2696,38 +2696,38 @@ False if this element has at least one child element; otherwise . - - 1 - -Console.WriteLine(xmlTree1.HasElements) - -Dim xmlTree2 As XElement = contents -Console.WriteLine(xmlTree2.HasElements) -``` - - This example produces the following output: - -``` -True -False -``` - + + 1 + +Console.WriteLine(xmlTree1.HasElements) + +Dim xmlTree2 As XElement = contents +Console.WriteLine(xmlTree2.HasElements) +``` + + This example produces the following output: + +``` +True +False +``` + ]]> LINQ to XML overview @@ -2773,68 +2773,68 @@ False if this element contains no content; otherwise . - -Console.WriteLine(el1) -Console.WriteLine(el1.IsEmpty) -Console.WriteLine() -Dim el2 As XElement = content -Console.WriteLine(el2) -Console.WriteLine(el2.IsEmpty) -Console.WriteLine() -Dim el3 As XElement = -Console.WriteLine(el3) -Console.WriteLine(el3.IsEmpty) -Console.WriteLine() -el3.ReplaceAll(Nothing) -Console.WriteLine(el3) -Console.WriteLine(el3.IsEmpty) -``` - - This example produces the following output: - -``` - -True - -content -False - - -False - - -True -``` - + +Console.WriteLine(el1) +Console.WriteLine(el1.IsEmpty) +Console.WriteLine() +Dim el2 As XElement = content +Console.WriteLine(el2) +Console.WriteLine(el2.IsEmpty) +Console.WriteLine() +Dim el3 As XElement = +Console.WriteLine(el3) +Console.WriteLine(el3.IsEmpty) +Console.WriteLine() +el3.ReplaceAll(Nothing) +Console.WriteLine(el3) +Console.WriteLine(el3.IsEmpty) +``` + + This example produces the following output: + +``` + +True + +content +False + + +False + + +True +``` + ]]> LINQ to XML overview @@ -2894,36 +2894,36 @@ True Gets the last attribute of this element. An that contains the last attribute of this element. - -Console.WriteLine(xmlTree.LastAttribute) -``` - - This example produces the following output: - -``` -Att3="3" -``` - + +Console.WriteLine(xmlTree.LastAttribute) +``` + + This example produces the following output: + +``` +Att3="3" +``` + ]]> LINQ to XML overview @@ -2938,13 +2938,13 @@ Att3="3" Creates a new from a file specified by a URI, from an , or from an . - from a file, a , or an . - - To create an from a string that contains XML, use . - + from a file, a , or an . + + To create an from a string that contains XML, use . + ]]> @@ -3000,19 +3000,19 @@ Att3="3" Creates a new instance by using the specified stream. An object used to read the data that is contained in the stream. - overload that takes as a parameter. - - LINQ to XML's loading functionality is built upon . Therefore, you might catch any exceptions that are thrown by the overload methods and the methods that read and parse the document. - - If you have to modify , following these steps: - -1. Create an by calling one of the overloads that take as a parameter. - -2. Pass the to one of the 's overloads that takes as a parameter. - + overload that takes as a parameter. + + LINQ to XML's loading functionality is built upon . Therefore, you might catch any exceptions that are thrown by the overload methods and the methods that read and parse the document. + + If you have to modify , following these steps: + +1. Create an by calling one of the overloads that take as a parameter. + +2. Pass the to one of the 's overloads that takes as a parameter. + ]]> @@ -3066,40 +3066,40 @@ Att3="3" Loads an from a . An that contains the XML that was read from the specified . - . Therefore, you might catch any exceptions that are thrown by the overload methods and the methods that read and parse the document. - - - -## Examples - The following example loads an element from a . - -```csharp -TextReader sr = new StringReader(""); -XElement xmlTree = XElement.Load(sr); -sr.Close(); -Console.WriteLine(xmlTree); -``` - -```vb -Dim sr As TextReader = New StringReader("") -Dim xmlTree As XElement = XElement.Load(sr) -sr.Close() -Console.WriteLine(xmlTree) -``` - - This example produces the following output: - -```xml - - - -``` - + . Therefore, you might catch any exceptions that are thrown by the overload methods and the methods that read and parse the document. + + + +## Examples + The following example loads an element from a . + +```csharp +TextReader sr = new StringReader(""); +XElement xmlTree = XElement.Load(sr); +sr.Close(); +Console.WriteLine(xmlTree); +``` + +```vb +Dim sr As TextReader = New StringReader("") +Dim xmlTree As XElement = XElement.Load(sr) +sr.Close() +Console.WriteLine(xmlTree) +``` + + This example produces the following output: + +```xml + + + +``` + ]]> LINQ to XML overview @@ -3161,45 +3161,45 @@ Console.WriteLine(xmlTree) Loads an from a file. An that contains the contents of the specified file. - . Therefore, you might catch any exceptions that are thrown by the overload methods and the methods that read and parse the document. - - - -## Examples - The following example creates an XML tree, saves it to a file, and then uses this method to load the from the file. - -```csharp -XElement xmlTree1 = new XElement("Root", - new XElement("Child", "content") -); -xmlTree1.Save("Tree.xml"); - -XElement xmlTree2 = XElement.Load("Tree.xml"); -Console.WriteLine(xmlTree2.Name); -``` - -```vb -Dim xmlTree1 As XElement = _ - - Content - -xmlTree1.Save("Tree.xml") - -Dim xmlTree2 As XElement = XElement.Load("Tree.xml") -Console.WriteLine(xmlTree2.Name) -``` - - This example produces the following output: - -``` -Root -``` - + . Therefore, you might catch any exceptions that are thrown by the overload methods and the methods that read and parse the document. + + + +## Examples + The following example creates an XML tree, saves it to a file, and then uses this method to load the from the file. + +```csharp +XElement xmlTree1 = new XElement("Root", + new XElement("Child", "content") +); +xmlTree1.Save("Tree.xml"); + +XElement xmlTree2 = XElement.Load("Tree.xml"); +Console.WriteLine(xmlTree2.Name); +``` + +```vb +Dim xmlTree1 As XElement = _ + + Content + +xmlTree1.Save("Tree.xml") + +Dim xmlTree2 As XElement = XElement.Load("Tree.xml") +Console.WriteLine(xmlTree2.Name) +``` + + This example produces the following output: + +``` +Root +``` + ]]> @@ -3256,66 +3256,66 @@ Root Loads an from an . An that contains the XML that was read from the specified . - from a DOM document, and then using the to create an , this method can be used to create a copy of a DOM document in a LINQ to XML tree. - - LINQ to XML's loading functionality is built upon . Therefore, you might catch any exceptions that are thrown by the overload methods and the methods that read and parse the document. - - - -## Examples - The following example creates a DOM document, creates an from the DOM document, instantiates a tree from the reader. This code effectively copies a DOM document into a LINQ to XML tree. - -```csharp -// Create a DOM document with some content. -XmlDocument doc = new XmlDocument(); -XmlElement child = doc.CreateElement("Child"); -child.InnerText = "child contents"; -XmlElement root = doc.CreateElement("Root"); -root.AppendChild(child); -doc.AppendChild(root); - -// Create a reader and move to the content. -using (XmlNodeReader nodeReader = new XmlNodeReader(doc)) { - // the reader must be in the Interactive state in order to - // Create a LINQ to XML tree from it. - nodeReader.MoveToContent(); - - XElement xRoot = XElement.Load(nodeReader); - Console.WriteLine(xRoot); -} -``` - -```vb -' Create a DOM document with some content. -Dim doc As XmlDocument = New XmlDocument() -Dim child As XmlElement = doc.CreateElement("Child") -child.InnerText = "child contents" -Dim root As XmlElement = doc.CreateElement("Root") -root.AppendChild(child) -doc.AppendChild(root) - -' Create a reader and move to the content. -Using nodeReader = New XmlNodeReader(doc) - ' the reader must be in the Interactive state in order to - ' Create a LINQ to XML tree from it. - nodeReader.MoveToContent() - - Dim xRoot As XElement = XElement.Load(nodeReader) - Console.WriteLine(xRoot) -End Using -``` - - This example produces the following output: - -```xml - - child contents - -``` - + from a DOM document, and then using the to create an , this method can be used to create a copy of a DOM document in a LINQ to XML tree. + + LINQ to XML's loading functionality is built upon . Therefore, you might catch any exceptions that are thrown by the overload methods and the methods that read and parse the document. + + + +## Examples + The following example creates a DOM document, creates an from the DOM document, instantiates a tree from the reader. This code effectively copies a DOM document into a LINQ to XML tree. + +```csharp +// Create a DOM document with some content. +XmlDocument doc = new XmlDocument(); +XmlElement child = doc.CreateElement("Child"); +child.InnerText = "child contents"; +XmlElement root = doc.CreateElement("Root"); +root.AppendChild(child); +doc.AppendChild(root); + +// Create a reader and move to the content. +using (XmlNodeReader nodeReader = new XmlNodeReader(doc)) { + // the reader must be in the Interactive state in order to + // Create a LINQ to XML tree from it. + nodeReader.MoveToContent(); + + XElement xRoot = XElement.Load(nodeReader); + Console.WriteLine(xRoot); +} +``` + +```vb +' Create a DOM document with some content. +Dim doc As XmlDocument = New XmlDocument() +Dim child As XmlElement = doc.CreateElement("Child") +child.InnerText = "child contents" +Dim root As XmlElement = doc.CreateElement("Root") +root.AppendChild(child) +doc.AppendChild(root) + +' Create a reader and move to the content. +Using nodeReader = New XmlNodeReader(doc) + ' the reader must be in the Interactive state in order to + ' Create a LINQ to XML tree from it. + nodeReader.MoveToContent() + + Dim xRoot As XElement = XElement.Load(nodeReader) + Console.WriteLine(xRoot) +End Using +``` + + This example produces the following output: + +```xml + + child contents + +``` + ]]> LINQ to XML overview @@ -3365,17 +3365,17 @@ End Using Creates a new instance by using the specified stream, optionally preserving white space, setting the base URI, and retaining line information. An object used to read the data that the stream contains. - . Therefore, you might catch any exceptions that are thrown by the overload methods and the methods that read and parse the document. - - If you have to modify , following these steps: - -1. Create an by calling one of the overloads that take as a parameter. - -2. Pass the to one of the 's overloads that takes as a parameter. - + . Therefore, you might catch any exceptions that are thrown by the overload methods and the methods that read and parse the document. + + If you have to modify , following these steps: + +1. Create an by calling one of the overloads that take as a parameter. + +2. Pass the to one of the 's overloads that takes as a parameter. + ]]> @@ -3425,152 +3425,152 @@ End Using Loads an from a , optionally preserving white space and retaining line information. An that contains the XML that was read from the specified . - flag in `options` causes the reader to read all white space in the source XML. Nodes of type are created for both significant and insignificant white space. - - If the source XML is indented, not setting the flag in `options` causes the reader to ignore all of the insignificant white space in the source XML. The XML tree is created without any text nodes for insignificant white space. - - If the source XML is not indented, setting the flag in `options` has no effect. Significant white space is still preserved, and there are no spans of insignificant white space that could cause the creation of more white space text nodes. - - For more information, see [Preserve white space while loading or parsing XML](/dotnet/standard/linq/preserve-white-space-loading-parsing-xml) and [Preserve white space while serializing](/dotnet/standard/linq/preserve-white-space-serializing). - - Use to create an from a string that contains XML. - - Setting will have no effect when loading from a . - - There is a performance penalty if you set the flag. - - The line information is accurate immediately after loading the XML document. If you modify the XML tree after loading the document, the line information may become meaningless. - - LINQ to XML's loading functionality is built upon . Therefore, you might catch any exceptions that are thrown by the overload methods and the methods that read and parse the document. - - - -## Examples - The following example loads an from a in two different ways: preserving white space, and not preserving white space. It then uses a query to determine the number of white space nodes in the resulting XML tree. - -```csharp -TextReader sr; -int whiteSpaceNodes; - -sr = new StringReader(" "); -XElement xmlTree1 = XElement.Load(sr, LoadOptions.None); -sr.Close(); -whiteSpaceNodes = xmlTree1 - .DescendantNodesAndSelf() - .OfType() - .Where(tNode => tNode.ToString().Trim().Length == 0) - .Count(); -Console.WriteLine("Count of white space nodes (not preserving whitespace): {0}", whiteSpaceNodes); - -sr = new StringReader(" "); -XElement xmlTree2 = XElement.Load(sr, LoadOptions.PreserveWhitespace); -sr.Close(); -whiteSpaceNodes = xmlTree2 - .DescendantNodesAndSelf() - .OfType() - .Where(tNode => tNode.ToString().Trim().Length == 0) - .Count(); -Console.WriteLine("Count of white space nodes (preserving whitespace): {0}", whiteSpaceNodes); -``` - -```vb -Dim sr As TextReader -Dim whiteSpaceNodes As Integer - -sr = New StringReader(" ") -Dim xmlTree1 As XElement = XElement.Load(sr, LoadOptions.None) -sr.Close() -whiteSpaceNodes = xmlTree1 _ - .DescendantNodesAndSelf() _ - .OfType(Of XText)() _ - .Where(Function(ByVal tNode As XNode) tNode.ToString().Trim().Length = 0) _ - .Count() -Console.WriteLine("Count of white space nodes (not preserving whitespace): {0}", whiteSpaceNodes) - -sr = New StringReader(" ") -Dim xmlTree2 As XElement = XElement.Load(sr, LoadOptions.PreserveWhitespace) -sr.Close() -whiteSpaceNodes = xmlTree2 _ - .DescendantNodesAndSelf() _ - .OfType(Of XText)() _ - .Where(Function(ByVal tNode As XNode) tNode.ToString().Trim().Length = 0) _ - .Count() -Console.WriteLine("Count of white space nodes (preserving whitespace): {0}", whiteSpaceNodes) -``` - - This example produces the following output: - -``` -Count of white space nodes (not preserving whitespace): 0 -Count of white space nodes (preserving whitespace): 3 -``` - - The following example loads the line information as it loads from the . It then prints the line information. - -```csharp -TextReader sr = new StringReader( -@" - - - - -"); -XElement po = XElement.Load(sr, - LoadOptions.SetLineInfo); -Console.WriteLine("{0}{1}{2}", - "Element Name".PadRight(20), - "Line".PadRight(5), - "Position"); -Console.WriteLine("{0}{1}{2}", - "------------".PadRight(20), - "----".PadRight(5), - "--------"); -foreach (XElement e in po.DescendantsAndSelf()) - Console.WriteLine("{0}{1}{2}", - ("".PadRight(e.Ancestors().Count() * 2) + e.Name).PadRight(20), - ((IXmlLineInfo)e).LineNumber.ToString().PadRight(5), - ((IXmlLineInfo)e).LinePosition); -``` - -```vb -Dim sr As TextReader = New StringReader( _ - "" & Environment.NewLine & _ - " " & Environment.NewLine & _ - " " & Environment.NewLine & _ - " " & Environment.NewLine & _ - " " & Environment.NewLine & _ - "") -Dim po As XElement = XElement.Load(sr, LoadOptions.SetLineInfo) -Console.WriteLine("{0}{1}{2}", _ - "Element Name".PadRight(20), _ - "Line".PadRight(5), _ - "Position") -Console.WriteLine("{0}{1}{2}", _ - "------------".PadRight(20), _ - "----".PadRight(5), _ - "--------") -For Each e As XElement In po.DescendantsAndSelf() - Console.WriteLine("{0}{1}{2}", _ - ("".PadRight(e.Ancestors().Count() * 2) & e.Name.ToString).PadRight(20), _ - (DirectCast(e, IXmlLineInfo)).LineNumber.ToString().PadRight(5), _ - (DirectCast(e, IXmlLineInfo)).LinePosition) -Next -``` - - This example produces the following output: - -``` -Element Name Line Position ------------- ---- -------- -Root 1 2 - Child 2 4 - GrandChild1 3 6 - GrandChild2 4 6 -``` - + flag in `options` causes the reader to read all white space in the source XML. Nodes of type are created for both significant and insignificant white space. + + If the source XML is indented, not setting the flag in `options` causes the reader to ignore all of the insignificant white space in the source XML. The XML tree is created without any text nodes for insignificant white space. + + If the source XML is not indented, setting the flag in `options` has no effect. Significant white space is still preserved, and there are no spans of insignificant white space that could cause the creation of more white space text nodes. + + For more information, see [Preserve white space while loading or parsing XML](/dotnet/standard/linq/preserve-white-space-loading-parsing-xml) and [Preserve white space while serializing](/dotnet/standard/linq/preserve-white-space-serializing). + + Use to create an from a string that contains XML. + + Setting will have no effect when loading from a . + + There is a performance penalty if you set the flag. + + The line information is accurate immediately after loading the XML document. If you modify the XML tree after loading the document, the line information may become meaningless. + + LINQ to XML's loading functionality is built upon . Therefore, you might catch any exceptions that are thrown by the overload methods and the methods that read and parse the document. + + + +## Examples + The following example loads an from a in two different ways: preserving white space, and not preserving white space. It then uses a query to determine the number of white space nodes in the resulting XML tree. + +```csharp +TextReader sr; +int whiteSpaceNodes; + +sr = new StringReader(" "); +XElement xmlTree1 = XElement.Load(sr, LoadOptions.None); +sr.Close(); +whiteSpaceNodes = xmlTree1 + .DescendantNodesAndSelf() + .OfType() + .Where(tNode => tNode.ToString().Trim().Length == 0) + .Count(); +Console.WriteLine("Count of white space nodes (not preserving whitespace): {0}", whiteSpaceNodes); + +sr = new StringReader(" "); +XElement xmlTree2 = XElement.Load(sr, LoadOptions.PreserveWhitespace); +sr.Close(); +whiteSpaceNodes = xmlTree2 + .DescendantNodesAndSelf() + .OfType() + .Where(tNode => tNode.ToString().Trim().Length == 0) + .Count(); +Console.WriteLine("Count of white space nodes (preserving whitespace): {0}", whiteSpaceNodes); +``` + +```vb +Dim sr As TextReader +Dim whiteSpaceNodes As Integer + +sr = New StringReader(" ") +Dim xmlTree1 As XElement = XElement.Load(sr, LoadOptions.None) +sr.Close() +whiteSpaceNodes = xmlTree1 _ + .DescendantNodesAndSelf() _ + .OfType(Of XText)() _ + .Where(Function(ByVal tNode As XNode) tNode.ToString().Trim().Length = 0) _ + .Count() +Console.WriteLine("Count of white space nodes (not preserving whitespace): {0}", whiteSpaceNodes) + +sr = New StringReader(" ") +Dim xmlTree2 As XElement = XElement.Load(sr, LoadOptions.PreserveWhitespace) +sr.Close() +whiteSpaceNodes = xmlTree2 _ + .DescendantNodesAndSelf() _ + .OfType(Of XText)() _ + .Where(Function(ByVal tNode As XNode) tNode.ToString().Trim().Length = 0) _ + .Count() +Console.WriteLine("Count of white space nodes (preserving whitespace): {0}", whiteSpaceNodes) +``` + + This example produces the following output: + +``` +Count of white space nodes (not preserving whitespace): 0 +Count of white space nodes (preserving whitespace): 3 +``` + + The following example loads the line information as it loads from the . It then prints the line information. + +```csharp +TextReader sr = new StringReader( +@" + + + + +"); +XElement po = XElement.Load(sr, + LoadOptions.SetLineInfo); +Console.WriteLine("{0}{1}{2}", + "Element Name".PadRight(20), + "Line".PadRight(5), + "Position"); +Console.WriteLine("{0}{1}{2}", + "------------".PadRight(20), + "----".PadRight(5), + "--------"); +foreach (XElement e in po.DescendantsAndSelf()) + Console.WriteLine("{0}{1}{2}", + ("".PadRight(e.Ancestors().Count() * 2) + e.Name).PadRight(20), + ((IXmlLineInfo)e).LineNumber.ToString().PadRight(5), + ((IXmlLineInfo)e).LinePosition); +``` + +```vb +Dim sr As TextReader = New StringReader( _ + "" & Environment.NewLine & _ + " " & Environment.NewLine & _ + " " & Environment.NewLine & _ + " " & Environment.NewLine & _ + " " & Environment.NewLine & _ + "") +Dim po As XElement = XElement.Load(sr, LoadOptions.SetLineInfo) +Console.WriteLine("{0}{1}{2}", _ + "Element Name".PadRight(20), _ + "Line".PadRight(5), _ + "Position") +Console.WriteLine("{0}{1}{2}", _ + "------------".PadRight(20), _ + "----".PadRight(5), _ + "--------") +For Each e As XElement In po.DescendantsAndSelf() + Console.WriteLine("{0}{1}{2}", _ + ("".PadRight(e.Ancestors().Count() * 2) & e.Name.ToString).PadRight(20), _ + (DirectCast(e, IXmlLineInfo)).LineNumber.ToString().PadRight(5), _ + (DirectCast(e, IXmlLineInfo)).LinePosition) +Next +``` + + This example produces the following output: + +``` +Element Name Line Position +------------ ---- -------- +Root 1 2 + Child 2 4 + GrandChild1 3 6 + GrandChild2 4 6 +``` + ]]> LINQ to XML overview @@ -3628,168 +3628,168 @@ Root 1 2 Loads an from a file, optionally preserving white space, setting the base URI, and retaining line information. An that contains the contents of the specified file. - flag in `options` causes the reader to read all white space in the source XML. Nodes of type are created for both significant and insignificant white space. - - If the source XML is indented, not setting the flag in `options` causes the reader to ignore all of the insignificant white space in the source XML. The XML tree is created without any text nodes for insignificant white space. - - If the source XML is not indented, setting the flag in `options` has no effect. Significant white space is still preserved, and there are no spans of insignificant white space that could cause the creation of more white space text nodes. - - For more information, see [Preserve white space while loading or parsing XML](/dotnet/standard/linq/preserve-white-space-loading-parsing-xml) and [Preserve white space while serializing](/dotnet/standard/linq/preserve-white-space-serializing). - - Use to create an from a string that contains XML. - - There is a performance penalty if you set the and the flags. - - The base URI and the line information are accurate immediately after loading the XML document. If you modify the XML tree after loading the document, the base URI and line information may become meaningless. - - LINQ to XML's loading functionality is built upon . Therefore, you might catch any exceptions that are thrown by the overload methods and the methods that read and parse the document. - - - -## Examples - The following example loads an from a file in two different ways: preserving white space, and not preserving white space. It then uses a query to determine the number of white space nodes in the resulting XML tree. - -```csharp -XElement xmlTree1 = XElement.Parse(" ", LoadOptions.PreserveWhitespace); -xmlTree1.Save("Tree.xml"); -Console.WriteLine(xmlTree1); - -int whiteSpaceNodes; -XElement xmlTree2 = XElement.Load("Tree.xml", - LoadOptions.None); -whiteSpaceNodes = xmlTree2 - .DescendantNodesAndSelf() - .OfType() - .Where(tNode => tNode.ToString().Trim().Length == 0) - .Count(); -Console.WriteLine("Count of white space nodes (not preserving whitespace): {0}", whiteSpaceNodes); - -XElement xmlTree3 = XElement.Load("Tree.xml", - LoadOptions.PreserveWhitespace); -whiteSpaceNodes = xmlTree3 - .DescendantNodesAndSelf() - .OfType() - .Where(tNode => tNode.ToString().Trim().Length == 0) - .Count(); -Console.WriteLine("Count of white space nodes (preserving whitespace): {0}", whiteSpaceNodes); -``` - -```vb -Dim xmlTree1 As XElement = XElement.Parse(" ", LoadOptions.PreserveWhitespace) -xmlTree1.Save("Tree.xml") -Console.WriteLine(xmlTree1) - -Dim whiteSpaceNodes As Integer -Dim xmlTree2 As XElement = XElement.Load("Tree.xml", LoadOptions.None) -whiteSpaceNodes = xmlTree2 _ - .DescendantNodesAndSelf() _ - .OfType(Of XText)() _ - .Where(Function(ByVal tNode As XNode) tNode.ToString().Trim().Length = 0) _ - .Count() -Console.WriteLine("Count of white space nodes (not preserving whitespace): {0}", whiteSpaceNodes) - -Dim xmlTree3 As XElement = XElement.Load("Tree.xml", LoadOptions.PreserveWhitespace) -whiteSpaceNodes = xmlTree3 _ - .DescendantNodesAndSelf() _ - .OfType(Of XText)() _ - .Where(Function(ByVal tNode As XNode) tNode.ToString().Trim().Length = 0) _ - .Count() -Console.WriteLine("Count of white space nodes (preserving whitespace): {0}", whiteSpaceNodes) -``` - - This example produces the following output: - -``` - -Count of white space nodes (not preserving whitespace): 0 -Count of white space nodes (preserving whitespace): 3 -``` - - The following example loads the base URI and line information as it loads the file. It then prints the base URI and the line information. - - This example uses the following resource file: [Sample XML File: Typical Purchase Order (LINQ to XML)](/dotnet/standard/linq/sample-xml-file-typical-purchase-order). - -```csharp -XElement po = XElement.Load("PurchaseOrder.xml", - LoadOptions.SetBaseUri | LoadOptions.SetLineInfo); -string[] splitUri = po.BaseUri.Split('/'); -Console.WriteLine("BaseUri: {0}", splitUri[splitUri.Length - 1]); -Console.WriteLine(); -Console.WriteLine("{0}{1}{2}", - "Element Name".PadRight(20), - "Line".PadRight(5), - "Position"); -Console.WriteLine("{0}{1}{2}", - "------------".PadRight(20), - "----".PadRight(5), - "--------"); -foreach (XElement e in po.DescendantsAndSelf()) - Console.WriteLine("{0}{1}{2}", - ("".PadRight(e.Ancestors().Count() * 2) + e.Name).PadRight(20), - ((IXmlLineInfo)e).LineNumber.ToString().PadRight(5), - ((IXmlLineInfo)e).LinePosition); -``` - -```vb -Dim po As XElement = XElement.Load("PurchaseOrder.xml", LoadOptions.SetBaseUri Or LoadOptions.SetLineInfo) -Dim splitUri() As String = po.BaseUri.Split("/") -Console.WriteLine("BaseUri: {0}", splitUri(splitUri.Length - 1)) -Console.WriteLine() -Console.WriteLine("{0}{1}{2}", _ - "Element Name".PadRight(20), _ - "Line".PadRight(5), _ - "Position") -Console.WriteLine("{0}{1}{2}", _ - "------------".PadRight(20), _ - "----".PadRight(5), _ - "--------") -For Each e As XElement In po.DescendantsAndSelf() - Console.WriteLine("{0}{1}{2}", _ - ("".PadRight(e.Ancestors().Count() * 2) & e.Name.ToString()).PadRight(20), _ - (DirectCast(e, IXmlLineInfo)).LineNumber.ToString().PadRight(5), _ - (DirectCast(e, IXmlLineInfo)).LinePosition) -Next -``` - - This example produces the following output: - -``` -BaseUri: PurchaseOrder.xml - -Element Name Line Position ------------- ---- -------- -PurchaseOrder 2 2 - Address 3 4 - Name 4 6 - Street 5 6 - City 6 6 - State 7 6 - Zip 8 6 - Country 9 6 - Address 11 4 - Name 12 6 - Street 13 6 - City 14 6 - State 15 6 - Zip 16 6 - Country 17 6 - DeliveryNotes 19 4 - Items 20 4 - Item 21 6 - ProductName 22 8 - Quantity 23 8 - USPrice 24 8 - Comment 25 8 - Item 27 6 - ProductName 28 8 - Quantity 29 8 - USPrice 30 8 - ShipDate 31 8 -``` - + flag in `options` causes the reader to read all white space in the source XML. Nodes of type are created for both significant and insignificant white space. + + If the source XML is indented, not setting the flag in `options` causes the reader to ignore all of the insignificant white space in the source XML. The XML tree is created without any text nodes for insignificant white space. + + If the source XML is not indented, setting the flag in `options` has no effect. Significant white space is still preserved, and there are no spans of insignificant white space that could cause the creation of more white space text nodes. + + For more information, see [Preserve white space while loading or parsing XML](/dotnet/standard/linq/preserve-white-space-loading-parsing-xml) and [Preserve white space while serializing](/dotnet/standard/linq/preserve-white-space-serializing). + + Use to create an from a string that contains XML. + + There is a performance penalty if you set the and the flags. + + The base URI and the line information are accurate immediately after loading the XML document. If you modify the XML tree after loading the document, the base URI and line information may become meaningless. + + LINQ to XML's loading functionality is built upon . Therefore, you might catch any exceptions that are thrown by the overload methods and the methods that read and parse the document. + + + +## Examples + The following example loads an from a file in two different ways: preserving white space, and not preserving white space. It then uses a query to determine the number of white space nodes in the resulting XML tree. + +```csharp +XElement xmlTree1 = XElement.Parse(" ", LoadOptions.PreserveWhitespace); +xmlTree1.Save("Tree.xml"); +Console.WriteLine(xmlTree1); + +int whiteSpaceNodes; +XElement xmlTree2 = XElement.Load("Tree.xml", + LoadOptions.None); +whiteSpaceNodes = xmlTree2 + .DescendantNodesAndSelf() + .OfType() + .Where(tNode => tNode.ToString().Trim().Length == 0) + .Count(); +Console.WriteLine("Count of white space nodes (not preserving whitespace): {0}", whiteSpaceNodes); + +XElement xmlTree3 = XElement.Load("Tree.xml", + LoadOptions.PreserveWhitespace); +whiteSpaceNodes = xmlTree3 + .DescendantNodesAndSelf() + .OfType() + .Where(tNode => tNode.ToString().Trim().Length == 0) + .Count(); +Console.WriteLine("Count of white space nodes (preserving whitespace): {0}", whiteSpaceNodes); +``` + +```vb +Dim xmlTree1 As XElement = XElement.Parse(" ", LoadOptions.PreserveWhitespace) +xmlTree1.Save("Tree.xml") +Console.WriteLine(xmlTree1) + +Dim whiteSpaceNodes As Integer +Dim xmlTree2 As XElement = XElement.Load("Tree.xml", LoadOptions.None) +whiteSpaceNodes = xmlTree2 _ + .DescendantNodesAndSelf() _ + .OfType(Of XText)() _ + .Where(Function(ByVal tNode As XNode) tNode.ToString().Trim().Length = 0) _ + .Count() +Console.WriteLine("Count of white space nodes (not preserving whitespace): {0}", whiteSpaceNodes) + +Dim xmlTree3 As XElement = XElement.Load("Tree.xml", LoadOptions.PreserveWhitespace) +whiteSpaceNodes = xmlTree3 _ + .DescendantNodesAndSelf() _ + .OfType(Of XText)() _ + .Where(Function(ByVal tNode As XNode) tNode.ToString().Trim().Length = 0) _ + .Count() +Console.WriteLine("Count of white space nodes (preserving whitespace): {0}", whiteSpaceNodes) +``` + + This example produces the following output: + +``` + +Count of white space nodes (not preserving whitespace): 0 +Count of white space nodes (preserving whitespace): 3 +``` + + The following example loads the base URI and line information as it loads the file. It then prints the base URI and the line information. + + This example uses the following resource file: [Sample XML File: Typical Purchase Order (LINQ to XML)](/dotnet/standard/linq/sample-xml-file-typical-purchase-order). + +```csharp +XElement po = XElement.Load("PurchaseOrder.xml", + LoadOptions.SetBaseUri | LoadOptions.SetLineInfo); +string[] splitUri = po.BaseUri.Split('/'); +Console.WriteLine("BaseUri: {0}", splitUri[splitUri.Length - 1]); +Console.WriteLine(); +Console.WriteLine("{0}{1}{2}", + "Element Name".PadRight(20), + "Line".PadRight(5), + "Position"); +Console.WriteLine("{0}{1}{2}", + "------------".PadRight(20), + "----".PadRight(5), + "--------"); +foreach (XElement e in po.DescendantsAndSelf()) + Console.WriteLine("{0}{1}{2}", + ("".PadRight(e.Ancestors().Count() * 2) + e.Name).PadRight(20), + ((IXmlLineInfo)e).LineNumber.ToString().PadRight(5), + ((IXmlLineInfo)e).LinePosition); +``` + +```vb +Dim po As XElement = XElement.Load("PurchaseOrder.xml", LoadOptions.SetBaseUri Or LoadOptions.SetLineInfo) +Dim splitUri() As String = po.BaseUri.Split("/") +Console.WriteLine("BaseUri: {0}", splitUri(splitUri.Length - 1)) +Console.WriteLine() +Console.WriteLine("{0}{1}{2}", _ + "Element Name".PadRight(20), _ + "Line".PadRight(5), _ + "Position") +Console.WriteLine("{0}{1}{2}", _ + "------------".PadRight(20), _ + "----".PadRight(5), _ + "--------") +For Each e As XElement In po.DescendantsAndSelf() + Console.WriteLine("{0}{1}{2}", _ + ("".PadRight(e.Ancestors().Count() * 2) & e.Name.ToString()).PadRight(20), _ + (DirectCast(e, IXmlLineInfo)).LineNumber.ToString().PadRight(5), _ + (DirectCast(e, IXmlLineInfo)).LinePosition) +Next +``` + + This example produces the following output: + +``` +BaseUri: PurchaseOrder.xml + +Element Name Line Position +------------ ---- -------- +PurchaseOrder 2 2 + Address 3 4 + Name 4 6 + Street 5 6 + City 6 6 + State 7 6 + Zip 8 6 + Country 9 6 + Address 11 4 + Name 12 6 + Street 13 6 + City 14 6 + State 15 6 + Zip 16 6 + Country 17 6 + DeliveryNotes 19 4 + Items 20 4 + Item 21 6 + ProductName 22 8 + Quantity 23 8 + USPrice 24 8 + Comment 25 8 + Item 27 6 + ProductName 28 8 + Quantity 29 8 + USPrice 30 8 + ShipDate 31 8 +``` + ]]> LINQ to XML overview @@ -3840,105 +3840,105 @@ PurchaseOrder 2 2 Loads an from an , optionally preserving white space, setting the base URI, and retaining line information. An that contains the XML that was read from the specified . - from a DOM document, and then using the to create an , this method can be used to create a copy of a DOM document in a LINQ to XML tree. - - Use to create an from a string that contains XML. - - Setting is not valid when loading from a . The will be configured to either read whitespace or not. The LINQ to XML tree will be populated with the whitespace nodes that the reader surfaces. This will be the behavior regardless of whether is set or not. - - The may have a valid base URI or not. If you set , the base URI will be set in the XML tree from the base URI that is reported by the . - - The may have a valid line information or not. If you set , the line information will be set in the XML tree from the line information that is reported by the . - - There is a performance penalty if you set the flag. - - The line information is accurate immediately after loading the XML document. If you modify the XML tree after loading the document, the line information may become meaningless. - - LINQ to XML's loading functionality is built upon . Therefore, you might catch any exceptions that are thrown by the overload methods and the methods that read and parse the document. - - - -## Examples - The following example loads the line information that it loads from the . It then prints the line information. - -```csharp -string markup = -@" - - - -"; - -// Create a reader and move to the content. -using (XmlReader nodeReader = XmlReader.Create(new StringReader(markup))) -{ - // the reader must be in the Interactive state in order to - // Create a LINQ to XML tree from it. - nodeReader.MoveToContent(); - - XElement xRoot = XElement.Load(nodeReader, LoadOptions.SetLineInfo); - Console.WriteLine("{0}{1}{2}", - "Element Name".PadRight(20), - "Line".PadRight(5), - "Position"); - Console.WriteLine("{0}{1}{2}", - "------------".PadRight(20), - "----".PadRight(5), - "--------"); - foreach (XElement e in xRoot.DescendantsAndSelf()) - Console.WriteLine("{0}{1}{2}", - ("".PadRight(e.Ancestors().Count() * 2) + e.Name).PadRight(20), - ((IXmlLineInfo)e).LineNumber.ToString().PadRight(5), - ((IXmlLineInfo)e).LinePosition); -} -``` - -```vb -Dim markup As String = _ - "" & Environment.NewLine & _ - " " & Environment.NewLine & _ - " " & Environment.NewLine & _ - " " & Environment.NewLine & _ - "" - -' Create a reader and move to the content. -Using nodeReader As XmlReader = XmlReader.Create(New StringReader(markup)) - - ' the reader must be in the Interactive state in order to - ' Create a LINQ to XML tree from it. - nodeReader.MoveToContent() - - Dim xRoot As XElement = XElement.Load(nodeReader, LoadOptions.SetLineInfo) - Console.WriteLine("{0}{1}{2}", _ - "Element Name".PadRight(20), _ - "Line".PadRight(5), _ - "Position") - Console.WriteLine("{0}{1}{2}", _ - "------------".PadRight(20), _ - "----".PadRight(5), _ - "--------") - For Each e As XElement In xRoot.DescendantsAndSelf() - Console.WriteLine("{0}{1}{2}", _ - ("".PadRight(e.Ancestors().Count() * 2) & e.Name.ToString).PadRight(20), _ - (DirectCast(e, IXmlLineInfo)).LineNumber.ToString().PadRight(5), _ - (DirectCast(e, IXmlLineInfo)).LinePosition) - Next -End Using -``` - - This example produces the following output: - -``` -Element Name Line Position ------------- ---- -------- -Root 1 2 - Child 2 6 - GrandChild 3 10 -``` - + from a DOM document, and then using the to create an , this method can be used to create a copy of a DOM document in a LINQ to XML tree. + + Use to create an from a string that contains XML. + + Setting is not valid when loading from a . The will be configured to either read whitespace or not. The LINQ to XML tree will be populated with the whitespace nodes that the reader surfaces. This will be the behavior regardless of whether is set or not. + + The may have a valid base URI or not. If you set , the base URI will be set in the XML tree from the base URI that is reported by the . + + The may have a valid line information or not. If you set , the line information will be set in the XML tree from the line information that is reported by the . + + There is a performance penalty if you set the flag. + + The line information is accurate immediately after loading the XML document. If you modify the XML tree after loading the document, the line information may become meaningless. + + LINQ to XML's loading functionality is built upon . Therefore, you might catch any exceptions that are thrown by the overload methods and the methods that read and parse the document. + + + +## Examples + The following example loads the line information that it loads from the . It then prints the line information. + +```csharp +string markup = +@" + + + +"; + +// Create a reader and move to the content. +using (XmlReader nodeReader = XmlReader.Create(new StringReader(markup))) +{ + // the reader must be in the Interactive state in order to + // Create a LINQ to XML tree from it. + nodeReader.MoveToContent(); + + XElement xRoot = XElement.Load(nodeReader, LoadOptions.SetLineInfo); + Console.WriteLine("{0}{1}{2}", + "Element Name".PadRight(20), + "Line".PadRight(5), + "Position"); + Console.WriteLine("{0}{1}{2}", + "------------".PadRight(20), + "----".PadRight(5), + "--------"); + foreach (XElement e in xRoot.DescendantsAndSelf()) + Console.WriteLine("{0}{1}{2}", + ("".PadRight(e.Ancestors().Count() * 2) + e.Name).PadRight(20), + ((IXmlLineInfo)e).LineNumber.ToString().PadRight(5), + ((IXmlLineInfo)e).LinePosition); +} +``` + +```vb +Dim markup As String = _ + "" & Environment.NewLine & _ + " " & Environment.NewLine & _ + " " & Environment.NewLine & _ + " " & Environment.NewLine & _ + "" + +' Create a reader and move to the content. +Using nodeReader As XmlReader = XmlReader.Create(New StringReader(markup)) + + ' the reader must be in the Interactive state in order to + ' Create a LINQ to XML tree from it. + nodeReader.MoveToContent() + + Dim xRoot As XElement = XElement.Load(nodeReader, LoadOptions.SetLineInfo) + Console.WriteLine("{0}{1}{2}", _ + "Element Name".PadRight(20), _ + "Line".PadRight(5), _ + "Position") + Console.WriteLine("{0}{1}{2}", _ + "------------".PadRight(20), _ + "----".PadRight(5), _ + "--------") + For Each e As XElement In xRoot.DescendantsAndSelf() + Console.WriteLine("{0}{1}{2}", _ + ("".PadRight(e.Ancestors().Count() * 2) & e.Name.ToString).PadRight(20), _ + (DirectCast(e, IXmlLineInfo)).LineNumber.ToString().PadRight(5), _ + (DirectCast(e, IXmlLineInfo)).LinePosition) + Next +End Using +``` + + This example produces the following output: + +``` +Element Name Line Position +------------ ---- -------- +Root 1 2 + Child 2 6 + GrandChild 3 10 +``` + ]]> LINQ to XML overview @@ -4141,58 +4141,58 @@ This method stores in the task it returns all non-usage exceptions that the meth Gets or sets the name of this element. An that contains the name of this element. - and the events. - - - -## Examples - The following example uses this property to determine the name of an element. - -```csharp -XElement el1 = new XElement("Root", "content"); -Console.WriteLine(el1.Name); - -XNamespace ns = "http://www.adventure-works.com"; -XElement el2 = new XElement(ns + "Root", "content"); -Console.WriteLine(el2.Name); -Console.WriteLine(el2.Name.Namespace); -Console.WriteLine(el2.Name.LocalName); -el2.Name = ns + "NewName"; -Console.WriteLine(el2.Name); -``` - -```vb -Imports - -Module Module1 - Sub Main() - Dim el1 As XElement = content - Console.WriteLine(el1.Name) - - Dim el2 As XElement = content - Console.WriteLine(el2.Name) - Console.WriteLine(el2.Name.Namespace) - Console.WriteLine(el2.Name.LocalName) - Dim aw as XNamespace = GetXmlNamespace(aw) - el2.Name = aw + "NewName" - Console.WriteLine(el2.Name) - End Sub -End Module -``` - - This example produces the following output: - -``` -Root -{http://www.adventure-works.com}Root -http://www.adventure-works.com -Root -{http://www.adventure-works.com}NewName -``` - + and the events. + + + +## Examples + The following example uses this property to determine the name of an element. + +```csharp +XElement el1 = new XElement("Root", "content"); +Console.WriteLine(el1.Name); + +XNamespace ns = "http://www.adventure-works.com"; +XElement el2 = new XElement(ns + "Root", "content"); +Console.WriteLine(el2.Name); +Console.WriteLine(el2.Name.Namespace); +Console.WriteLine(el2.Name.LocalName); +el2.Name = ns + "NewName"; +Console.WriteLine(el2.Name); +``` + +```vb +Imports + +Module Module1 + Sub Main() + Dim el1 As XElement = content + Console.WriteLine(el1.Name) + + Dim el2 As XElement = content + Console.WriteLine(el2.Name) + Console.WriteLine(el2.Name.Namespace) + Console.WriteLine(el2.Name.LocalName) + Dim aw as XNamespace = GetXmlNamespace(aw) + el2.Name = aw + "NewName" + Console.WriteLine(el2.Name) + End Sub +End Module +``` + + This example produces the following output: + +``` +Root +{http://www.adventure-works.com}Root +http://www.adventure-works.com +Root +{http://www.adventure-works.com}NewName +``` + ]]> LINQ to XML overview @@ -4237,34 +4237,34 @@ Root Gets the node type for this node. The node type. For objects, this value is . - contain a property, you can write code that operates on collections of concrete subclass of . Your code can then test for the node type of each node in the collection. - - - -## Examples - The following example uses this property to print the node type of an element. - -```csharp -XElement el1 = new XElement("Root", "content"); -Console.WriteLine(el1.NodeType); -Console.WriteLine(); -``` - -```vb -Dim el1 As XElement = content -Console.WriteLine(el1.NodeType.ToString()) -Console.WriteLine() -``` - - This example produces the following output: - -``` -Element -``` - + contain a property, you can write code that operates on collections of concrete subclass of . Your code can then test for the node type of each node in the collection. + + + +## Examples + The following example uses this property to print the node type of an element. + +```csharp +XElement el1 = new XElement("Root", "content"); +Console.WriteLine(el1.NodeType); +Console.WriteLine(); +``` + +```vb +Dim el1 As XElement = content +Console.WriteLine(el1.NodeType.ToString()) +Console.WriteLine() +``` + + This example produces the following output: + +``` +Element +``` + ]]> LINQ to XML overview @@ -4319,44 +4319,44 @@ Element Cast the value of this to a . A that contains the content of this . - from an attribute or element, allowed values are "0", "1", and any string that produces "true" or "false" after trimming and conversion to lower case. - -## Examples - The following example creates some elements with boolean values. It then casts them to . - -```csharp -XElement root = new XElement("Root", - new XElement("BoolValue1", true), - new XElement("BoolValue2", false) -); -bool bool1 = (bool)root.Element("BoolValue1"); -bool bool2 = (bool)root.Element("BoolValue2"); -Console.WriteLine("(bool)BoolValue1={0}", bool1); -Console.WriteLine("(bool)BoolValue2={0}", bool2); -``` - -```vb -Dim root As XElement = _ - - true - false - -Dim bool1 As Boolean = CBool(root.Element("BoolValue1")) -Dim bool2 As Boolean = CBool(root.Element("BoolValue2")) -Console.WriteLine("(bool)BoolValue1={0}", bool1) -Console.WriteLine("(bool)BoolValue2={0}", bool2) -``` - - This example produces the following output: - -``` -(bool)BoolValue1=True -(bool)BoolValue2=False -``` - + +## Examples + The following example creates some elements with boolean values. It then casts them to . + +```csharp +XElement root = new XElement("Root", + new XElement("BoolValue1", true), + new XElement("BoolValue2", false) +); +bool bool1 = (bool)root.Element("BoolValue1"); +bool bool2 = (bool)root.Element("BoolValue2"); +Console.WriteLine("(bool)BoolValue1={0}", bool1); +Console.WriteLine("(bool)BoolValue2={0}", bool2); +``` + +```vb +Dim root As XElement = _ + + true + false + +Dim bool1 As Boolean = CBool(root.Element("BoolValue1")) +Dim bool2 As Boolean = CBool(root.Element("BoolValue2")) +Console.WriteLine("(bool)BoolValue1={0}", bool1) +Console.WriteLine("(bool)BoolValue2={0}", bool2) +``` + + This example produces the following output: + +``` +(bool)BoolValue1=True +(bool)BoolValue2=False +``` + ]]> The element does not contain a valid value. @@ -4413,64 +4413,64 @@ Console.WriteLine("(bool)BoolValue2={0}", bool2) Cast the value of this to a . A that contains the content of this . - from an attribute or element. Even if the attribute or element value is not formatted exactly per the W3C specification, the value is appropriately converted to a . - + from an attribute or element. Even if the attribute or element value is not formatted exactly per the W3C specification, the value is appropriately converted to a . + This conversion operator uses to convert from a . -## Examples - The following example creates an element with date and time content. It then casts it to to retrieve the value. - -```csharp -// Behavior is strict when formatting an XML element or attribute from a DateTime, -// but behavior is lax when casting to a DateTime from an element or attribute. -XElement root = new XElement("Root", new DateTime(2006, 10, 6, 12, 30, 0)); -Console.WriteLine(root); - -// Cast from a strictly formatted XML element. -DateTime dt = (DateTime)root; -Console.WriteLine("dt={0}", dt); -Console.WriteLine("-----"); - -// If root is formatted in some different way: -XElement dtElement = new XElement("OrderDate", "October 6, 2006"); -Console.WriteLine(dtElement); -DateTime orderDate = (DateTime)dtElement; -Console.WriteLine("orderDate={0:d}", orderDate); -``` - -```vb -' Behavior is strict when formatting an XML element or attribute from a DateTime, -' but behavior is lax when casting to a DateTime from an element or attribute. -Dim root As XElement = <%= New DateTime(2006, 10, 6, 12, 30, 0) %> -Console.WriteLine(root) - -' Cast from a strictly formatted XML element. -Dim dt As DateTime = CType(root, DateTime) -Console.WriteLine("dt={0}", dt) -Console.WriteLine("-----") - -' If root is formatted in some different way: -Dim dtElement As XElement = October 6, 2006 -Console.WriteLine(dtElement) -Dim orderDate As DateTime = CType(dtElement, DateTime) -Console.WriteLine("orderDate={0:d}", orderDate) -``` - - This example produces the following output: - -``` -2006-10-06T12:30:00 -dt=10/6/2006 12:30:00 PM ------ -October 6, 2006 -orderDate=10/6/2006 -``` - +## Examples + The following example creates an element with date and time content. It then casts it to to retrieve the value. + +```csharp +// Behavior is strict when formatting an XML element or attribute from a DateTime, +// but behavior is lax when casting to a DateTime from an element or attribute. +XElement root = new XElement("Root", new DateTime(2006, 10, 6, 12, 30, 0)); +Console.WriteLine(root); + +// Cast from a strictly formatted XML element. +DateTime dt = (DateTime)root; +Console.WriteLine("dt={0}", dt); +Console.WriteLine("-----"); + +// If root is formatted in some different way: +XElement dtElement = new XElement("OrderDate", "October 6, 2006"); +Console.WriteLine(dtElement); +DateTime orderDate = (DateTime)dtElement; +Console.WriteLine("orderDate={0:d}", orderDate); +``` + +```vb +' Behavior is strict when formatting an XML element or attribute from a DateTime, +' but behavior is lax when casting to a DateTime from an element or attribute. +Dim root As XElement = <%= New DateTime(2006, 10, 6, 12, 30, 0) %> +Console.WriteLine(root) + +' Cast from a strictly formatted XML element. +Dim dt As DateTime = CType(root, DateTime) +Console.WriteLine("dt={0}", dt) +Console.WriteLine("-----") + +' If root is formatted in some different way: +Dim dtElement As XElement = October 6, 2006 +Console.WriteLine(dtElement) +Dim orderDate As DateTime = CType(dtElement, DateTime) +Console.WriteLine("orderDate={0:d}", orderDate) +``` + + This example produces the following output: + +``` +2006-10-06T12:30:00 +dt=10/6/2006 12:30:00 PM +----- +October 6, 2006 +orderDate=10/6/2006 +``` + ]]> The element does not contain a valid value. @@ -4529,44 +4529,44 @@ orderDate=10/6/2006 Cast the value of this to a . A that contains the content of this . - class to do the conversion. - -## Examples - The following example creates an element with date and time content. It then casts to to retrieve the value. - -```csharp -XElement root = new XElement("Root", - new XElement("Child", new DateTimeOffset(new DateTime(2006, 10, 6, 12, 30, 0))) -); -Console.WriteLine(root); - -DateTimeOffset dt = (DateTimeOffset)root.Element("Child"); -Console.WriteLine("dt={0}", dt); -``` - -```vb -Dim root As XElement = _ - - <%= New DateTimeOffset(New DateTime(2006, 10, 6, 12, 30, 0)) %> - -Console.WriteLine(root) - -Dim dt As DateTimeOffset = CType(root.(0), DateTimeOffset) -Console.WriteLine("dt={0}", dt) -``` - - This example produces the following output: - -``` - - 2006-10-06T12:30:00-07:00 - -dt=10/6/2006 12:30:00 PM -07:00 -``` - + class to do the conversion. + +## Examples + The following example creates an element with date and time content. It then casts to to retrieve the value. + +```csharp +XElement root = new XElement("Root", + new XElement("Child", new DateTimeOffset(new DateTime(2006, 10, 6, 12, 30, 0))) +); +Console.WriteLine(root); + +DateTimeOffset dt = (DateTimeOffset)root.Element("Child"); +Console.WriteLine("dt={0}", dt); +``` + +```vb +Dim root As XElement = _ + + <%= New DateTimeOffset(New DateTime(2006, 10, 6, 12, 30, 0)) %> + +Console.WriteLine(root) + +Dim dt As DateTimeOffset = CType(root.(0), DateTimeOffset) +Console.WriteLine("dt={0}", dt) +``` + + This example produces the following output: + +``` + + 2006-10-06T12:30:00-07:00 + +dt=10/6/2006 12:30:00 PM -07:00 +``` + ]]> The element does not contain a valid value. @@ -4626,29 +4626,29 @@ dt=10/6/2006 12:30:00 PM -07:00 A that contains the content of this . . - -```csharp -XElement root = new XElement("Root", "79228162514264337593543950335"); -decimal value = (decimal)root; -Console.WriteLine("value={0}", value); -``` - -```vb -Dim root As XElement = 79228162514264337593543950335 -Dim value As Decimal = CDec(root) -Console.WriteLine("value={0}", value) - -``` - - This example produces the following output: - -``` -value=79228162514264337593543950335 -``` - + +## Examples + The following example creates an element with a decimal value. It then retrieves the value of the attribute by casting to . + +```csharp +XElement root = new XElement("Root", "79228162514264337593543950335"); +decimal value = (decimal)root; +Console.WriteLine("value={0}", value); +``` + +```vb +Dim root As XElement = 79228162514264337593543950335 +Dim value As Decimal = CDec(root) +Console.WriteLine("value={0}", value) + +``` + + This example produces the following output: + +``` +value=79228162514264337593543950335 +``` + ]]> The element does not contain a valid value. @@ -4707,28 +4707,28 @@ value=79228162514264337593543950335 Cast the value of this to a . A that contains the content of this . - . - -```csharp -XElement root = new XElement("Root", 1.79769313486231e308); -double value = (double)root; -Console.WriteLine("value={0}", value); -``` - -```vb -Dim root As XElement = 1.79769313486231E+308 -Dim value As Double = CDbl(root) -Console.WriteLine("value={0}", value) -``` - - This example produces the following output: - -``` -value=1.79769313486231E+308 -``` - + . + +```csharp +XElement root = new XElement("Root", 1.79769313486231e308); +double value = (double)root; +Console.WriteLine("value={0}", value); +``` + +```vb +Dim root As XElement = 1.79769313486231E+308 +Dim value As Double = CDbl(root) +Console.WriteLine("value={0}", value) +``` + + This example produces the following output: + +``` +value=1.79769313486231E+308 +``` + ]]> The element does not contain a valid value. @@ -4788,28 +4788,28 @@ value=1.79769313486231E+308 A that contains the content of this . . - -```csharp -XElement root = new XElement("Root", new Guid("3c1cc55b-baff-4b7a-9d17-077af3aa5730")); -Guid value = (Guid)root; -Console.WriteLine("value={0}", value); -``` - -```vb -Dim root As XElement = <%= New Guid("3c1cc55b-baff-4b7a-9d17-077af3aa5730") %> -Dim value As Guid = CType(root, Guid) -Console.WriteLine("value={0}", value) -``` - - This example produces the following output: - -``` -value=3c1cc55b-baff-4b7a-9d17-077af3aa5730 -``` - + +## Examples + The following example creates an element with a guid as content. It then retrieves the value by casting to . + +```csharp +XElement root = new XElement("Root", new Guid("3c1cc55b-baff-4b7a-9d17-077af3aa5730")); +Guid value = (Guid)root; +Console.WriteLine("value={0}", value); +``` + +```vb +Dim root As XElement = <%= New Guid("3c1cc55b-baff-4b7a-9d17-077af3aa5730") %> +Dim value As Guid = CType(root, Guid) +Console.WriteLine("value={0}", value) +``` + + This example produces the following output: + +``` +value=3c1cc55b-baff-4b7a-9d17-077af3aa5730 +``` + ]]> The element does not contain a valid value. @@ -4869,28 +4869,28 @@ value=3c1cc55b-baff-4b7a-9d17-077af3aa5730 A that contains the content of this . . - -```csharp -XElement root = new XElement("Root", 2147483647); -int value = (int)root; -Console.WriteLine("value={0}", value); -``` - -```vb -Dim root As XElement = 2147483647 -Dim value As Integer = CInt(root) -Console.WriteLine("value={0}", value) -``` - - This example produces the following output: - -``` -value=2147483647 -``` - + +## Examples + The following example creates an element with an integer as content. It then retrieves the value by casting to . + +```csharp +XElement root = new XElement("Root", 2147483647); +int value = (int)root; +Console.WriteLine("value={0}", value); +``` + +```vb +Dim root As XElement = 2147483647 +Dim value As Integer = CInt(root) +Console.WriteLine("value={0}", value) +``` + + This example produces the following output: + +``` +value=2147483647 +``` + ]]> The element does not contain a valid value. @@ -4948,28 +4948,28 @@ value=2147483647 A that contains the content of this . . - -```csharp -XElement root = new XElement("Root", 9223372036854775807); -long value = (long)root; -Console.WriteLine("value={0}", value); -``` - -```vb -Dim root As XElement = 9223372036854775807 -Dim value As Long = CLng(root) -Console.WriteLine("value={0}", value) -``` - - This example produces the following output: - -``` -value=9223372036854775807 -``` - + +## Examples + The following example creates an element with a long integer as content. It then retrieves the value of the element by casting to . + +```csharp +XElement root = new XElement("Root", 9223372036854775807); +long value = (long)root; +Console.WriteLine("value={0}", value); +``` + +```vb +Dim root As XElement = 9223372036854775807 +Dim value As Long = CLng(root) +Console.WriteLine("value={0}", value) +``` + + This example produces the following output: + +``` +value=9223372036854775807 +``` + ]]> The element does not contain a valid value. @@ -5033,44 +5033,44 @@ value=9223372036854775807 Cast the value of this to a of . A of that contains the content of this . - of from an attribute or element, allowed values are "0", "1", and any string that produces "true" or "false" after trimming and conversion to lower case. - -## Examples - The following example creates an element with boolean content. It then retrieves the value by casting to of . - -```csharp -XElement root = new XElement("Root", - new XElement("BoolValue1", true), - new XElement("BoolValue2", false)); -bool? bool1 = (bool?)root.Element("BoolValue1"); -bool? bool2 = (bool?)root.Element("BoolValue2"); -Console.WriteLine("Nullable Boolean: value1={0}", bool1); -Console.WriteLine("Nullable Boolean: value2={0}", bool2); -``` - -```vb -Dim root As XElement = _ - - true - false - - -Dim value1 As Nullable(Of Boolean) = CType(root.Element("BoolValue1"), Nullable(Of Boolean)) -Dim value2 As Nullable(Of Boolean) = CType(root.Element("BoolValue2"), Nullable(Of Boolean)) -Console.WriteLine("Nullable Boolean: value1={0}", IIf(value1.HasValue, value1.ToString(), "null")) -Console.WriteLine("Nullable Boolean: value2={0}", IIf(value2.HasValue, value2.ToString(), "null")) -``` - - This example produces the following output: - -``` -Nullable Boolean: value1=True -Nullable Boolean: value2=False -``` - + +## Examples + The following example creates an element with boolean content. It then retrieves the value by casting to of . + +```csharp +XElement root = new XElement("Root", + new XElement("BoolValue1", true), + new XElement("BoolValue2", false)); +bool? bool1 = (bool?)root.Element("BoolValue1"); +bool? bool2 = (bool?)root.Element("BoolValue2"); +Console.WriteLine("Nullable Boolean: value1={0}", bool1); +Console.WriteLine("Nullable Boolean: value2={0}", bool2); +``` + +```vb +Dim root As XElement = _ + + true + false + + +Dim value1 As Nullable(Of Boolean) = CType(root.Element("BoolValue1"), Nullable(Of Boolean)) +Dim value2 As Nullable(Of Boolean) = CType(root.Element("BoolValue2"), Nullable(Of Boolean)) +Console.WriteLine("Nullable Boolean: value1={0}", IIf(value1.HasValue, value1.ToString(), "null")) +Console.WriteLine("Nullable Boolean: value2={0}", IIf(value2.HasValue, value2.ToString(), "null")) +``` + + This example produces the following output: + +``` +Nullable Boolean: value1=True +Nullable Boolean: value2=False +``` + ]]> The element is not and does not contain a valid value. @@ -5131,41 +5131,41 @@ Nullable Boolean: value2=False Cast the value of this to a of . A of that contains the content of this . - of from an attribute or element. Even if the attribute or element value is not formatted exactly per the W3C specification, the value is appropriately converted to a of . - + of from an attribute or element. Even if the attribute or element value is not formatted exactly per the W3C specification, the value is appropriately converted to a of . + This conversion operator uses to convert from a . - -## Examples - The following example creates an element with a date and time as content. It then retrieves the value by casting to of . - + +## Examples + The following example creates an element with a date and time as content. It then retrieves the value by casting to of . + ```csharp -XElement root = new XElement("Root", - new XElement("Value", new DateTime(2006, 10, 6, 12, 30, 0)) -); -DateTime? value = (DateTime?)root.Element("Value"); -Console.WriteLine("Nullable DateTime: value={0}", value == null ? "null" : value.ToString()); -``` - -```vb -Dim root As XElement = _ - - <%= New DateTime(2006, 10, 6, 12, 30, 0) %> - -Dim value As Nullable(Of DateTime) = CType(root.Element("Value"), Nullable(Of DateTime)) -Console.WriteLine("Nullable DateTime: value={0}", IIf(value.HasValue, value.ToString(), "null")) -``` - - This example produces the following output: - -``` -Nullable DateTime: value=10/6/2006 12:30:00 PM -``` - +XElement root = new XElement("Root", + new XElement("Value", new DateTime(2006, 10, 6, 12, 30, 0)) +); +DateTime? value = (DateTime?)root.Element("Value"); +Console.WriteLine("Nullable DateTime: value={0}", value == null ? "null" : value.ToString()); +``` + +```vb +Dim root As XElement = _ + + <%= New DateTime(2006, 10, 6, 12, 30, 0) %> + +Dim value As Nullable(Of DateTime) = CType(root.Element("Value"), Nullable(Of DateTime)) +Console.WriteLine("Nullable DateTime: value={0}", IIf(value.HasValue, value.ToString(), "null")) +``` + + This example produces the following output: + +``` +Nullable DateTime: value=10/6/2006 12:30:00 PM +``` + ]]> The element is not and does not contain a valid value. @@ -5226,44 +5226,44 @@ Nullable DateTime: value=10/6/2006 12:30:00 PM Cast the value of this to a of . A of that contains the content of this . - class to do the conversion. - -## Examples - The following example creates an element with date and time content. It then casts to of to retrieve the value. - -```csharp -XElement root = new XElement("Root", - new XElement("Child", new DateTimeOffset(new DateTime(2006, 10, 6, 12, 30, 0))) -); -Console.WriteLine(root); - -DateTimeOffset? dt = (DateTimeOffset?)root.Element("Child"); -Console.WriteLine("dt={0}", dt); -``` - -```vb -Dim root As XElement = _ - - <%= New DateTimeOffset(New DateTime(2006, 10, 6, 12, 30, 0)) %> - -Console.WriteLine(root) - -Dim dt As Nullable(Of DateTimeOffset) = CType(root.(0), Nullable(Of DateTimeOffset)) -Console.WriteLine("dt={0}", dt) -``` - - This example produces the following output: - -``` - - 2006-10-06T12:30:00-07:00 - -dt=10/6/2006 12:30:00 PM -07:00 -``` - + +## Examples + The following example creates an element with date and time content. It then casts to of to retrieve the value. + +```csharp +XElement root = new XElement("Root", + new XElement("Child", new DateTimeOffset(new DateTime(2006, 10, 6, 12, 30, 0))) +); +Console.WriteLine(root); + +DateTimeOffset? dt = (DateTimeOffset?)root.Element("Child"); +Console.WriteLine("dt={0}", dt); +``` + +```vb +Dim root As XElement = _ + + <%= New DateTimeOffset(New DateTime(2006, 10, 6, 12, 30, 0)) %> + +Console.WriteLine(root) + +Dim dt As Nullable(Of DateTimeOffset) = CType(root.(0), Nullable(Of DateTimeOffset)) +Console.WriteLine("dt={0}", dt) +``` + + This example produces the following output: + +``` + + 2006-10-06T12:30:00-07:00 + +dt=10/6/2006 12:30:00 PM -07:00 +``` + ]]> The element is not and does not contain a valid value. @@ -5325,33 +5325,33 @@ dt=10/6/2006 12:30:00 PM -07:00 A of that contains the content of this . of . - -```csharp -XElement root = new XElement("Root", - new XElement("Value", "79228162514264337593543950335") -); -decimal? value = (decimal?)root.Element("Value"); -Console.WriteLine("Nullable decimal: value={0}", value == null ? "null" : value.ToString()); -``` - -```vb -Dim root As XElement = _ - - 79228162514264337593543950335 - -Dim value As Nullable(Of Decimal) = CType(root.Element("Value"), Nullable(Of Decimal)) -Console.WriteLine("Nullable decimal: value={0}", IIf(value.HasValue, value.ToString(), "null")) -``` - - This example produces the following output: - -``` -Nullable decimal: value=79228162514264337593543950335 -``` - + +## Examples + The following example creates an element with decimal content. It then retrieves the value by casting to of . + +```csharp +XElement root = new XElement("Root", + new XElement("Value", "79228162514264337593543950335") +); +decimal? value = (decimal?)root.Element("Value"); +Console.WriteLine("Nullable decimal: value={0}", value == null ? "null" : value.ToString()); +``` + +```vb +Dim root As XElement = _ + + 79228162514264337593543950335 + +Dim value As Nullable(Of Decimal) = CType(root.Element("Value"), Nullable(Of Decimal)) +Console.WriteLine("Nullable decimal: value={0}", IIf(value.HasValue, value.ToString(), "null")) +``` + + This example produces the following output: + +``` +Nullable decimal: value=79228162514264337593543950335 +``` + ]]> The element is not and does not contain a valid value. @@ -5414,33 +5414,33 @@ Nullable decimal: value=79228162514264337593543950335 of . - -```csharp -XElement root = new XElement("Root", - new XElement("Value", 1.79769313486231e308) -); -double? value = (double?)root.Element("Value"); -Console.WriteLine("Nullable double: value={0}", value == null ? "null" : value.ToString()); -``` - -```vb -Dim root As XElement = _ - - 1.79769313486231e308 - - -Dim value As Nullable(Of Double) = CType(root.Element("Value"), Nullable(Of Double)) -Console.WriteLine("Nullable double: value={0}", IIf(value.HasValue, value.ToString(), "null")) -``` - - This example produces the following output: - -``` -Nullable double: value=1.79769313486231E+308 -``` - +## Examples + The following example creates an element with double precision floating point content. It then retrieves the value by casting to of . + +```csharp +XElement root = new XElement("Root", + new XElement("Value", 1.79769313486231e308) +); +double? value = (double?)root.Element("Value"); +Console.WriteLine("Nullable double: value={0}", value == null ? "null" : value.ToString()); +``` + +```vb +Dim root As XElement = _ + + 1.79769313486231e308 + + +Dim value As Nullable(Of Double) = CType(root.Element("Value"), Nullable(Of Double)) +Console.WriteLine("Nullable double: value={0}", IIf(value.HasValue, value.ToString(), "null")) +``` + + This example produces the following output: + +``` +Nullable double: value=1.79769313486231E+308 +``` + ]]> The element is not and does not contain a valid value. @@ -5503,32 +5503,32 @@ Nullable double: value=1.79769313486231E+308 of . - -```csharp -XElement root = new XElement("Root", - new XElement("Value", new Guid("3c1cc55b-baff-4b7a-9d17-077af3aa5730")) -); -Guid? value = (Guid?)root.Element("Value"); -Console.WriteLine("Nullable Guid: value={0}", value == null ? "null" : value.ToString()); -``` - -```vb -Dim root As XElement = _ - - <%= New Guid("3c1cc55b-baff-4b7a-9d17-077af3aa5730") %> - -Dim value As Nullable(Of Guid) = CType(root.Element("Value"), Nullable(Of Guid)) -Console.WriteLine("Nullable Guid: value={0}", IIf(value.HasValue, value.ToString(), "null")) -``` - - This example produces the following output: - -``` -Nullable Guid: value=3c1cc55b-baff-4b7a-9d17-077af3aa5730 -``` - +## Examples + The following example creates an element with guid content. It then retrieves the value by casting to of . + +```csharp +XElement root = new XElement("Root", + new XElement("Value", new Guid("3c1cc55b-baff-4b7a-9d17-077af3aa5730")) +); +Guid? value = (Guid?)root.Element("Value"); +Console.WriteLine("Nullable Guid: value={0}", value == null ? "null" : value.ToString()); +``` + +```vb +Dim root As XElement = _ + + <%= New Guid("3c1cc55b-baff-4b7a-9d17-077af3aa5730") %> + +Dim value As Nullable(Of Guid) = CType(root.Element("Value"), Nullable(Of Guid)) +Console.WriteLine("Nullable Guid: value={0}", IIf(value.HasValue, value.ToString(), "null")) +``` + + This example produces the following output: + +``` +Nullable Guid: value=3c1cc55b-baff-4b7a-9d17-077af3aa5730 +``` + ]]> The element is not and does not contain a valid value. @@ -5591,33 +5591,33 @@ Nullable Guid: value=3c1cc55b-baff-4b7a-9d17-077af3aa5730 of . - -```csharp -XElement root = new XElement("Root", - new XElement("Value", 2147483647) -); -int? value = (int?)root.Element("Value"); -Console.WriteLine("Nullable integer: value={0}", value == null ? "null" : value.ToString()); -``` - -```vb -Dim root As XElement = _ - - 2147483647 - -Dim value As Nullable(Of Integer) = CType(root.Element("Value"), Nullable(Of Integer)) -Console.WriteLine("Nullable integer: value={0}", IIf(value.HasValue, value.ToString(), "null")) - -``` - - This example produces the following output: - -``` -Nullable integer: value=2147483647 -``` - +## Examples + The following example creates an element with unsigned integer content. It then retrieves the value by casting to of . + +```csharp +XElement root = new XElement("Root", + new XElement("Value", 2147483647) +); +int? value = (int?)root.Element("Value"); +Console.WriteLine("Nullable integer: value={0}", value == null ? "null" : value.ToString()); +``` + +```vb +Dim root As XElement = _ + + 2147483647 + +Dim value As Nullable(Of Integer) = CType(root.Element("Value"), Nullable(Of Integer)) +Console.WriteLine("Nullable integer: value={0}", IIf(value.HasValue, value.ToString(), "null")) + +``` + + This example produces the following output: + +``` +Nullable integer: value=2147483647 +``` + ]]> The element is not and does not contain a valid value. @@ -5680,32 +5680,32 @@ Nullable integer: value=2147483647 of . - -```csharp -XElement root = new XElement("Root", - new XElement("Value", 9223372036854775807) -); -ulong? value = (ulong?)root.Element("Value"); -Console.WriteLine("Nullable ulong: value={0}", value == null ? "null" : value.ToString()); -``` - -```vb -Dim root As XElement = _ - - 9223372036854775807 - -Dim value As Nullable(Of ULong) = CType(root.Element("Value"), Nullable(Of ULong)) -Console.WriteLine("Nullable ulong: value={0}", IIf(value.HasValue, value.ToString(), "null")) -``` - - This example produces the following output: - -``` -Nullable ulong: value=9223372036854775807 -``` - +## Examples + The following example creates an element with long integer content. It then retrieves the value by casting to of . + +```csharp +XElement root = new XElement("Root", + new XElement("Value", 9223372036854775807) +); +ulong? value = (ulong?)root.Element("Value"); +Console.WriteLine("Nullable ulong: value={0}", value == null ? "null" : value.ToString()); +``` + +```vb +Dim root As XElement = _ + + 9223372036854775807 + +Dim value As Nullable(Of ULong) = CType(root.Element("Value"), Nullable(Of ULong)) +Console.WriteLine("Nullable ulong: value={0}", IIf(value.HasValue, value.ToString(), "null")) +``` + + This example produces the following output: + +``` +Nullable ulong: value=9223372036854775807 +``` + ]]> The element is not and does not contain a valid value. @@ -5768,32 +5768,32 @@ Nullable ulong: value=9223372036854775807 of . - -```csharp -XElement root = new XElement("Root", - new XElement("Value", 3.402823e38) -); -float? value = (float?)root.Element("Value"); -Console.WriteLine("Nullable Single: value={0}", value == null ? "null" : value.ToString()); -``` - -```vb -Dim root As XElement = _ - - 3.402823e38 - -Dim value As Nullable(Of Single) = CType(root.Element("Value"), Nullable(Of Single)) -Console.WriteLine("Nullable Single: value={0}", IIf(value.HasValue, value.ToString(), "null")) -``` - - This example produces the following output: - -``` -Nullable Single: value=3.402823E+38 -``` - +## Examples + The following example creates an element with single precision floating point content. It then retrieves the value by casting to of . + +```csharp +XElement root = new XElement("Root", + new XElement("Value", 3.402823e38) +); +float? value = (float?)root.Element("Value"); +Console.WriteLine("Nullable Single: value={0}", value == null ? "null" : value.ToString()); +``` + +```vb +Dim root As XElement = _ + + 3.402823e38 + +Dim value As Nullable(Of Single) = CType(root.Element("Value"), Nullable(Of Single)) +Console.WriteLine("Nullable Single: value={0}", IIf(value.HasValue, value.ToString(), "null")) +``` + + This example produces the following output: + +``` +Nullable Single: value=3.402823E+38 +``` + ]]> The element is not and does not contain a valid value. @@ -5854,39 +5854,39 @@ Nullable Single: value=3.402823E+38 Cast the value of this to a of . A of that contains the content of this . - of from an attribute or element. Even if the attribute or element value is not formatted exactly per the W3C specification, the value is appropriately converted to a of . - -## Examples - The following example creates an element with time span content. It then retrieves the value by casting to of . - -```csharp -XElement root = new XElement("Root", - new XElement("Value", new TimeSpan(1, 5, 30)) -); -TimeSpan? value = (TimeSpan?)root.Element("Value"); -Console.WriteLine("Nullable TimeSpan: value={0}", value == null ? "null" : value.ToString()); -``` - -```vb -Dim root As XElement = _ - - <%= New TimeSpan(1, 5, 30) %> - -Dim value As Nullable(Of TimeSpan) = CType(root.Element("Value"), Nullable(Of TimeSpan)) -Console.WriteLine("Nullable TimeSpan: value={0}", IIf(value.HasValue, value.ToString(), "null")) -``` - - This example produces the following output: - -``` -Nullable TimeSpan: value=01:05:30 -``` - + +## Examples + The following example creates an element with time span content. It then retrieves the value by casting to of . + +```csharp +XElement root = new XElement("Root", + new XElement("Value", new TimeSpan(1, 5, 30)) +); +TimeSpan? value = (TimeSpan?)root.Element("Value"); +Console.WriteLine("Nullable TimeSpan: value={0}", value == null ? "null" : value.ToString()); +``` + +```vb +Dim root As XElement = _ + + <%= New TimeSpan(1, 5, 30) %> + +Dim value As Nullable(Of TimeSpan) = CType(root.Element("Value"), Nullable(Of TimeSpan)) +Console.WriteLine("Nullable TimeSpan: value={0}", IIf(value.HasValue, value.ToString(), "null")) +``` + + This example produces the following output: + +``` +Nullable TimeSpan: value=01:05:30 +``` + ]]> The element is not and does not contain a valid value. @@ -5949,32 +5949,32 @@ Nullable TimeSpan: value=01:05:30 of . - -```csharp -XElement root = new XElement("Root", - new XElement("Value", 4294967295) -); -uint? value = (uint?)root.Element("Value"); -Console.WriteLine("Nullable uint: value={0}", value == null ? "null" : value.ToString()); -``` - -```vb -Dim root As XElement = _ - - 4294967295 - -Dim value As Nullable(Of UInteger) = CType(root.Element("Value"), Nullable(Of UInteger)) -Console.WriteLine("Nullable uint: value={0}", IIf(value.HasValue, value.ToString(), "null")) -``` - - This example produces the following output: - -``` -Nullable uint: value=4294967295 -``` - +## Examples + The following example creates an element with unsigned integer content. It then retrieves the value by casting to of . + +```csharp +XElement root = new XElement("Root", + new XElement("Value", 4294967295) +); +uint? value = (uint?)root.Element("Value"); +Console.WriteLine("Nullable uint: value={0}", value == null ? "null" : value.ToString()); +``` + +```vb +Dim root As XElement = _ + + 4294967295 + +Dim value As Nullable(Of UInteger) = CType(root.Element("Value"), Nullable(Of UInteger)) +Console.WriteLine("Nullable uint: value={0}", IIf(value.HasValue, value.ToString(), "null")) +``` + + This example produces the following output: + +``` +Nullable uint: value=4294967295 +``` + ]]> The element is not and does not contain a valid value. @@ -6037,33 +6037,33 @@ Nullable uint: value=4294967295 of . - -```csharp -XElement root = new XElement("Root", - new XElement("Value", 9223372036854775807) -); -ulong? value = (ulong?)root.Element("Value"); -Console.WriteLine("Nullable ulong: value={0}", value == null ? "null" : value.ToString()); -``` - -```vb -Dim root As XElement = _ - - 9223372036854775807 - - -Dim value As Nullable(Of ULong) = CType(root.Element("Value"), Nullable(Of ULong)) -Console.WriteLine("Nullable ulong: value={0}", IIf(value.HasValue, value.ToString(), "null")) -``` - - This example produces the following output: - -``` -Nullable ulong: value=9223372036854775807 -``` - +## Examples + The following example creates an element with unsigned long integer content. It then retrieves the value by casting to of . + +```csharp +XElement root = new XElement("Root", + new XElement("Value", 9223372036854775807) +); +ulong? value = (ulong?)root.Element("Value"); +Console.WriteLine("Nullable ulong: value={0}", value == null ? "null" : value.ToString()); +``` + +```vb +Dim root As XElement = _ + + 9223372036854775807 + + +Dim value As Nullable(Of ULong) = CType(root.Element("Value"), Nullable(Of ULong)) +Console.WriteLine("Nullable ulong: value={0}", IIf(value.HasValue, value.ToString(), "null")) +``` + + This example produces the following output: + +``` +Nullable ulong: value=9223372036854775807 +``` + ]]> The element is not and does not contain a valid value. @@ -6120,28 +6120,28 @@ Nullable ulong: value=9223372036854775807 A that contains the content of this . . - -```csharp -XElement root = new XElement("Root", 3.402823e38); -float value = (float)root; -Console.WriteLine("value={0}", value); -``` - -```vb -Dim root As XElement = 3.402823E+38 -Dim value As Single = CSng(root) -Console.WriteLine("value={0}", value) -``` - - This example produces the following output: - -``` -value=3.402823E+38 -``` - + +## Examples + The following example creates an element with single precision floating point content. It then retrieves the value by casting to . + +```csharp +XElement root = new XElement("Root", 3.402823e38); +float value = (float)root; +Console.WriteLine("value={0}", value); +``` + +```vb +Dim root As XElement = 3.402823E+38 +Dim value As Single = CSng(root) +Console.WriteLine("value={0}", value) +``` + + This example produces the following output: + +``` +value=3.402823E+38 +``` + ]]> The element does not contain a valid value. @@ -6205,30 +6205,30 @@ value=3.402823E+38 Cast the value of this to a . A that contains the content of this . - has children, the concatenated string value of all of the element's text and descendant's text is returned. - -## Examples - The following example creates an element with string content. It then retrieves the value by casting to . - -```csharp -XElement root = XElement.Parse("abc def ghi"); -Console.WriteLine("(string)root={0}", (string)root); -``` - -```vb -Dim root As XElement = abc def ghi -Console.WriteLine("(string)root={0}", root.Value) -``` - - This example produces the following output: - -``` -(string)root=abc def ghi -``` - + has children, the concatenated string value of all of the element's text and descendant's text is returned. + +## Examples + The following example creates an element with string content. It then retrieves the value by casting to . + +```csharp +XElement root = XElement.Parse("abc def ghi"); +Console.WriteLine("(string)root={0}", (string)root); +``` + +```vb +Dim root As XElement = abc def ghi +Console.WriteLine("(string)root={0}", root.Value) +``` + + This example produces the following output: + +``` +(string)root=abc def ghi +``` + ]]> LINQ to XML overview @@ -6283,34 +6283,34 @@ Console.WriteLine("(string)root={0}", root.Value) Cast the value of this to a . A that contains the content of this . - from an attribute or element. Even if the attribute or element value is not formatted exactly per the W3C specification, the value is appropriately converted to a . - -## Examples - The following example creates an element with time span content. It then retrieves the value by casting to . - -```csharp -XElement root = new XElement("Root", new TimeSpan(1, 5, 30)); -TimeSpan value = (TimeSpan)root; -Console.WriteLine("value={0}", value); -``` - -```vb -Dim root As XElement = <%= New TimeSpan(1, 5, 30) %> -Dim value As TimeSpan = CType(root, TimeSpan) -Console.WriteLine("value={0}", value) -``` - - This example produces the following output: - -``` -value=01:05:30 -``` - + +## Examples + The following example creates an element with time span content. It then retrieves the value by casting to . + +```csharp +XElement root = new XElement("Root", new TimeSpan(1, 5, 30)); +TimeSpan value = (TimeSpan)root; +Console.WriteLine("value={0}", value); +``` + +```vb +Dim root As XElement = <%= New TimeSpan(1, 5, 30) %> +Dim value As TimeSpan = CType(root, TimeSpan) +Console.WriteLine("value={0}", value) +``` + + This example produces the following output: + +``` +value=01:05:30 +``` + ]]> The element does not contain a valid value. @@ -6369,27 +6369,27 @@ value=01:05:30 . - -```csharp -XElement root = new XElement("Root", 4294967295); -uint value = (uint)root; -Console.WriteLine("value={0}", value); -``` - -```vb -Dim root As XElement = 4294967295 -Dim value As UInteger = CUInt(root) -Console.WriteLine("value={0}", value) -``` - - This example produces the following output: - -``` -value=4294967295 -``` - +## Examples + The following example creates an element with unsigned integer content. It then retrieves the value by casting to . + +```csharp +XElement root = new XElement("Root", 4294967295); +uint value = (uint)root; +Console.WriteLine("value={0}", value); +``` + +```vb +Dim root As XElement = 4294967295 +Dim value As UInteger = CUInt(root) +Console.WriteLine("value={0}", value) +``` + + This example produces the following output: + +``` +value=4294967295 +``` + ]]> The element does not contain a valid value. @@ -6447,28 +6447,28 @@ value=4294967295 A that contains the content of this . . - -```csharp -XElement root = new XElement("Root", 18446744073709551615); -ulong value = (ulong)root; -Console.WriteLine("value={0}", value); -``` - -```vb -Dim root As XElement = 18446744073709551615 -Dim value As ULong = CULng(root) -Console.WriteLine("value={0}", value) -``` - - This example produces the following output: - -``` -value=18446744073709551615 -``` - + +## Examples + The following example creates an element with unsigned long integer content. It then retrieves the value by casting to . + +```csharp +XElement root = new XElement("Root", 18446744073709551615); +ulong value = (ulong)root; +Console.WriteLine("value={0}", value); +``` + +```vb +Dim root As XElement = 18446744073709551615 +Dim value As ULong = CULng(root) +Console.WriteLine("value={0}", value) +``` + + This example produces the following output: + +``` +value=18446744073709551615 +``` + ]]> The element does not contain a valid value. @@ -6539,36 +6539,36 @@ value=18446744073709551615 Load an from a string that contains XML. An populated from the string that contains XML. - method that takes as a parameter. For more information, see [Preserve white space while loading or parsing XML](/dotnet/standard/linq/preserve-white-space-loading-parsing-xml) and [Preserve white space while serializing](/dotnet/standard/linq/preserve-white-space-serializing). - - LINQ to XML's loading functionality is built upon . Therefore, you might catch any exceptions that are thrown by the overload methods and the methods that read and parse the document. - - - -## Examples - The following example creates a string that contains XML. It then parses the string into an . - -```csharp -XElement xmlTree = XElement.Parse(" "); -Console.WriteLine(xmlTree); -``` - -```vb -Dim xmlTree As XElement = -Console.WriteLine(xmlTree) -``` - - This example produces the following output: - -```xml - - - -``` - + method that takes as a parameter. For more information, see [Preserve white space while loading or parsing XML](/dotnet/standard/linq/preserve-white-space-loading-parsing-xml) and [Preserve white space while serializing](/dotnet/standard/linq/preserve-white-space-serializing). + + LINQ to XML's loading functionality is built upon . Therefore, you might catch any exceptions that are thrown by the overload methods and the methods that read and parse the document. + + + +## Examples + The following example creates a string that contains XML. It then parses the string into an . + +```csharp +XElement xmlTree = XElement.Parse(" "); +Console.WriteLine(xmlTree); +``` + +```vb +Dim xmlTree As XElement = +Console.WriteLine(xmlTree) +``` + + This example produces the following output: + +```xml + + + +``` + ]]> LINQ to XML overview @@ -6619,144 +6619,144 @@ Console.WriteLine(xmlTree) Load an from a string that contains XML, optionally preserving white space and retaining line information. An populated from the string that contains XML. - flag in `options` causes the reader to read all white space in the source XML. Nodes of type are created for both significant and insignificant white space. - - If the source XML is indented, not setting the flag in `options` causes the reader to ignore all of the insignificant white space in the source XML. The XML tree is created without any text nodes for insignificant white space. - - If the source XML is not indented, setting the flag in `options` has no effect. Significant white space is still preserved, and there are no spans of insignificant white space that could cause the creation of more white space text nodes. - - For more information, see [Preserve white space while loading or parsing XML](/dotnet/standard/linq/preserve-white-space-loading-parsing-xml) and [Preserve white space while serializing](/dotnet/standard/linq/preserve-white-space-serializing). - - Setting will have no effect when parsing from a . - - The may have a valid line information or not. If you set , the line information will be set in the XML tree from the line information that is reported by the . - - There is a performance penalty if you set the flag. - - The line information is accurate immediately after loading the XML document. If you modify the XML tree after loading the document, the line information may become meaningless. - - LINQ to XML's loading functionality is built upon . Therefore, you might catch any exceptions that are thrown by the overload methods and the methods that read and parse the document. - - - -## Examples - The following example parses a string into an in two different ways: preserving white space, and not preserving white space. It then uses a query to determine the number of white space nodes in the resulting XML tree. - -```csharp -int whiteSpaceNodes; - -XElement xmlTree1 = XElement.Parse(" ", - LoadOptions.None); -whiteSpaceNodes = xmlTree1 - .DescendantNodesAndSelf() - .OfType() - .Where(tNode => tNode.ToString().Trim().Length == 0) - .Count(); -Console.WriteLine("Count of white space nodes (not preserving whitespace): {0}", - whiteSpaceNodes); - -XElement xmlTree2 = XElement.Parse(" ", - LoadOptions.PreserveWhitespace); -whiteSpaceNodes = xmlTree2 - .DescendantNodesAndSelf() - .OfType() - .Where(tNode => tNode.ToString().Trim().Length == 0) - .Count(); -Console.WriteLine("Count of white space nodes (preserving whitespace): {0}", - whiteSpaceNodes); -``` - -```vb -Dim whiteSpaceNodes As Integer - -Dim xmlTree1 As XElement = XElement.Parse(" ", LoadOptions.None) -whiteSpaceNodes = xmlTree1 _ - .DescendantNodesAndSelf() _ - .OfType(Of XText)() _ - .Where(Function(ByVal tNode As XNode) tNode.ToString().Trim().Length = 0) _ - .Count() -Console.WriteLine("Count of white space nodes (not preserving whitespace): {0}", whiteSpaceNodes) - -Dim xmlTree2 As XElement = XElement.Parse(" ", LoadOptions.PreserveWhitespace) -whiteSpaceNodes = xmlTree2 _ - .DescendantNodesAndSelf() _ - .OfType(Of XText)() _ - .Where(Function(ByVal tNode As XNode) tNode.ToString().Trim().Length = 0) _ - .Count() -Console.WriteLine("Count of white space nodes (preserving whitespace): {0}", whiteSpaceNodes) -``` - - This example produces the following output: - -``` -Count of white space nodes (not preserving whitespace): 0 -Count of white space nodes (preserving whitespace): 3 -``` - - The following example retains line information as it parses the string. - -```csharp -string markup = -@" - - - -"; - -XElement xRoot = XElement.Parse(markup, LoadOptions.SetLineInfo); -Console.WriteLine("{0}{1}{2}", - "Element Name".PadRight(20), - "Line".PadRight(5), - "Position"); -Console.WriteLine("{0}{1}{2}", - "------------".PadRight(20), - "----".PadRight(5), - "--------"); -foreach (XElement e in xRoot.DescendantsAndSelf()) - Console.WriteLine("{0}{1}{2}", - ("".PadRight(e.Ancestors().Count() * 2) + e.Name).PadRight(20), - ((IXmlLineInfo)e).LineNumber.ToString().PadRight(5), - ((IXmlLineInfo)e).LinePosition); -``` - -```vb -Dim markup As String = _ -"" & Environment.NewLine & _ -" " & Environment.NewLine & _ -" " & Environment.NewLine & _ -" " & Environment.NewLine & _ -"" - -Dim xRoot As XElement = XElement.Parse(markup, LoadOptions.SetLineInfo) -Console.WriteLine("{0}{1}{2}", _ - "Element Name".PadRight(20), _ - "Line".PadRight(5), _ - "Position") -Console.WriteLine("{0}{1}{2}", _ - "------------".PadRight(20), _ - "----".PadRight(5), _ - "--------") -For Each e As XElement In xRoot.DescendantsAndSelf() - Console.WriteLine("{0}{1}{2}", _ - ("".PadRight(e.Ancestors().Count() * 2) & e.Name.ToString).PadRight(20), _ - DirectCast(e, IXmlLineInfo).LineNumber.ToString().PadRight(5), _ - DirectCast(e, IXmlLineInfo).LinePosition) -Next -``` - - This example produces the following output: - -``` -Element Name Line Position ------------- ---- -------- -Root 1 2 - Child 2 6 - GrandChild 3 10 -``` - + flag in `options` causes the reader to read all white space in the source XML. Nodes of type are created for both significant and insignificant white space. + + If the source XML is indented, not setting the flag in `options` causes the reader to ignore all of the insignificant white space in the source XML. The XML tree is created without any text nodes for insignificant white space. + + If the source XML is not indented, setting the flag in `options` has no effect. Significant white space is still preserved, and there are no spans of insignificant white space that could cause the creation of more white space text nodes. + + For more information, see [Preserve white space while loading or parsing XML](/dotnet/standard/linq/preserve-white-space-loading-parsing-xml) and [Preserve white space while serializing](/dotnet/standard/linq/preserve-white-space-serializing). + + Setting will have no effect when parsing from a . + + The may have a valid line information or not. If you set , the line information will be set in the XML tree from the line information that is reported by the . + + There is a performance penalty if you set the flag. + + The line information is accurate immediately after loading the XML document. If you modify the XML tree after loading the document, the line information may become meaningless. + + LINQ to XML's loading functionality is built upon . Therefore, you might catch any exceptions that are thrown by the overload methods and the methods that read and parse the document. + + + +## Examples + The following example parses a string into an in two different ways: preserving white space, and not preserving white space. It then uses a query to determine the number of white space nodes in the resulting XML tree. + +```csharp +int whiteSpaceNodes; + +XElement xmlTree1 = XElement.Parse(" ", + LoadOptions.None); +whiteSpaceNodes = xmlTree1 + .DescendantNodesAndSelf() + .OfType() + .Where(tNode => tNode.ToString().Trim().Length == 0) + .Count(); +Console.WriteLine("Count of white space nodes (not preserving whitespace): {0}", + whiteSpaceNodes); + +XElement xmlTree2 = XElement.Parse(" ", + LoadOptions.PreserveWhitespace); +whiteSpaceNodes = xmlTree2 + .DescendantNodesAndSelf() + .OfType() + .Where(tNode => tNode.ToString().Trim().Length == 0) + .Count(); +Console.WriteLine("Count of white space nodes (preserving whitespace): {0}", + whiteSpaceNodes); +``` + +```vb +Dim whiteSpaceNodes As Integer + +Dim xmlTree1 As XElement = XElement.Parse(" ", LoadOptions.None) +whiteSpaceNodes = xmlTree1 _ + .DescendantNodesAndSelf() _ + .OfType(Of XText)() _ + .Where(Function(ByVal tNode As XNode) tNode.ToString().Trim().Length = 0) _ + .Count() +Console.WriteLine("Count of white space nodes (not preserving whitespace): {0}", whiteSpaceNodes) + +Dim xmlTree2 As XElement = XElement.Parse(" ", LoadOptions.PreserveWhitespace) +whiteSpaceNodes = xmlTree2 _ + .DescendantNodesAndSelf() _ + .OfType(Of XText)() _ + .Where(Function(ByVal tNode As XNode) tNode.ToString().Trim().Length = 0) _ + .Count() +Console.WriteLine("Count of white space nodes (preserving whitespace): {0}", whiteSpaceNodes) +``` + + This example produces the following output: + +``` +Count of white space nodes (not preserving whitespace): 0 +Count of white space nodes (preserving whitespace): 3 +``` + + The following example retains line information as it parses the string. + +```csharp +string markup = +@" + + + +"; + +XElement xRoot = XElement.Parse(markup, LoadOptions.SetLineInfo); +Console.WriteLine("{0}{1}{2}", + "Element Name".PadRight(20), + "Line".PadRight(5), + "Position"); +Console.WriteLine("{0}{1}{2}", + "------------".PadRight(20), + "----".PadRight(5), + "--------"); +foreach (XElement e in xRoot.DescendantsAndSelf()) + Console.WriteLine("{0}{1}{2}", + ("".PadRight(e.Ancestors().Count() * 2) + e.Name).PadRight(20), + ((IXmlLineInfo)e).LineNumber.ToString().PadRight(5), + ((IXmlLineInfo)e).LinePosition); +``` + +```vb +Dim markup As String = _ +"" & Environment.NewLine & _ +" " & Environment.NewLine & _ +" " & Environment.NewLine & _ +" " & Environment.NewLine & _ +"" + +Dim xRoot As XElement = XElement.Parse(markup, LoadOptions.SetLineInfo) +Console.WriteLine("{0}{1}{2}", _ + "Element Name".PadRight(20), _ + "Line".PadRight(5), _ + "Position") +Console.WriteLine("{0}{1}{2}", _ + "------------".PadRight(20), _ + "----".PadRight(5), _ + "--------") +For Each e As XElement In xRoot.DescendantsAndSelf() + Console.WriteLine("{0}{1}{2}", _ + ("".PadRight(e.Ancestors().Count() * 2) & e.Name.ToString).PadRight(20), _ + DirectCast(e, IXmlLineInfo).LineNumber.ToString().PadRight(5), _ + DirectCast(e, IXmlLineInfo).LinePosition) +Next +``` + + This example produces the following output: + +``` +Element Name Line Position +------------ ---- -------- +Root 1 2 + Child 2 6 + GrandChild 3 10 +``` + ]]> LINQ to XML overview @@ -6801,47 +6801,47 @@ Root 1 2 Removes nodes and attributes from this . - and the events. - - - -## Examples - The following example creates an element with attributes and child elements. It then calls this method to remove both the attributes and the child elements. - -```csharp -XElement root = new XElement("Root", - new XAttribute("Att1", 1), - new XAttribute("Att2", 2), - new XAttribute("Att3", 3), - new XElement("Child1", 1), - new XElement("Child2", 2), - new XElement("Child3", 3) -); -root.RemoveAll(); // removes children elements and attributes of root -Console.WriteLine(root); -``` - -```vb -Dim root As XElement = _ - - 1 - 2 - 3 - - -root.RemoveAll() ' removes children elements and attributes of root -Console.WriteLine(root) -``` - - This example produces the following output: - -```xml - -``` - + and the events. + + + +## Examples + The following example creates an element with attributes and child elements. It then calls this method to remove both the attributes and the child elements. + +```csharp +XElement root = new XElement("Root", + new XAttribute("Att1", 1), + new XAttribute("Att2", 2), + new XAttribute("Att3", 3), + new XElement("Child1", 1), + new XElement("Child2", 2), + new XElement("Child3", 3) +); +root.RemoveAll(); // removes children elements and attributes of root +Console.WriteLine(root); +``` + +```vb +Dim root As XElement = _ + + 1 + 2 + 3 + + +root.RemoveAll() ' removes children elements and attributes of root +Console.WriteLine(root) +``` + + This example produces the following output: + +```xml + +``` + ]]> @@ -6888,51 +6888,51 @@ Console.WriteLine(root) Removes the attributes of this . - and the events. - - - -## Examples - The following example creates an element with attributes and child elements. It then calls this method to remove the attributes. The child elements remain. - -```csharp -XElement root = new XElement("Root", - new XAttribute("Att1", 1), - new XAttribute("Att2", 2), - new XAttribute("Att3", 3), - new XElement("Child1", 1), - new XElement("Child2", 2), - new XElement("Child3", 3) -); -root.RemoveAttributes(); -Console.WriteLine(root); -``` - -```vb -Dim root As XElement = _ - - 1 - 2 - 3 - - -root.RemoveAttributes() -Console.WriteLine(root) -``` - - This example produces the following output: - -```xml - - 1 - 2 - 3 - -``` - + and the events. + + + +## Examples + The following example creates an element with attributes and child elements. It then calls this method to remove the attributes. The child elements remain. + +```csharp +XElement root = new XElement("Root", + new XAttribute("Att1", 1), + new XAttribute("Att2", 2), + new XAttribute("Att3", 3), + new XElement("Child1", 1), + new XElement("Child2", 2), + new XElement("Child3", 3) +); +root.RemoveAttributes(); +Console.WriteLine(root); +``` + +```vb +Dim root As XElement = _ + + 1 + 2 + 3 + + +root.RemoveAttributes() +Console.WriteLine(root) +``` + + This example produces the following output: + +```xml + + 1 + 2 + 3 + +``` + ]]> @@ -6949,81 +6949,81 @@ Console.WriteLine(root) Replaces the child nodes and the attributes of this element with the specified content. - and the events. - - - -## Examples - The following example passes the results of a LINQ query to this method, replacing the contents of an element with the query results. It queries the element that is having its contents replaced. - -```csharp -XElement xmlTree = new XElement("Root", - new XElement("Data", 1), - new XElement("Data", 2), - new XElement("Data", 3), - new XElement("Data", 4), - new XElement("Data", 5) -); - -Console.WriteLine(xmlTree); -Console.WriteLine("-----"); - -xmlTree.ReplaceAll( - from el in xmlTree.Elements() - where (int)el >= 3 - select new XElement("NewData", (int)el) -); - -Console.WriteLine(xmlTree); -``` - -```vb -Dim xmlTree As XElement = _ - - 1 - 2 - 3 - 4 - 5 - - -Console.WriteLine(xmlTree) -Console.WriteLine("-----") - -xmlTree.ReplaceAll( _ - From el In xmlTree.Elements _ - Where el.Value >= 3 _ - Select <%= el.Value %> _ -) - -Console.WriteLine(xmlTree) -``` - - This example produces the following output: - -``` - - 1 - 2 - 3 - 4 - 5 - ------ - - 3 - 4 - 5 - -``` - + and the events. + + + +## Examples + The following example passes the results of a LINQ query to this method, replacing the contents of an element with the query results. It queries the element that is having its contents replaced. + +```csharp +XElement xmlTree = new XElement("Root", + new XElement("Data", 1), + new XElement("Data", 2), + new XElement("Data", 3), + new XElement("Data", 4), + new XElement("Data", 5) +); + +Console.WriteLine(xmlTree); +Console.WriteLine("-----"); + +xmlTree.ReplaceAll( + from el in xmlTree.Elements() + where (int)el >= 3 + select new XElement("NewData", (int)el) +); + +Console.WriteLine(xmlTree); +``` + +```vb +Dim xmlTree As XElement = _ + + 1 + 2 + 3 + 4 + 5 + + +Console.WriteLine(xmlTree) +Console.WriteLine("-----") + +xmlTree.ReplaceAll( _ + From el In xmlTree.Elements _ + Where el.Value >= 3 _ + Select <%= el.Value %> _ +) + +Console.WriteLine(xmlTree) +``` + + This example produces the following output: + +``` + + 1 + 2 + 3 + 4 + 5 + +----- + + 3 + 4 + 5 + +``` + ]]> LINQ to XML overview @@ -7078,156 +7078,156 @@ Console.WriteLine(xmlTree) The content that will replace the child nodes and attributes of this element. Replaces the child nodes and the attributes of this element with the specified content. - and the events. - - - -## Examples - The following example uses this method. - -```csharp -XElement root = new XElement("Root", - new XElement("Child", "child content") -); - -// ReplaceAll with an XElement object. -root.ReplaceAll(new XElement("NewChild", "n")); -Console.WriteLine(root); - -// ReplaceAll with an XAttribute object. -root.ReplaceAll(new XAttribute("NewAttribute", "n")); -Console.WriteLine(root); - -// ReplaceAll with a string. -root.ReplaceAll("Some text"); -Console.WriteLine(root); - -// ReplaceAll with a double. -double dbl = 12.345; -root.ReplaceAll(dbl); -Console.WriteLine(root); - -// ReplaceAll with a DateTime object. -DateTime dt = new DateTime(2006, 10, 6, 12, 30, 00); -root.ReplaceAll(dt); -Console.WriteLine(root); - -// ReplaceAll with a string array. -// Any collection other than a collection of XElement or XAttribute objects -// are converted to strings. The strings are concatenated and added. -string[] stringArray = { - "abc", - "def", - "ghi" -}; -root.ReplaceAll(stringArray); -Console.WriteLine(root); - -// ReplaceAll with an array of XElement objects. -XElement[] ellArray = { - new XElement("NewChild1", 1), - new XElement("NewChild2", 2), - new XElement("NewChild3", 3) -}; -root.ReplaceAll(ellArray); -Console.WriteLine(root); - -// ReplaceAll with an array of XAttribute objects. -XAttribute[] attArray = { - new XAttribute("NewAtt1", 1), - new XAttribute("NewAtt2", 2), - new XAttribute("NewAtt3", 3) -}; -root.ReplaceAll(attArray); -Console.WriteLine(root); -``` - -```vb -Dim root As XElement = _ - - child content - - -' ReplaceAll with an XElement object. -root.ReplaceAll(n) -Console.WriteLine(root) - -' ReplaceAll with an XAttribute object. -root.ReplaceAll(New XAttribute("NewAttribute", "n")) -Console.WriteLine(root) - -' ReplaceAll with a string. -root.ReplaceAll("Some text") -Console.WriteLine(root) - -' ReplaceAll with a double. -Dim dbl As Double = 12.345 -root.ReplaceAll(dbl) -Console.WriteLine(root) - -' ReplaceAll with a DateTime object. -Dim dt As DateTime = New DateTime(2006, 10, 6, 12, 30, 0) -root.ReplaceAll(dt) -Console.WriteLine(root) - -' ReplaceAll with a string array. -' Any collection other than a collection of XElement or XAttribute objects -' are converted to strings. The strings are concatenated and added. -Dim stringArray As String() = { _ - "abc", _ - "def", _ - "ghi" _ -} -root.ReplaceAll(stringArray) -Console.WriteLine(root) - -' ReplaceAll with an array of XElement objects. -Dim ellArray As XElement() = { _ - New XElement("NewChild1", 1), _ - New XElement("NewChild2", 2), _ - New XElement("NewChild3", 3) _ -} -root.ReplaceAll(ellArray) -Console.WriteLine(root) - -' ReplaceAll with an array of XAttribute objects. -Dim attArray As XAttribute() = { _ -New XAttribute("NewAtt1", 1), _ -New XAttribute("NewAtt2", 2), _ -New XAttribute("NewAtt3", 3) _ -} -root.ReplaceAll(attArray) -Console.WriteLine(root) -``` - - This example produces the following output: - -```xml - - n - - -Some text -12.345 -2006-10-06T12:30:00 -abcdefghi - - 1 - 2 - 3 - - -``` - + and the events. + + + +## Examples + The following example uses this method. + +```csharp +XElement root = new XElement("Root", + new XElement("Child", "child content") +); + +// ReplaceAll with an XElement object. +root.ReplaceAll(new XElement("NewChild", "n")); +Console.WriteLine(root); + +// ReplaceAll with an XAttribute object. +root.ReplaceAll(new XAttribute("NewAttribute", "n")); +Console.WriteLine(root); + +// ReplaceAll with a string. +root.ReplaceAll("Some text"); +Console.WriteLine(root); + +// ReplaceAll with a double. +double dbl = 12.345; +root.ReplaceAll(dbl); +Console.WriteLine(root); + +// ReplaceAll with a DateTime object. +DateTime dt = new DateTime(2006, 10, 6, 12, 30, 00); +root.ReplaceAll(dt); +Console.WriteLine(root); + +// ReplaceAll with a string array. +// Any collection other than a collection of XElement or XAttribute objects +// are converted to strings. The strings are concatenated and added. +string[] stringArray = { + "abc", + "def", + "ghi" +}; +root.ReplaceAll(stringArray); +Console.WriteLine(root); + +// ReplaceAll with an array of XElement objects. +XElement[] ellArray = { + new XElement("NewChild1", 1), + new XElement("NewChild2", 2), + new XElement("NewChild3", 3) +}; +root.ReplaceAll(ellArray); +Console.WriteLine(root); + +// ReplaceAll with an array of XAttribute objects. +XAttribute[] attArray = { + new XAttribute("NewAtt1", 1), + new XAttribute("NewAtt2", 2), + new XAttribute("NewAtt3", 3) +}; +root.ReplaceAll(attArray); +Console.WriteLine(root); +``` + +```vb +Dim root As XElement = _ + + child content + + +' ReplaceAll with an XElement object. +root.ReplaceAll(n) +Console.WriteLine(root) + +' ReplaceAll with an XAttribute object. +root.ReplaceAll(New XAttribute("NewAttribute", "n")) +Console.WriteLine(root) + +' ReplaceAll with a string. +root.ReplaceAll("Some text") +Console.WriteLine(root) + +' ReplaceAll with a double. +Dim dbl As Double = 12.345 +root.ReplaceAll(dbl) +Console.WriteLine(root) + +' ReplaceAll with a DateTime object. +Dim dt As DateTime = New DateTime(2006, 10, 6, 12, 30, 0) +root.ReplaceAll(dt) +Console.WriteLine(root) + +' ReplaceAll with a string array. +' Any collection other than a collection of XElement or XAttribute objects +' are converted to strings. The strings are concatenated and added. +Dim stringArray As String() = { _ + "abc", _ + "def", _ + "ghi" _ +} +root.ReplaceAll(stringArray) +Console.WriteLine(root) + +' ReplaceAll with an array of XElement objects. +Dim ellArray As XElement() = { _ + New XElement("NewChild1", 1), _ + New XElement("NewChild2", 2), _ + New XElement("NewChild3", 3) _ +} +root.ReplaceAll(ellArray) +Console.WriteLine(root) + +' ReplaceAll with an array of XAttribute objects. +Dim attArray As XAttribute() = { _ +New XAttribute("NewAtt1", 1), _ +New XAttribute("NewAtt2", 2), _ +New XAttribute("NewAtt3", 3) _ +} +root.ReplaceAll(attArray) +Console.WriteLine(root) +``` + + This example produces the following output: + +```xml + + n + + +Some text +12.345 +2006-10-06T12:30:00 +abcdefghi + + 1 + 2 + 3 + + +``` + ]]> LINQ to XML overview @@ -7293,78 +7293,78 @@ Console.WriteLine(root) A parameter list of content objects. Replaces the child nodes and the attributes of this element with the specified content. - and the events. - - - -## Examples - The following example passes the results of a LINQ query to this method, replacing the contents of an element with the query results. - -```csharp -XElement xmlTree1 = new XElement("Root", - new XElement("Child1", 1), - new XElement("Child2", 2), - new XElement("Child3", 3), - new XElement("Child4", 4), - new XElement("Child5", 5), - new XElement("Child6", 6) -); - -XElement root = new XElement("Root", - new XElement("Child", "child content") -); - -root.ReplaceAll( - from el in xmlTree1.Elements() - where((int)el >= 3 && (int)el <= 5) - select el -); -Console.WriteLine(root); -``` - -```vb -Dim xmlTree1 As XElement = _ - - 1 - 2 - 3 - 4 - 5 - 6 - - -Dim root As XElement = - child content - - -root.ReplaceAll( _ - From el In xmlTree1.Elements() _ - Where el.Value >= 3 And el.Value <= 5 _ - Select el _ -) - -Console.WriteLine(root) -``` - - This example produces the following output: - -```xml - - 3 - 4 - 5 - -``` - + and the events. + + + +## Examples + The following example passes the results of a LINQ query to this method, replacing the contents of an element with the query results. + +```csharp +XElement xmlTree1 = new XElement("Root", + new XElement("Child1", 1), + new XElement("Child2", 2), + new XElement("Child3", 3), + new XElement("Child4", 4), + new XElement("Child5", 5), + new XElement("Child6", 6) +); + +XElement root = new XElement("Root", + new XElement("Child", "child content") +); + +root.ReplaceAll( + from el in xmlTree1.Elements() + where((int)el >= 3 && (int)el <= 5) + select el +); +Console.WriteLine(root); +``` + +```vb +Dim xmlTree1 As XElement = _ + + 1 + 2 + 3 + 4 + 5 + 6 + + +Dim root As XElement = + child content + + +root.ReplaceAll( _ + From el In xmlTree1.Elements() _ + Where el.Value >= 3 And el.Value <= 5 _ + Select el _ +) + +Console.WriteLine(root) +``` + + This example produces the following output: + +```xml + + 3 + 4 + 5 + +``` + ]]> LINQ to XML overview @@ -7379,42 +7379,42 @@ Console.WriteLine(root) Replaces the attributes of this element with the specified content. - and the events. - - For details about the valid content that can be passed to this function, see [Valid Content of XElement and XDocument Objects](/dotnet/standard/linq/valid-content-xelement-xdocument-objects). - - - -## Examples - The following example creates an element with three attributes. It then uses this method to replace all of the attributes of the element with a single attribute. - -```csharp -XElement root = new XElement("Root", - new XAttribute("Att1", 1), - new XAttribute("Att2", 2), - new XAttribute("Att3", 3) -); -root.ReplaceAttributes( - new XAttribute("NewAtt1", 101) -); -Console.WriteLine(root); -``` - -```vb -Dim root As XElement = -root.ReplaceAttributes(New XAttribute("NewAtt1", 101)) -Console.WriteLine(root) -``` - - This example produces the following output: - -```xml - -``` - + and the events. + + For details about the valid content that can be passed to this function, see [Valid Content of XElement and XDocument Objects](/dotnet/standard/linq/valid-content-xelement-xdocument-objects). + + + +## Examples + The following example creates an element with three attributes. It then uses this method to replace all of the attributes of the element with a single attribute. + +```csharp +XElement root = new XElement("Root", + new XAttribute("Att1", 1), + new XAttribute("Att2", 2), + new XAttribute("Att3", 3) +); +root.ReplaceAttributes( + new XAttribute("NewAtt1", 101) +); +Console.WriteLine(root); +``` + +```vb +Dim root As XElement = +root.ReplaceAttributes(New XAttribute("NewAtt1", 101)) +Console.WriteLine(root) +``` + + This example produces the following output: + +```xml + +``` + ]]> LINQ to XML overview @@ -7469,44 +7469,44 @@ Console.WriteLine(root) The content that will replace the attributes of this element. Replaces the attributes of this element with the specified content. - and the events. - - - -## Examples - The following example creates an element with three attributes. It then uses this method to replace all of the attributes of the element with a single attribute. - -```csharp -XElement root = new XElement("Root", - new XAttribute("Att1", 1), - new XAttribute("Att2", 2), - new XAttribute("Att3", 3) -); -root.ReplaceAttributes( - new XAttribute("NewAtt1", 101) -); -Console.WriteLine(root); -``` - -```vb -Dim root As XElement = -root.ReplaceAttributes(New XAttribute("NewAtt1", 101)) -Console.WriteLine(root) -``` - - This example produces the following output: - -```xml - -``` - + and the events. + + + +## Examples + The following example creates an element with three attributes. It then uses this method to replace all of the attributes of the element with a single attribute. + +```csharp +XElement root = new XElement("Root", + new XAttribute("Att1", 1), + new XAttribute("Att2", 2), + new XAttribute("Att3", 3) +); +root.ReplaceAttributes( + new XAttribute("NewAtt1", 101) +); +Console.WriteLine(root); +``` + +```vb +Dim root As XElement = +root.ReplaceAttributes(New XAttribute("NewAtt1", 101)) +Console.WriteLine(root) +``` + + This example produces the following output: + +```xml + +``` + ]]> LINQ to XML overview @@ -7572,49 +7572,49 @@ Console.WriteLine(root) A parameter list of content objects. Replaces the attributes of this element with the specified content. - and the events. - - - -## Examples - The following example creates an element with three attributes. It then replaces the attributes with other attributes. - -```csharp -XElement root = new XElement("Root", - new XAttribute("Att1", 1), - new XAttribute("Att2", 2), - new XAttribute("Att3", 3) -); -root.ReplaceAttributes( - new XAttribute("NewAtt1", 101), - new XAttribute("NewAtt2", 102), - new XAttribute("NewAtt3", 103) -); -Console.WriteLine(root); -``` - -```vb -Dim root As XElement = -root.ReplaceAttributes( _ -New XAttribute("NewAtt1", 101), _ -New XAttribute("NewAtt2", 102), _ -New XAttribute("NewAtt3", 103)) -Console.WriteLine(root) -``` - - This example produces the following output: - -```xml - -``` - + and the events. + + + +## Examples + The following example creates an element with three attributes. It then replaces the attributes with other attributes. + +```csharp +XElement root = new XElement("Root", + new XAttribute("Att1", 1), + new XAttribute("Att2", 2), + new XAttribute("Att3", 3) +); +root.ReplaceAttributes( + new XAttribute("NewAtt1", 101), + new XAttribute("NewAtt2", 102), + new XAttribute("NewAtt3", 103) +); +Console.WriteLine(root); +``` + +```vb +Dim root As XElement = +root.ReplaceAttributes( _ +New XAttribute("NewAtt1", 101), _ +New XAttribute("NewAtt2", 102), _ +New XAttribute("NewAtt3", 103)) +Console.WriteLine(root) +``` + + This example produces the following output: + +```xml + +``` + ]]> LINQ to XML overview @@ -7673,15 +7673,15 @@ Console.WriteLine(root) The stream to output this to. Outputs this to the specified . - that takes as a parameter. Use the option to save unindented XML. This will cause the writer to write all white spaces exactly as represented in the XML tree. - - Use the option if you want to remove duplicate namespace declarations. - + that takes as a parameter. Use the option to save unindented XML. This will cause the writer to write all white spaces exactly as represented in the XML tree. + + Use the option if you want to remove duplicate namespace declarations. + ]]> @@ -7728,43 +7728,43 @@ Console.WriteLine(root) A that the will be written to. Serialize this element to a . - that allows you to specify as a parameter. For more information, see [Preserve white space while loading or parsing XML](/dotnet/standard/linq/preserve-white-space-loading-parsing-xml) and [Preserve white space while serializing](/dotnet/standard/linq/preserve-white-space-serializing). - - - -## Examples - The following example creates an , saves the document to a , and then prints the string to the console. - -```csharp -XElement root = XElement.Parse(@" Text "); -using (StringWriter sw = new StringWriter()) { - root.Save(sw); - Console.WriteLine(sw.ToString()); -} -``` - -```vb -Dim root As XElement = Text -Using sw = New StringWriter() - root.Save(sw) - Console.WriteLine(sw.ToString()) -End Using -``` - - This example produces the following output: - -```xml - - - Text - -``` - + that allows you to specify as a parameter. For more information, see [Preserve white space while loading or parsing XML](/dotnet/standard/linq/preserve-white-space-loading-parsing-xml) and [Preserve white space while serializing](/dotnet/standard/linq/preserve-white-space-serializing). + + + +## Examples + The following example creates an , saves the document to a , and then prints the string to the console. + +```csharp +XElement root = XElement.Parse(@" Text "); +using (StringWriter sw = new StringWriter()) { + root.Save(sw); + Console.WriteLine(sw.ToString()); +} +``` + +```vb +Dim root As XElement = Text +Using sw = New StringWriter() + root.Save(sw) + Console.WriteLine(sw.ToString()) +End Using +``` + + This example produces the following output: + +```xml + + + Text + +``` + ]]> LINQ to XML overview @@ -7804,52 +7804,52 @@ End Using System.Void - + A that contains the name of the file. Serialize this element to a file. - that allows you to specify as a parameter. For more information, see [Preserve white space while loading or parsing XML](/dotnet/standard/linq/preserve-white-space-loading-parsing-xml) and [Preserve white space while serializing](/dotnet/standard/linq/preserve-white-space-serializing). - - - -## Examples - The following example creates an , saves the document to a file, and then prints the file to the console. - -```csharp -XElement root = new XElement("Root", - new XElement("Child", "child content") -); -root.Save("Root.xml"); -string str = File.ReadAllText("Root.xml"); -Console.WriteLine(str); -``` - -```vb -Dim root As XElement = _ - - child content - -root.Save("Root.xml") -Dim Str As String = File.ReadAllText("Root.xml") -Console.WriteLine(Str) -``` - - This example produces the following output: - -```xml - - - child content - -``` - + that allows you to specify as a parameter. For more information, see [Preserve white space while loading or parsing XML](/dotnet/standard/linq/preserve-white-space-loading-parsing-xml) and [Preserve white space while serializing](/dotnet/standard/linq/preserve-white-space-serializing). + + + +## Examples + The following example creates an , saves the document to a file, and then prints the file to the console. + +```csharp +XElement root = new XElement("Root", + new XElement("Child", "child content") +); +root.Save("Root.xml"); +string str = File.ReadAllText("Root.xml"); +Console.WriteLine(str); +``` + +```vb +Dim root As XElement = _ + + child content + +root.Save("Root.xml") +Dim Str As String = File.ReadAllText("Root.xml") +Console.WriteLine(Str) +``` + + This example produces the following output: + +```xml + + + child content + +``` + ]]> LINQ to XML overview @@ -7897,43 +7897,43 @@ Console.WriteLine(Str) A that the will be written to. Serialize this element to an . - to an . - -```csharp -StringBuilder sb = new StringBuilder(); -XmlWriterSettings xws = new XmlWriterSettings(); -xws.OmitXmlDeclaration = true; -using (XmlWriter xw = XmlWriter.Create(sb, xws)) { - XElement root = new XElement("Root", - new XElement("Child", "child content") - ); - root.Save(xw); -} -Console.WriteLine(sb.ToString()); -``` - -```vb -Dim sb As StringBuilder = New StringBuilder() -Dim xws As XmlWriterSettings = New XmlWriterSettings() -xws.OmitXmlDeclaration = True -Using xw = XmlWriter.Create(sb, xws) - Dim root As XElement = - child content - - root.Save(xw) -End Using -Console.WriteLine(sb.ToString()) -``` - - This example produces the following output: - -```xml -child content -``` - + to an . + +```csharp +StringBuilder sb = new StringBuilder(); +XmlWriterSettings xws = new XmlWriterSettings(); +xws.OmitXmlDeclaration = true; +using (XmlWriter xw = XmlWriter.Create(sb, xws)) { + XElement root = new XElement("Root", + new XElement("Child", "child content") + ); + root.Save(xw); +} +Console.WriteLine(sb.ToString()); +``` + +```vb +Dim sb As StringBuilder = New StringBuilder() +Dim xws As XmlWriterSettings = New XmlWriterSettings() +xws.OmitXmlDeclaration = True +Using xw = XmlWriter.Create(sb, xws) + Dim root As XElement = + child content + + root.Save(xw) +End Using +Console.WriteLine(sb.ToString()) +``` + + This example produces the following output: + +```xml +child content +``` + ]]> LINQ to XML overview @@ -7982,15 +7982,15 @@ Console.WriteLine(sb.ToString()) A object that specifies formatting behavior. Outputs this to the specified , optionally specifying formatting behavior. - . This option will remove all extraneous insignificant white space, and add appropriate insignificant white space so that the XML is properly indented. - - If you want to save unindented XML, specify the flag for `options`. This will cause the writer to write all white spaces exactly as represented in the XML tree. - - Use option if you want to remove duplicate namespace declarations. - + . This option will remove all extraneous insignificant white space, and add appropriate insignificant white space so that the XML is properly indented. + + If you want to save unindented XML, specify the flag for `options`. This will cause the writer to write all white spaces exactly as represented in the XML tree. + + Use option if you want to remove duplicate namespace declarations. + ]]> @@ -8039,65 +8039,65 @@ Console.WriteLine(sb.ToString()) A that specifies formatting behavior. Serialize this element to a , optionally disabling formatting. - flag for `options`. This will cause the writer to write all white space exactly as represented in the XML tree. - - If you want to save indented XML, do not specify the flag for `options`. This will remove all extraneous insignificant white space, and add appropriate insignificant white space so that the XML is properly indented. This is the default behavior, and the behavior of the overloads of the methods that do not take `options` as a parameter. - - For more information, see [Preserve white space while loading or parsing XML](/dotnet/standard/linq/preserve-white-space-loading-parsing-xml) and [Preserve white space while serializing](/dotnet/standard/linq/preserve-white-space-serializing). - - - -## Examples - The following example shows two uses of this method. The first use preserves white space. The second serializes the with formatting. Because the document has no white space in it as constructed, preserving white space outputs the XML without any indenting. - -```csharp -XElement root = XElement.Parse(@" Text "); - -using (StringWriter sw = new StringWriter()) -{ - root.Save(sw, SaveOptions.DisableFormatting); - Console.WriteLine(sw.ToString()); -} - -Console.WriteLine("====="); - -using (StringWriter sw = new StringWriter()) -{ - root.Save(sw, SaveOptions.None); - Console.WriteLine(sw.ToString()); -} -``` - -```vb -Dim root As XElement = Text - -Using sw = New StringWriter() - root.Save(sw, SaveOptions.DisableFormatting) - Console.WriteLine(sw.ToString()) -End Using - -Console.WriteLine("=====") - -Using sw = New StringWriter() - root.Save(sw, SaveOptions.None) - Console.WriteLine(sw.ToString()) -End Using -``` - - This example produces the following output: - -``` - Text -===== - - - Text - -``` - + flag for `options`. This will cause the writer to write all white space exactly as represented in the XML tree. + + If you want to save indented XML, do not specify the flag for `options`. This will remove all extraneous insignificant white space, and add appropriate insignificant white space so that the XML is properly indented. This is the default behavior, and the behavior of the overloads of the methods that do not take `options` as a parameter. + + For more information, see [Preserve white space while loading or parsing XML](/dotnet/standard/linq/preserve-white-space-loading-parsing-xml) and [Preserve white space while serializing](/dotnet/standard/linq/preserve-white-space-serializing). + + + +## Examples + The following example shows two uses of this method. The first use preserves white space. The second serializes the with formatting. Because the document has no white space in it as constructed, preserving white space outputs the XML without any indenting. + +```csharp +XElement root = XElement.Parse(@" Text "); + +using (StringWriter sw = new StringWriter()) +{ + root.Save(sw, SaveOptions.DisableFormatting); + Console.WriteLine(sw.ToString()); +} + +Console.WriteLine("====="); + +using (StringWriter sw = new StringWriter()) +{ + root.Save(sw, SaveOptions.None); + Console.WriteLine(sw.ToString()); +} +``` + +```vb +Dim root As XElement = Text + +Using sw = New StringWriter() + root.Save(sw, SaveOptions.DisableFormatting) + Console.WriteLine(sw.ToString()) +End Using + +Console.WriteLine("=====") + +Using sw = New StringWriter() + root.Save(sw, SaveOptions.None) + Console.WriteLine(sw.ToString()) +End Using +``` + + This example produces the following output: + +``` + Text +===== + + + Text + +``` + ]]> LINQ to XML overview @@ -8137,69 +8137,69 @@ End Using System.Void - - + + A that contains the name of the file. A that specifies formatting behavior. Serialize this element to a file, optionally disabling formatting. - flag for `options`. This will cause the writer to write all white space exactly as represented in the XML tree. - - If you want to save indented XML, do not specify the flag for `options`. This will remove all extraneous insignificant white space, and add appropriate insignificant white space so that the XML is properly indented. This is the default behavior, and the behavior of the overloads of the methods that do not take `options` as a parameter. - - For more information, see [Preserve white space while loading or parsing XML](/dotnet/standard/linq/preserve-white-space-loading-parsing-xml) and [Preserve white space while serializing](/dotnet/standard/linq/preserve-white-space-serializing). - - - -## Examples - The following example shows two uses of this method. The first use preserves white space. The second one serializes the with formatting. - -```csharp -string str; -XElement root = XElement.Parse(@" Text "); - -root.Save("Root.xml", SaveOptions.DisableFormatting); -str = File.ReadAllText("Root.xml"); -Console.WriteLine(str); - -Console.WriteLine("====="); - -root.Save("Root.xml", SaveOptions.None); -str = File.ReadAllText("Root.xml"); -Console.WriteLine(str); -``` - -```vb -Dim str As String -Dim root As XElement = Text - -root.Save("Root.xml", SaveOptions.DisableFormatting) -str = File.ReadAllText("Root.xml") -Console.WriteLine(str) - -Console.WriteLine("=====") - -root.Save("Root.xml", SaveOptions.None) -str = File.ReadAllText("Root.xml") -Console.WriteLine(str) -``` - - This example produces the following output: - -``` - Text -===== - - - Text - -``` - + flag for `options`. This will cause the writer to write all white space exactly as represented in the XML tree. + + If you want to save indented XML, do not specify the flag for `options`. This will remove all extraneous insignificant white space, and add appropriate insignificant white space so that the XML is properly indented. This is the default behavior, and the behavior of the overloads of the methods that do not take `options` as a parameter. + + For more information, see [Preserve white space while loading or parsing XML](/dotnet/standard/linq/preserve-white-space-loading-parsing-xml) and [Preserve white space while serializing](/dotnet/standard/linq/preserve-white-space-serializing). + + + +## Examples + The following example shows two uses of this method. The first use preserves white space. The second one serializes the with formatting. + +```csharp +string str; +XElement root = XElement.Parse(@" Text "); + +root.Save("Root.xml", SaveOptions.DisableFormatting); +str = File.ReadAllText("Root.xml"); +Console.WriteLine(str); + +Console.WriteLine("====="); + +root.Save("Root.xml", SaveOptions.None); +str = File.ReadAllText("Root.xml"); +Console.WriteLine(str); +``` + +```vb +Dim str As String +Dim root As XElement = Text + +root.Save("Root.xml", SaveOptions.DisableFormatting) +str = File.ReadAllText("Root.xml") +Console.WriteLine(str) + +Console.WriteLine("=====") + +root.Save("Root.xml", SaveOptions.None) +str = File.ReadAllText("Root.xml") +Console.WriteLine(str) +``` + + This example produces the following output: + +``` + Text +===== + + + Text + +``` + ]]> LINQ to XML overview @@ -8387,68 +8387,68 @@ Console.WriteLine(str) The value to assign to the attribute. The attribute is removed if the value is . Otherwise, the value is converted to its string representation and assigned to the property of the attribute. Sets the value of an attribute, adds an attribute, or removes an attribute. - and the events. - - The value is assigned to the attribute with the specified name. If no attribute with the specified name exists, a new attribute is added. If the value is `null`, the attribute with the specified name, if any, is deleted. - - For more information, see [Maintain name-value pairs](/dotnet/standard/linq/maintain-name-value-pairs). - - - -## Examples - The following example creates an element with an attribute. It then uses this method to replace the content of the attribute. - -```csharp -// Create an element with no content. -XElement root = new XElement("Root"); - -// Add some name/value pairs. -root.SetAttributeValue("Att1", 1); -root.SetAttributeValue("Att2", 2); -root.SetAttributeValue("Att3", 3); -Console.WriteLine(root); - -// Modify one of the name/value pairs. -root.SetAttributeValue("Att2", 22); -Console.WriteLine(root); - -// Remove one of the name/value pairs. -root.SetAttributeValue("Att3", null); -Console.WriteLine(root); -``` - -```vb -' Create an element with no content. -Dim root As XElement = - -' Add some name/value pairs. -root.SetAttributeValue("Att1", 1) -root.SetAttributeValue("Att2", 2) -root.SetAttributeValue("Att3", 3) -Console.WriteLine(root) - -' Modify one of the name/value pairs. -root.SetAttributeValue("Att2", 22) -Console.WriteLine(root) - -' Remove one of the name/value pairs. -root.SetAttributeValue("Att3", Nothing) -Console.WriteLine(root) -``` - - This example produces the following output: - -``` - - - -``` - + and the events. + + The value is assigned to the attribute with the specified name. If no attribute with the specified name exists, a new attribute is added. If the value is `null`, the attribute with the specified name, if any, is deleted. + + For more information, see [Maintain name-value pairs](/dotnet/standard/linq/maintain-name-value-pairs). + + + +## Examples + The following example creates an element with an attribute. It then uses this method to replace the content of the attribute. + +```csharp +// Create an element with no content. +XElement root = new XElement("Root"); + +// Add some name/value pairs. +root.SetAttributeValue("Att1", 1); +root.SetAttributeValue("Att2", 2); +root.SetAttributeValue("Att3", 3); +Console.WriteLine(root); + +// Modify one of the name/value pairs. +root.SetAttributeValue("Att2", 22); +Console.WriteLine(root); + +// Remove one of the name/value pairs. +root.SetAttributeValue("Att3", null); +Console.WriteLine(root); +``` + +```vb +' Create an element with no content. +Dim root As XElement = + +' Add some name/value pairs. +root.SetAttributeValue("Att1", 1) +root.SetAttributeValue("Att2", 2) +root.SetAttributeValue("Att3", 3) +Console.WriteLine(root) + +' Modify one of the name/value pairs. +root.SetAttributeValue("Att2", 22) +Console.WriteLine(root) + +' Remove one of the name/value pairs. +root.SetAttributeValue("Att3", Nothing) +Console.WriteLine(root) +``` + + This example produces the following output: + +``` + + + +``` + ]]> The is an instance of . @@ -8511,81 +8511,81 @@ Console.WriteLine(root) The value to assign to the child element. The child element is removed if the value is . Otherwise, the value is converted to its string representation and assigned to the property of the child element. Sets the value of a child element, adds a child element, or removes a child element. - is passed as `value`. - - For more information, see [Maintain name-value pairs](/dotnet/standard/linq/maintain-name-value-pairs). - - - -## Examples - The following example creates an element with a child element. It then uses this method to set the value of the child element. - -```csharp -// Create an element with no content -XElement root = new XElement("Root"); - -// Add some name/value pairs. -root.SetElementValue("Ele1", 1); -root.SetElementValue("Ele2", 2); -root.SetElementValue("Ele3", 3); -Console.WriteLine(root); - -// Modify one of the name/value pairs. -root.SetElementValue("Ele2", 22); -Console.WriteLine(root); - -// Remove one of the name/value pairs. -root.SetElementValue("Ele3", null); -Console.WriteLine(root); -``` - -```vb -' Create an element with no content. -Dim root As XElement = - -' Add some name/value pairs. -root.SetElementValue("Ele1", 1) -root.SetElementValue("Ele2", 2) -root.SetElementValue("Ele3", 3) -Console.WriteLine(root) - -' Modify one of the name/value pairs. -root.SetElementValue("Ele2", 22) -Console.WriteLine(root) - -' Remove one of the name/value pairs. -root.SetElementValue("Ele3", Nothing) -Console.WriteLine(root) -``` - - This example produces the following output: - -``` - - 1 - 2 - 3 - - - 1 - 22 - 3 - - - 1 - 22 - -``` - + is passed as `value`. + + For more information, see [Maintain name-value pairs](/dotnet/standard/linq/maintain-name-value-pairs). + + + +## Examples + The following example creates an element with a child element. It then uses this method to set the value of the child element. + +```csharp +// Create an element with no content +XElement root = new XElement("Root"); + +// Add some name/value pairs. +root.SetElementValue("Ele1", 1); +root.SetElementValue("Ele2", 2); +root.SetElementValue("Ele3", 3); +Console.WriteLine(root); + +// Modify one of the name/value pairs. +root.SetElementValue("Ele2", 22); +Console.WriteLine(root); + +// Remove one of the name/value pairs. +root.SetElementValue("Ele3", null); +Console.WriteLine(root); +``` + +```vb +' Create an element with no content. +Dim root As XElement = + +' Add some name/value pairs. +root.SetElementValue("Ele1", 1) +root.SetElementValue("Ele2", 2) +root.SetElementValue("Ele3", 3) +Console.WriteLine(root) + +' Modify one of the name/value pairs. +root.SetElementValue("Ele2", 22) +Console.WriteLine(root) + +' Remove one of the name/value pairs. +root.SetElementValue("Ele3", Nothing) +Console.WriteLine(root) +``` + + This example produces the following output: + +``` + + 1 + 2 + 3 + + + 1 + 22 + 3 + + + 1 + 22 + +``` + ]]> The is an instance of . @@ -8638,42 +8638,42 @@ Console.WriteLine(root) The value to assign to this element. The value is converted to its string representation and assigned to the property. Sets the value of this element. - and the events. - - It is invalid to pass an instance of a class that derives from , such as . - - - -## Examples - The following example creates an element that contains a child element. It then sets the value of the element using this method. - -```csharp -XElement root = new XElement("Root", - new XElement("Child", "child content") -); -root.SetValue("new content"); -Console.WriteLine(root); -``` - -```vb -Dim root As XElement = _ - - child content - - -root.SetValue("new content") -Console.WriteLine(root) -``` - - This example produces the following output: - -```xml -new content -``` - + and the events. + + It is invalid to pass an instance of a class that derives from , such as . + + + +## Examples + The following example creates an element that contains a child element. It then sets the value of the element using this method. + +```csharp +XElement root = new XElement("Root", + new XElement("Child", "child content") +); +root.SetValue("new content"); +Console.WriteLine(root); +``` + +```vb +Dim root As XElement = _ + + child content + + +root.SetValue("new content") +Console.WriteLine(root) +``` + + This example produces the following output: + +```xml +new content +``` + ]]> The is . @@ -8726,13 +8726,13 @@ Console.WriteLine(root) Gets an XML schema definition that describes the XML representation of this object. An that describes the XML representation of the object that is produced by the method and consumed by the method. - interface. - - This method is used internally for serializing object graphs that contain LINQ to XML objects. For an example of serializing an object graph that contains LINQ to XML objects, see [Serialize object graphs that contain XElement objects](/dotnet/standard/linq/serialize-xmlserializer). - + interface. + + This method is used internally for serializing object graphs that contain LINQ to XML objects. For an example of serializing an object graph that contains LINQ to XML objects, see [Serialize object graphs that contain XElement objects](/dotnet/standard/linq/serialize-xmlserializer). + ]]> @@ -8781,13 +8781,13 @@ Console.WriteLine(root) The from which the object is deserialized. Generates an object from its XML representation. - interface. - - This method is used internally for serializing object graphs that contain LINQ to XML objects. For an example of serializing an object graph that contains LINQ to XML objects, see [Serialize object graphs that contain XElement objects](/dotnet/standard/linq/serialize-xmlserializer). - + interface. + + This method is used internally for serializing object graphs that contain LINQ to XML objects. For an example of serializing an object graph that contains LINQ to XML objects, see [Serialize object graphs that contain XElement objects](/dotnet/standard/linq/serialize-xmlserializer). + ]]> @@ -8836,11 +8836,11 @@ Console.WriteLine(root) The to which this object is serialized. Converts an object into its XML representation. - @@ -8884,36 +8884,36 @@ Console.WriteLine(root) Gets or sets the concatenated text contents of this element. A that contains all of the text content of this element. If there are multiple text nodes, they will be concatenated. - and the events. - - If you want to get the value of an element but you are not sure that it exists, it is more convenient to use the explicit conversion operators, and assign the element to a nullable type such as `string` or of . If the element does not exist, the nullable type is set to `null`. By contrast, if you want to use this property, you must make sure that the method does not return `null` before you access this property. - - - -## Examples - The following example uses this property to retrieve the text of an element with mixed content. - -```csharp -XElement el = XElement.Parse("This is mixed content"); -Console.WriteLine("{0}", el.Value); -``` - -```vb -Dim el As XElement = This is mixed content -Console.WriteLine("{0}", el.Value) -``` - - This example produces the following output: - -``` -This is mixed content -``` - + and the events. + + If you want to get the value of an element but you are not sure that it exists, it is more convenient to use the explicit conversion operators, and assign the element to a nullable type such as `string` or of . If the element does not exist, the nullable type is set to `null`. By contrast, if you want to use this property, you must make sure that the method does not return `null` before you access this property. + + + +## Examples + The following example uses this property to retrieve the text of an element with mixed content. + +```csharp +XElement el = XElement.Parse("This is mixed content"); +Console.WriteLine("{0}", el.Value); +``` + +```vb +Dim el As XElement = This is mixed content +Console.WriteLine("{0}", el.Value) +``` + + This example produces the following output: + +``` +This is mixed content +``` + ]]> LINQ to XML overview @@ -8961,73 +8961,73 @@ This is mixed content An into which this method will write. Write this element to an . - to an . Note that the example did not write an XML declaration. - -```csharp -StringBuilder sb = new StringBuilder(); -XmlWriterSettings xws = new XmlWriterSettings(); -xws.OmitXmlDeclaration = true; -xws.Indent = true; - -using (XmlWriter xw = XmlWriter.Create(sb, xws)) { - xw.WriteStartElement("Root"); - - XElement child1 = new XElement("Child", - new XElement("GrandChild", "some content") - ); - child1.WriteTo(xw); - - XElement child2 = new XElement("AnotherChild", - new XElement("GrandChild", "different content") - ); - child2.WriteTo(xw); - - xw.WriteEndElement(); -} - -Console.WriteLine(sb.ToString()); -``` - -```vb -Dim sb As StringBuilder = New StringBuilder() -Dim xws As XmlWriterSettings = New XmlWriterSettings() -xws.OmitXmlDeclaration = True -xws.Indent = True - -Using xw = XmlWriter.Create(sb, xws) - xw.WriteStartElement("Root") - Dim child1 As XElement = _ - - some content - - child1.WriteTo(xw) - Dim child2 As XElement = _ - - different content - - child2.WriteTo(xw) - xw.WriteEndElement() -End Using - -Console.WriteLine(sb.ToString()) -``` - - This example produces the following output: - -```xml - - - some content - - - different content - - -``` - + to an . Note that the example did not write an XML declaration. + +```csharp +StringBuilder sb = new StringBuilder(); +XmlWriterSettings xws = new XmlWriterSettings(); +xws.OmitXmlDeclaration = true; +xws.Indent = true; + +using (XmlWriter xw = XmlWriter.Create(sb, xws)) { + xw.WriteStartElement("Root"); + + XElement child1 = new XElement("Child", + new XElement("GrandChild", "some content") + ); + child1.WriteTo(xw); + + XElement child2 = new XElement("AnotherChild", + new XElement("GrandChild", "different content") + ); + child2.WriteTo(xw); + + xw.WriteEndElement(); +} + +Console.WriteLine(sb.ToString()); +``` + +```vb +Dim sb As StringBuilder = New StringBuilder() +Dim xws As XmlWriterSettings = New XmlWriterSettings() +xws.OmitXmlDeclaration = True +xws.Indent = True + +Using xw = XmlWriter.Create(sb, xws) + xw.WriteStartElement("Root") + Dim child1 As XElement = _ + + some content + + child1.WriteTo(xw) + Dim child2 As XElement = _ + + different content + + child2.WriteTo(xw) + xw.WriteEndElement() +End Using + +Console.WriteLine(sb.ToString()) +``` + + This example produces the following output: + +```xml + + + some content + + + different content + + +``` + ]]> LINQ to XML overview diff --git a/xml/System.Xml.Linq/XName.xml b/xml/System.Xml.Linq/XName.xml index 7dc890c97a5..04b095a1b31 100644 --- a/xml/System.Xml.Linq/XName.xml +++ b/xml/System.Xml.Linq/XName.xml @@ -1058,8 +1058,8 @@ False System.Void - - + + The to populate with data. diff --git a/xml/System.Xml.Linq/XStreamingElement.xml b/xml/System.Xml.Linq/XStreamingElement.xml index 6728220fcea..9d6d8f0e583 100644 --- a/xml/System.Xml.Linq/XStreamingElement.xml +++ b/xml/System.Xml.Linq/XStreamingElement.xml @@ -54,431 +54,431 @@ Represents elements in an XML tree that supports deferred streaming output. - . However, there is a fundamental difference. When you use a LINQ query to specify content when creating an XML tree using , the query variable is iterated at the time of construction of the XML tree, and the results of the query are added to the XML tree. In contrast, when you create an XML tree using , a reference to the query variable is stored in the XML tree without being iterated. Queries are iterated only upon serialization. This allows you to create larger XML trees while maintaining a smaller memory footprint. - - If you are streaming from an input source, such as a text file, then you can read a very large text file, and generate a very large XML document while maintaining a small memory footprint. - - Another scenario is that you have a large XML tree that has been loaded into memory, and you want to create a transformed version of the document. If you create a new document using , then you will have two large XML trees in memory upon completion of the transformation. However, if you create the new XML tree using , then your working set will be effectively cut in half. - - Note that when debugging a program that uses , displaying the value of an object causes its method to be called. This causes the XML to be serialized. If the semantics of your streaming element query are such that the streaming element can only be streamed once, this may cause undesirable behavior in your debugging experience. - - - -## Examples - The following example first creates a source XML tree. It then creates a transform of the source XML tree using . This transform creates a new tree in memory. It then creates a transform of the source XML tree using . This transform doesn't execute the query until the transformed tree is serialized to the console. Its memory usage is less. - -```csharp -XElement srcTree = new XElement("Root", - new XElement("Child", 1), - new XElement("Child", 2), - new XElement("Child", 3), - new XElement("Child", 4), - new XElement("Child", 5) - ); - -XElement dstTree1 = new XElement("NewRoot", - from el in srcTree.Elements() - where (int)el >= 3 - select new XElement("DifferentChild", (int)el) - ); - -XStreamingElement dstTree2 = new XStreamingElement("NewRoot", - from el in srcTree.Elements() - where (int)el >= 3 - select new XElement("DifferentChild", (int)el) - ); - -Console.WriteLine(dstTree1); -Console.WriteLine("------"); -Console.WriteLine(dstTree2); -``` - -```vb -Dim srcTree As XElement = _ - - 1 - 2 - 3 - 4 - 5 - - -Dim dstTree1 As XElement = _ - - <%= From el In srcTree.Elements _ - Where (el.Value >= 3) _ - Select <%= el.Value %> %> - - -Dim dstTree2 As XStreamingElement = New XStreamingElement("NewRoot", _ - From el In srcTree.Elements _ - Where el.Value >= 3 _ - Select <%= el.Value %> _ - ) - -Console.WriteLine(dstTree1) -Console.WriteLine("------") -Console.WriteLine(dstTree2) -``` - - This example produces the following output: - -``` - - 3 - 4 - 5 - ------- - - 3 - 4 - 5 - -``` - - One approach to processing a text file is to write an extension method that streams the text file a line at a time using the `yield return` construct. You then can write a LINQ query that processes the text file in a lazy deferred fashion. If you then use the to stream output, you then can create a transform from the text file to XML that uses a minimal amount of memory, regardless of the size of the source text file. - - The following text file, People.txt, is the source for this example. - -``` -#This is a comment -1,Tai,Yee,Writer -2,Nikolay,Grachev,Programmer -3,David,Wright,Inventor -``` - - The following code contains an extension method that streams the lines of the text file in a deferred fashion. - -```csharp -public static class StreamReaderSequence -{ - public static IEnumerable Lines(this StreamReader source) - { - String line; - - if (source == null) - throw new ArgumentNullException("source"); - while ((line = source.ReadLine()) != null) - { - yield return line; - } - } -} - -class Program -{ - static void Main(string[] args) - { - StreamReader sr = new StreamReader("People.txt"); - XStreamingElement xmlTree = new XStreamingElement("Root", - from line in sr.Lines() - let items = line.Split(',') - where !line.StartsWith("#") - select new XElement("Person", - new XAttribute("ID", items[0]), - new XElement("First", items[1]), - new XElement("Last", items[2]), - new XElement("Occupation", items[3]) - ) - ); - Console.WriteLine(xmlTree); - sr.Close(); - } -} -``` - -```vb -Module StreamReaderSequence - - - Public Iterator Function Lines(source As IO.StreamReader) As IEnumerable(Of String) - If source Is Nothing Then Throw New ArgumentNullException("source") - Dim line As String = source.ReadLine() - While (line <> Nothing) - Yield line - line = source.ReadLine() - End While - End Function - -End Module - -Module Module1 - Sub Main() - Dim sr As New IO.StreamReader("People.txt") - Dim xmlTree As New XStreamingElement("Root", - From line In sr.Lines() - Let items = line.Split(","c) - Where Not line.StartsWith("#") - Select > - <%= items(1) %> - <%= items(2) %> - <%= items(3) %> - ) - Console.WriteLine(xmlTree) - sr.Close() - End Sub -End Module -``` - - This example produces the following output: - -```xml - - - Tai - Yee - Writer - - - Nikolay - Grachev - Programmer - - - David - Wright - Inventor - - -``` - - Sometimes you have to transform large XML files, and write your application so that the memory footprint of the application is predictable. If you try to populate an XML tree with a very large XML file, your memory usage will be proportional to the size of the file (that is, excessive). Therefore, you should use a streaming technique instead. - - Certain standard query operators, such as , iterate their source, collect all of the data, sort it, and then finally yield the first item in the sequence. Note that if you use a query operator that materializes its source before yielding the first item, you will not retain a small memory footprint for your application. - - Even if you use the technique described in , if you try to assemble an XML tree that contains the transformed document, memory usage may be too great. - - The following example builds on the example in [How to stream XML fragments with access to header information](/dotnet/standard/linq/stream-xml-fragments-access-header-information). - - This example uses the deferred execution capabilities of to stream the output. - - Note that the custom axis (`StreamCustomerItem`) is specifically written so that it expects a document that has `Customer`, `Name`, and `Item` elements, and that those elements will be arranged as in the following Source.xml document. A more robust implementation, however, would either validate the source document with an XSD, or would be prepared to parse an invalid document. - - The following is the source document, Source.xml: - -```xml - - - - A. Datum Corporation - - 0001 - - - 0002 - - - 0003 - - - 0004 - - - - Fabrikam, Inc. - - 0005 - - - 0006 - - - 0007 - - - 0008 - - - - Southridge Video - - 0009 - - - 0010 - - - -``` - - The following code contains a method that uses an to stream the source XML. It uses to stream the new XML. - -```csharp -static IEnumerable StreamCustomerItem(string uri) -{ - using (XmlReader reader = XmlReader.Create(uri)) - { - XElement name = null; - XElement item = null; - - reader.MoveToContent(); - - // Parse the file, save header information when encountered, and yield the - // Item XElement objects as they are created. - - // loop through Customer elements - while (reader.Read()) - { - if (reader.NodeType == XmlNodeType.Element - && reader.Name == "Customer") - { - // move to Name element - while (reader.Read()) - { - if (reader.NodeType == XmlNodeType.Element && - reader.Name == "Name") - { - name = XElement.ReadFrom(reader) as XElement; - break; - } - } - - // loop through Item elements - while (reader.Read()) - { - if (reader.NodeType == XmlNodeType.EndElement) - break; - if (reader.NodeType == XmlNodeType.Element - && reader.Name == "Item") - { - item = XElement.ReadFrom(reader) as XElement; - if (item != null) - { - XElement tempRoot = new XElement("Root", - new XElement(name) - ); - tempRoot.Add(item); - yield return item; - } - } - } - } - } - } -} - -static void Main(string[] args) -{ - XStreamingElement root = new XStreamingElement("Root", - from el in StreamCustomerItem("Source.xml") - select new XElement("Item", - new XElement("Customer", (string)el.Parent.Element("Name")), - new XElement(el.Element("Key")) - ) - ); - root.Save("Test.xml"); - Console.WriteLine(File.ReadAllText("Test.xml")); -} -``` - -```vb -Iterator Function StreamCustomerItem(uri As String) As IEnumerable(Of XElement) - - Dim name As XElement = Nothing - Dim item As XElement = Nothing - - Dim reader As XmlReader = XmlReader.Create(uri) - reader.MoveToContent() - - ' Parse the file, save header information when encountered, and yield the - ' Item XElement objects as they are created. - - ' Loop through Customer elements. - While (reader.Read()) - If (reader.NodeType = XmlNodeType.Element And reader.Name = "Customer") Then - While (reader.Read()) - ' Move to Name element - If (reader.NodeType = XmlNodeType.Element And reader.Name = "Name") Then - name = CType(XElement.ReadFrom(reader), XElement) - Exit While - End If - End While - - ' Loop through Item elements - While (reader.Read()) - If (reader.NodeType = XmlNodeType.EndElement) Then - Exit While - End If - - If (reader.NodeType = XmlNodeType.Element And reader.Name = "Item") Then - item = CType(XElement.ReadFrom(reader), XElement) - If (Not (item Is Nothing)) Then - Dim tempRoot = New XElement("Root", - New XElement(name) - ) - tempRoot.Add(item) - Yield item - End If - End If - End While - End If - End While - reader.Close() -End Function - -Sub Main() - Dim root As New XStreamingElement("Root", - From el In StreamCustomerItem("c:\trash\Source.xml") - Select New XElement("Item", - New XElement("Customer", CStr(el.Parent.Element("Name"))), - New XElement(el.Element("Key")))) - root.Save("c:\trash\Test.xml") - Console.WriteLine(System.IO.File.ReadAllText("c:\trash\Test.xml")) -End Sub -``` - - This example produces the following output: - -```xml - - - - A. Datum Corporation - 0001 - - - A. Datum Corporation - 0002 - - - A. Datum Corporation - 0003 - - - A. Datum Corporation - 0004 - - - Fabrikam, Inc. - 0005 - - - Fabrikam, Inc. - 0006 - - - Fabrikam, Inc. - 0007 - - - Fabrikam, Inc. - 0008 - - - Southridge Video - 0009 - - - Southridge Video - 0010 - - -``` - + . However, there is a fundamental difference. When you use a LINQ query to specify content when creating an XML tree using , the query variable is iterated at the time of construction of the XML tree, and the results of the query are added to the XML tree. In contrast, when you create an XML tree using , a reference to the query variable is stored in the XML tree without being iterated. Queries are iterated only upon serialization. This allows you to create larger XML trees while maintaining a smaller memory footprint. + + If you are streaming from an input source, such as a text file, then you can read a very large text file, and generate a very large XML document while maintaining a small memory footprint. + + Another scenario is that you have a large XML tree that has been loaded into memory, and you want to create a transformed version of the document. If you create a new document using , then you will have two large XML trees in memory upon completion of the transformation. However, if you create the new XML tree using , then your working set will be effectively cut in half. + + Note that when debugging a program that uses , displaying the value of an object causes its method to be called. This causes the XML to be serialized. If the semantics of your streaming element query are such that the streaming element can only be streamed once, this may cause undesirable behavior in your debugging experience. + + + +## Examples + The following example first creates a source XML tree. It then creates a transform of the source XML tree using . This transform creates a new tree in memory. It then creates a transform of the source XML tree using . This transform doesn't execute the query until the transformed tree is serialized to the console. Its memory usage is less. + +```csharp +XElement srcTree = new XElement("Root", + new XElement("Child", 1), + new XElement("Child", 2), + new XElement("Child", 3), + new XElement("Child", 4), + new XElement("Child", 5) + ); + +XElement dstTree1 = new XElement("NewRoot", + from el in srcTree.Elements() + where (int)el >= 3 + select new XElement("DifferentChild", (int)el) + ); + +XStreamingElement dstTree2 = new XStreamingElement("NewRoot", + from el in srcTree.Elements() + where (int)el >= 3 + select new XElement("DifferentChild", (int)el) + ); + +Console.WriteLine(dstTree1); +Console.WriteLine("------"); +Console.WriteLine(dstTree2); +``` + +```vb +Dim srcTree As XElement = _ + + 1 + 2 + 3 + 4 + 5 + + +Dim dstTree1 As XElement = _ + + <%= From el In srcTree.Elements _ + Where (el.Value >= 3) _ + Select <%= el.Value %> %> + + +Dim dstTree2 As XStreamingElement = New XStreamingElement("NewRoot", _ + From el In srcTree.Elements _ + Where el.Value >= 3 _ + Select <%= el.Value %> _ + ) + +Console.WriteLine(dstTree1) +Console.WriteLine("------") +Console.WriteLine(dstTree2) +``` + + This example produces the following output: + +``` + + 3 + 4 + 5 + +------ + + 3 + 4 + 5 + +``` + + One approach to processing a text file is to write an extension method that streams the text file a line at a time using the `yield return` construct. You then can write a LINQ query that processes the text file in a lazy deferred fashion. If you then use the to stream output, you then can create a transform from the text file to XML that uses a minimal amount of memory, regardless of the size of the source text file. + + The following text file, People.txt, is the source for this example. + +``` +#This is a comment +1,Tai,Yee,Writer +2,Nikolay,Grachev,Programmer +3,David,Wright,Inventor +``` + + The following code contains an extension method that streams the lines of the text file in a deferred fashion. + +```csharp +public static class StreamReaderSequence +{ + public static IEnumerable Lines(this StreamReader source) + { + String line; + + if (source == null) + throw new ArgumentNullException("source"); + while ((line = source.ReadLine()) != null) + { + yield return line; + } + } +} + +class Program +{ + static void Main(string[] args) + { + StreamReader sr = new StreamReader("People.txt"); + XStreamingElement xmlTree = new XStreamingElement("Root", + from line in sr.Lines() + let items = line.Split(',') + where !line.StartsWith("#") + select new XElement("Person", + new XAttribute("ID", items[0]), + new XElement("First", items[1]), + new XElement("Last", items[2]), + new XElement("Occupation", items[3]) + ) + ); + Console.WriteLine(xmlTree); + sr.Close(); + } +} +``` + +```vb +Module StreamReaderSequence + + + Public Iterator Function Lines(source As IO.StreamReader) As IEnumerable(Of String) + If source Is Nothing Then Throw New ArgumentNullException("source") + Dim line As String = source.ReadLine() + While (line <> Nothing) + Yield line + line = source.ReadLine() + End While + End Function + +End Module + +Module Module1 + Sub Main() + Dim sr As New IO.StreamReader("People.txt") + Dim xmlTree As New XStreamingElement("Root", + From line In sr.Lines() + Let items = line.Split(","c) + Where Not line.StartsWith("#") + Select > + <%= items(1) %> + <%= items(2) %> + <%= items(3) %> + ) + Console.WriteLine(xmlTree) + sr.Close() + End Sub +End Module +``` + + This example produces the following output: + +```xml + + + Tai + Yee + Writer + + + Nikolay + Grachev + Programmer + + + David + Wright + Inventor + + +``` + + Sometimes you have to transform large XML files, and write your application so that the memory footprint of the application is predictable. If you try to populate an XML tree with a very large XML file, your memory usage will be proportional to the size of the file (that is, excessive). Therefore, you should use a streaming technique instead. + + Certain standard query operators, such as , iterate their source, collect all of the data, sort it, and then finally yield the first item in the sequence. Note that if you use a query operator that materializes its source before yielding the first item, you will not retain a small memory footprint for your application. + + Even if you use the technique described in , if you try to assemble an XML tree that contains the transformed document, memory usage may be too great. + + The following example builds on the example in [How to stream XML fragments with access to header information](/dotnet/standard/linq/stream-xml-fragments-access-header-information). + + This example uses the deferred execution capabilities of to stream the output. + + Note that the custom axis (`StreamCustomerItem`) is specifically written so that it expects a document that has `Customer`, `Name`, and `Item` elements, and that those elements will be arranged as in the following Source.xml document. A more robust implementation, however, would either validate the source document with an XSD, or would be prepared to parse an invalid document. + + The following is the source document, Source.xml: + +```xml + + + + A. Datum Corporation + + 0001 + + + 0002 + + + 0003 + + + 0004 + + + + Fabrikam, Inc. + + 0005 + + + 0006 + + + 0007 + + + 0008 + + + + Southridge Video + + 0009 + + + 0010 + + + +``` + + The following code contains a method that uses an to stream the source XML. It uses to stream the new XML. + +```csharp +static IEnumerable StreamCustomerItem(string uri) +{ + using (XmlReader reader = XmlReader.Create(uri)) + { + XElement name = null; + XElement item = null; + + reader.MoveToContent(); + + // Parse the file, save header information when encountered, and yield the + // Item XElement objects as they are created. + + // loop through Customer elements + while (reader.Read()) + { + if (reader.NodeType == XmlNodeType.Element + && reader.Name == "Customer") + { + // move to Name element + while (reader.Read()) + { + if (reader.NodeType == XmlNodeType.Element && + reader.Name == "Name") + { + name = XElement.ReadFrom(reader) as XElement; + break; + } + } + + // loop through Item elements + while (reader.Read()) + { + if (reader.NodeType == XmlNodeType.EndElement) + break; + if (reader.NodeType == XmlNodeType.Element + && reader.Name == "Item") + { + item = XElement.ReadFrom(reader) as XElement; + if (item != null) + { + XElement tempRoot = new XElement("Root", + new XElement(name) + ); + tempRoot.Add(item); + yield return item; + } + } + } + } + } + } +} + +static void Main(string[] args) +{ + XStreamingElement root = new XStreamingElement("Root", + from el in StreamCustomerItem("Source.xml") + select new XElement("Item", + new XElement("Customer", (string)el.Parent.Element("Name")), + new XElement(el.Element("Key")) + ) + ); + root.Save("Test.xml"); + Console.WriteLine(File.ReadAllText("Test.xml")); +} +``` + +```vb +Iterator Function StreamCustomerItem(uri As String) As IEnumerable(Of XElement) + + Dim name As XElement = Nothing + Dim item As XElement = Nothing + + Dim reader As XmlReader = XmlReader.Create(uri) + reader.MoveToContent() + + ' Parse the file, save header information when encountered, and yield the + ' Item XElement objects as they are created. + + ' Loop through Customer elements. + While (reader.Read()) + If (reader.NodeType = XmlNodeType.Element And reader.Name = "Customer") Then + While (reader.Read()) + ' Move to Name element + If (reader.NodeType = XmlNodeType.Element And reader.Name = "Name") Then + name = CType(XElement.ReadFrom(reader), XElement) + Exit While + End If + End While + + ' Loop through Item elements + While (reader.Read()) + If (reader.NodeType = XmlNodeType.EndElement) Then + Exit While + End If + + If (reader.NodeType = XmlNodeType.Element And reader.Name = "Item") Then + item = CType(XElement.ReadFrom(reader), XElement) + If (Not (item Is Nothing)) Then + Dim tempRoot = New XElement("Root", + New XElement(name) + ) + tempRoot.Add(item) + Yield item + End If + End If + End While + End If + End While + reader.Close() +End Function + +Sub Main() + Dim root As New XStreamingElement("Root", + From el In StreamCustomerItem("c:\trash\Source.xml") + Select New XElement("Item", + New XElement("Customer", CStr(el.Parent.Element("Name"))), + New XElement(el.Element("Key")))) + root.Save("c:\trash\Test.xml") + Console.WriteLine(System.IO.File.ReadAllText("c:\trash\Test.xml")) +End Sub +``` + + This example produces the following output: + +```xml + + + + A. Datum Corporation + 0001 + + + A. Datum Corporation + 0002 + + + A. Datum Corporation + 0003 + + + A. Datum Corporation + 0004 + + + Fabrikam, Inc. + 0005 + + + Fabrikam, Inc. + 0006 + + + Fabrikam, Inc. + 0007 + + + Fabrikam, Inc. + 0008 + + + Southridge Video + 0009 + + + Southridge Video + 0010 + + +``` + ]]> LINQ to XML overview @@ -493,13 +493,13 @@ End Sub Initializes a new instance of the class. - is serialized. This is in contrast to using queries for content for an , where queries are iterated at the time of construction of the new . - - For details about the valid content that can be passed to this constructor, see [Valid Content of XElement and XDocument Objects](/dotnet/standard/linq/valid-content-xelement-xdocument-objects). - + is serialized. This is in contrast to using queries for content for an , where queries are iterated at the time of construction of the new . + + For details about the valid content that can be passed to this constructor, see [Valid Content of XElement and XDocument Objects](/dotnet/standard/linq/valid-content-xelement-xdocument-objects). + ]]> LINQ to XML overview @@ -544,64 +544,64 @@ End Sub An that contains the name of the element. Initializes a new instance of the class from the specified . - . Typical use of this constructor is to specify a string as the parameter instead of creating a new . - - - -## Examples - -```csharp -XElement srcTree = new XElement("Root", - new XElement("Child", 1), - new XElement("Child", 2), - new XElement("Child", 3), - new XElement("Child", 4), - new XElement("Child", 5) - ); - -XStreamingElement dstTree = new XStreamingElement("NewRoot", - from el in srcTree.Elements() - where (int)el >= 3 - select new XElement("DifferentChild", (int)el) - ); - -Console.WriteLine(dstTree); -``` - -```vb -Dim srcTree As XElement = _ - - 1 - 2 - 3 - 4 - 5 - - -Dim dstTree As XStreamingElement = New XStreamingElement("NewRoot", _ - From el In srcTree.Elements _ - Where el.Value >= 3 _ - Select <%= el.Value %> _ - ) - -Console.WriteLine(dstTree) -``` - - This example produces the following output: - -``` - - 3 - 4 - 5 - -``` - + . Typical use of this constructor is to specify a string as the parameter instead of creating a new . + + + +## Examples + +```csharp +XElement srcTree = new XElement("Root", + new XElement("Child", 1), + new XElement("Child", 2), + new XElement("Child", 3), + new XElement("Child", 4), + new XElement("Child", 5) + ); + +XStreamingElement dstTree = new XStreamingElement("NewRoot", + from el in srcTree.Elements() + where (int)el >= 3 + select new XElement("DifferentChild", (int)el) + ); + +Console.WriteLine(dstTree); +``` + +```vb +Dim srcTree As XElement = _ + + 1 + 2 + 3 + 4 + 5 + + +Dim dstTree As XStreamingElement = New XStreamingElement("NewRoot", _ + From el In srcTree.Elements _ + Where el.Value >= 3 _ + Select <%= el.Value %> _ + ) + +Console.WriteLine(dstTree) +``` + + This example produces the following output: + +``` + + 3 + 4 + 5 + +``` + ]]> LINQ to XML overview @@ -656,37 +656,37 @@ Console.WriteLine(dstTree) The contents of the element. Initializes a new instance of the class with the specified name and content. - . Typical use of this constructor is to specify a string as the parameter instead of creating a new . - - Queries are not iterated until the is serialized. This is in contrast to using queries for content for an , where queries are iterated at the time of construction of the new . - - For details about the valid content that can be passed to this constructor, see [Valid Content of XElement and XDocument Objects](/dotnet/standard/linq/valid-content-xelement-xdocument-objects). - - - -## Examples - This example uses the following XML file, named Source.xml: - -```xml - - - - aaa - - - bbb - - - ccc - - -``` - + . Typical use of this constructor is to specify a string as the parameter instead of creating a new . + + Queries are not iterated until the is serialized. This is in contrast to using queries for content for an , where queries are iterated at the time of construction of the new . + + For details about the valid content that can be passed to this constructor, see [Valid Content of XElement and XDocument Objects](/dotnet/standard/linq/valid-content-xelement-xdocument-objects). + + + +## Examples + This example uses the following XML file, named Source.xml: + +```xml + + + + aaa + + + bbb + + + ccc + + +``` + ]]> LINQ to XML overview @@ -751,37 +751,37 @@ Console.WriteLine(dstTree) The contents of the element. Initializes a new instance of the class with the specified name and content. - . Typical use of this constructor is to specify a string as the parameter instead of creating a new . - - Queries are not iterated until the is serialized. This is in contrast to using queries for content for an , where queries are iterated at the time of construction of the new . - - For details about the valid content that can be passed to this function, see [Valid Content of XElement and XDocument Objects](/dotnet/standard/linq/valid-content-xelement-xdocument-objects). - - - -## Examples - This example uses the following XML file, named Source.xml: - -```xml - - - - aaa - - - bbb - - - ccc - - -``` - + . Typical use of this constructor is to specify a string as the parameter instead of creating a new . + + Queries are not iterated until the is serialized. This is in contrast to using queries for content for an , where queries are iterated at the time of construction of the new . + + For details about the valid content that can be passed to this function, see [Valid Content of XElement and XDocument Objects](/dotnet/standard/linq/valid-content-xelement-xdocument-objects). + + + +## Examples + This example uses the following XML file, named Source.xml: + +```xml + + + + aaa + + + bbb + + + ccc + + +``` + ]]> LINQ to XML overview @@ -848,84 +848,84 @@ Console.WriteLine(dstTree) Content to be added to the streaming element. Adds the specified content as children to this . - . While it is often possible to construct the in a single statement, it is sometimes more convenient to add content to the streaming element incrementally. - - Queries are not iterated until the is serialized. This is in contrast to using queries for content for an , where queries are iterated at the time of construction of the new . - - For details about the valid content that can be passed to this function, see [Valid Content of XElement and XDocument Objects](/dotnet/standard/linq/valid-content-xelement-xdocument-objects). - - - -## Examples - The following example creates a new . It then adds two queries to the streaming element. The queries are not iterated until the streaming element is serialized. - -```csharp -XElement srcTree = new XElement("Root", - new XElement("Child", 1), - new XElement("Child", 2), - new XElement("Child", 3), - new XElement("Child", 4), - new XElement("Child", 5) - ); - -XStreamingElement dstTree = new XStreamingElement("NewRoot"); - -dstTree.Add( - from el in srcTree.Elements() - where (int)el <= 1 - select new XElement("Child", (int)el) -); - -dstTree.Add( - from el in srcTree.Elements() - where (int)el >= 3 - select new XElement("DifferentChild", (int)el) -); - -Console.WriteLine(dstTree); -``` - -```vb -Dim srcTree As XElement = _ - - 1 - 2 - 3 - 4 - 5 - - -Dim dstTree As XStreamingElement = New XStreamingElement("NewRoot") - -dstTree.Add( _ - From el In srcTree.Elements() _ - Where el.Value <= 1 _ - Select <%= el.Value %> _ -) - -dstTree.Add( _ - From el In srcTree.Elements() _ - Where el.Value >= 3 _ - Select <%= el.Value %> _ -) - -Console.WriteLine(dstTree) -``` - - This example produces the following output: - -```xml - - 1 - 3 - 4 - 5 - -``` - + . While it is often possible to construct the in a single statement, it is sometimes more convenient to add content to the streaming element incrementally. + + Queries are not iterated until the is serialized. This is in contrast to using queries for content for an , where queries are iterated at the time of construction of the new . + + For details about the valid content that can be passed to this function, see [Valid Content of XElement and XDocument Objects](/dotnet/standard/linq/valid-content-xelement-xdocument-objects). + + + +## Examples + The following example creates a new . It then adds two queries to the streaming element. The queries are not iterated until the streaming element is serialized. + +```csharp +XElement srcTree = new XElement("Root", + new XElement("Child", 1), + new XElement("Child", 2), + new XElement("Child", 3), + new XElement("Child", 4), + new XElement("Child", 5) + ); + +XStreamingElement dstTree = new XStreamingElement("NewRoot"); + +dstTree.Add( + from el in srcTree.Elements() + where (int)el <= 1 + select new XElement("Child", (int)el) +); + +dstTree.Add( + from el in srcTree.Elements() + where (int)el >= 3 + select new XElement("DifferentChild", (int)el) +); + +Console.WriteLine(dstTree); +``` + +```vb +Dim srcTree As XElement = _ + + 1 + 2 + 3 + 4 + 5 + + +Dim dstTree As XStreamingElement = New XStreamingElement("NewRoot") + +dstTree.Add( _ + From el In srcTree.Elements() _ + Where el.Value <= 1 _ + Select <%= el.Value %> _ +) + +dstTree.Add( _ + From el In srcTree.Elements() _ + Where el.Value >= 3 _ + Select <%= el.Value %> _ +) + +Console.WriteLine(dstTree) +``` + + This example produces the following output: + +```xml + + 1 + 3 + 4 + 5 + +``` + ]]> LINQ to XML overview @@ -991,84 +991,84 @@ Console.WriteLine(dstTree) Content to be added to the streaming element. Adds the specified content as children to this . - . While it is often possible to construct the in a single statement, it is sometimes more convenient to add content to the streaming element incrementally. - - Queries are not iterated until the is serialized. This is in contrast to using queries for content for an , where queries are iterated at the time of construction of the new . - - For details about the valid content that can be passed to this function, see [Valid Content of XElement and XDocument Objects](/dotnet/standard/linq/valid-content-xelement-xdocument-objects). - - - -## Examples - The following example creates a new . It then adds two queries to the streaming element. The queries are not iterated until the streaming element is serialized. - -```csharp -XElement srcTree = new XElement("Root", - new XElement("Child", 1), - new XElement("Child", 2), - new XElement("Child", 3), - new XElement("Child", 4), - new XElement("Child", 5) - ); - -XStreamingElement dstTree = new XStreamingElement("NewRoot"); - -dstTree.Add( - from el in srcTree.Elements() - where (int)el <= 1 - select new XElement("Child", (int)el) -); - -dstTree.Add( - from el in srcTree.Elements() - where (int)el >= 3 - select new XElement("DifferentChild", (int)el) -); - -Console.WriteLine(dstTree); -``` - -```vb -Dim srcTree As XElement = _ - - 1 - 2 - 3 - 4 - 5 - - -Dim dstTree As XStreamingElement = New XStreamingElement("NewRoot") - -dstTree.Add( _ - From el In srcTree.Elements() _ - Where el.Value <= 1 _ - Select <%= el.Value %> _ -) - -dstTree.Add( _ - From el In srcTree.Elements() _ - Where el.Value >= 3 _ - Select <%= el.Value %> _ -) - -Console.WriteLine(dstTree) -``` - - This example produces the following output: - -```xml - - 1 - 3 - 4 - 5 - -``` - + . While it is often possible to construct the in a single statement, it is sometimes more convenient to add content to the streaming element incrementally. + + Queries are not iterated until the is serialized. This is in contrast to using queries for content for an , where queries are iterated at the time of construction of the new . + + For details about the valid content that can be passed to this function, see [Valid Content of XElement and XDocument Objects](/dotnet/standard/linq/valid-content-xelement-xdocument-objects). + + + +## Examples + The following example creates a new . It then adds two queries to the streaming element. The queries are not iterated until the streaming element is serialized. + +```csharp +XElement srcTree = new XElement("Root", + new XElement("Child", 1), + new XElement("Child", 2), + new XElement("Child", 3), + new XElement("Child", 4), + new XElement("Child", 5) + ); + +XStreamingElement dstTree = new XStreamingElement("NewRoot"); + +dstTree.Add( + from el in srcTree.Elements() + where (int)el <= 1 + select new XElement("Child", (int)el) +); + +dstTree.Add( + from el in srcTree.Elements() + where (int)el >= 3 + select new XElement("DifferentChild", (int)el) +); + +Console.WriteLine(dstTree); +``` + +```vb +Dim srcTree As XElement = _ + + 1 + 2 + 3 + 4 + 5 + + +Dim dstTree As XStreamingElement = New XStreamingElement("NewRoot") + +dstTree.Add( _ + From el In srcTree.Elements() _ + Where el.Value <= 1 _ + Select <%= el.Value %> _ +) + +dstTree.Add( _ + From el In srcTree.Elements() _ + Where el.Value >= 3 _ + Select <%= el.Value %> _ +) + +Console.WriteLine(dstTree) +``` + + This example produces the following output: + +```xml + + 1 + 3 + 4 + 5 + +``` + ]]> LINQ to XML overview @@ -1119,54 +1119,54 @@ Console.WriteLine(dstTree) Gets or sets the name of this streaming element. An that contains the name of this streaming element. - = 3 - select new XElement("DifferentChild", (int)el) - ); - -Console.WriteLine(dstTree.Name); -``` - -```vb -Dim srcTree As XElement = _ - - 1 - 2 - 3 - 4 - 5 - - -Dim dstTree As XStreamingElement = New XStreamingElement("NewRoot", _ - From el In srcTree.Elements _ - Where el.Value >= 3 _ - Select <%= el.Value %> _ - ) - -Console.WriteLine(dstTree.Name) -``` - - This example produces the following output: - -``` -NewRoot -``` - + = 3 + select new XElement("DifferentChild", (int)el) + ); + +Console.WriteLine(dstTree.Name); +``` + +```vb +Dim srcTree As XElement = _ + + 1 + 2 + 3 + 4 + 5 + + +Dim dstTree As XStreamingElement = New XStreamingElement("NewRoot", _ + From el In srcTree.Elements _ + Where el.Value >= 3 _ + Select <%= el.Value %> _ + ) + +Console.WriteLine(dstTree.Name) +``` + + This example produces the following output: + +``` +NewRoot +``` + ]]> LINQ to XML overview @@ -1231,15 +1231,15 @@ NewRoot The stream to output this to. Outputs this to the specified . - that takes as a parameter. Use the option to save unindented XML. This will cause the writer to write all white spaces exactly as represented in the XML tree. - - Use option if you want to remove duplicate namespace declarations. - + that takes as a parameter. Use the option to save unindented XML. This will cause the writer to write all white spaces exactly as represented in the XML tree. + + Use option if you want to remove duplicate namespace declarations. + ]]> @@ -1292,70 +1292,70 @@ NewRoot A that the will be written to. Serialize this streaming element to a . - that take as a parameter. For more information, see [Preserve white space while loading or parsing XML](/dotnet/standard/linq/preserve-white-space-loading-parsing-xml) and [Preserve white space while serializing](/dotnet/standard/linq/preserve-white-space-serializing). - - - -## Examples - The following example creates a source XML tree, then instantiates an using a query on the source XML tree. It then writes the streaming element to a . - -```csharp -XElement srcTree = new XElement("Root", - new XElement("Child", 1), - new XElement("Child", 2), - new XElement("Child", 3), - new XElement("Child", 4), - new XElement("Child", 5) - ); - -XStreamingElement dstTree = new XStreamingElement("NewRoot", - from el in srcTree.Elements() - where (int)el >= 3 - select new XElement("DifferentChild", (int)el) - ); - -StringBuilder sb = new StringBuilder(); -dstTree.Save(new StringWriter(sb)); -Console.WriteLine(sb.ToString()); -``` - -```vb -Dim srcTree As XElement = _ - - 1 - 2 - 3 - 4 - 5 - - -Dim dstTree As XStreamingElement = New XStreamingElement("NewRoot", _ - From el In srcTree.Elements() _ - Where el.Value >= 3 _ - Select <%= el.Value %> _ - ) - -Dim sb As StringBuilder = New StringBuilder() -dstTree.Save(New StringWriter(sb)) -Console.WriteLine(sb.ToString()) -``` - - This example produces the following output: - -```xml - - - 3 - 4 - 5 - -``` - + that take as a parameter. For more information, see [Preserve white space while loading or parsing XML](/dotnet/standard/linq/preserve-white-space-loading-parsing-xml) and [Preserve white space while serializing](/dotnet/standard/linq/preserve-white-space-serializing). + + + +## Examples + The following example creates a source XML tree, then instantiates an using a query on the source XML tree. It then writes the streaming element to a . + +```csharp +XElement srcTree = new XElement("Root", + new XElement("Child", 1), + new XElement("Child", 2), + new XElement("Child", 3), + new XElement("Child", 4), + new XElement("Child", 5) + ); + +XStreamingElement dstTree = new XStreamingElement("NewRoot", + from el in srcTree.Elements() + where (int)el >= 3 + select new XElement("DifferentChild", (int)el) + ); + +StringBuilder sb = new StringBuilder(); +dstTree.Save(new StringWriter(sb)); +Console.WriteLine(sb.ToString()); +``` + +```vb +Dim srcTree As XElement = _ + + 1 + 2 + 3 + 4 + 5 + + +Dim dstTree As XStreamingElement = New XStreamingElement("NewRoot", _ + From el In srcTree.Elements() _ + Where el.Value >= 3 _ + Select <%= el.Value %> _ + ) + +Dim sb As StringBuilder = New StringBuilder() +dstTree.Save(New StringWriter(sb)) +Console.WriteLine(sb.ToString()) +``` + + This example produces the following output: + +```xml + + + 3 + 4 + 5 + +``` + ]]> LINQ to XML overview @@ -1401,74 +1401,74 @@ Console.WriteLine(sb.ToString()) System.Void - + A that contains the name of the file. Serialize this streaming element to a file. - that take as a parameter. For more information, see [Preserve white space while loading or parsing XML](/dotnet/standard/linq/preserve-white-space-loading-parsing-xml) and [Preserve white space while serializing](/dotnet/standard/linq/preserve-white-space-serializing). - - - -## Examples - The following example creates a streaming XML tree. It then serializes the streaming XML tree to a file. - -```csharp -XElement srcTree = new XElement("Root", - new XElement("Child", 1), - new XElement("Child", 2), - new XElement("Child", 3), - new XElement("Child", 4), - new XElement("Child", 5) - ); - -XStreamingElement dstTree = new XStreamingElement("NewRoot", - from el in srcTree.Elements() - where (int)el >= 3 - select new XElement("DifferentChild", (int)el) - ); - -dstTree.Save("Test.xml"); -Console.WriteLine(File.ReadAllText("Test.xml")); -``` - -```vb -Dim srcTree As XElement = _ - - 1 - 2 - 3 - 4 - 5 - - -Dim dstTree As XStreamingElement = New XStreamingElement("NewRoot", _ - From el In srcTree.Elements() _ - Where el.Value >= 3 _ - Select <%= el.Value %> _ - ) - -dstTree.Save("Test.xml") -Console.WriteLine(File.ReadAllText("Test.xml")) -``` - - This example produces the following output: - -```xml - - - 3 - 4 - 5 - -``` - + that take as a parameter. For more information, see [Preserve white space while loading or parsing XML](/dotnet/standard/linq/preserve-white-space-loading-parsing-xml) and [Preserve white space while serializing](/dotnet/standard/linq/preserve-white-space-serializing). + + + +## Examples + The following example creates a streaming XML tree. It then serializes the streaming XML tree to a file. + +```csharp +XElement srcTree = new XElement("Root", + new XElement("Child", 1), + new XElement("Child", 2), + new XElement("Child", 3), + new XElement("Child", 4), + new XElement("Child", 5) + ); + +XStreamingElement dstTree = new XStreamingElement("NewRoot", + from el in srcTree.Elements() + where (int)el >= 3 + select new XElement("DifferentChild", (int)el) + ); + +dstTree.Save("Test.xml"); +Console.WriteLine(File.ReadAllText("Test.xml")); +``` + +```vb +Dim srcTree As XElement = _ + + 1 + 2 + 3 + 4 + 5 + + +Dim dstTree As XStreamingElement = New XStreamingElement("NewRoot", _ + From el In srcTree.Elements() _ + Where el.Value >= 3 _ + Select <%= el.Value %> _ + ) + +dstTree.Save("Test.xml") +Console.WriteLine(File.ReadAllText("Test.xml")) +``` + + This example produces the following output: + +```xml + + + 3 + 4 + 5 + +``` + ]]> LINQ to XML overview @@ -1516,66 +1516,66 @@ Console.WriteLine(File.ReadAllText("Test.xml")) A that the will be written to. Serialize this streaming element to an . - and writes it to an . - -```csharp -XElement srcTree = new XElement("Root", - new XElement("Child", 1), - new XElement("Child", 2), - new XElement("Child", 3), - new XElement("Child", 4), - new XElement("Child", 5) - ); - -StringBuilder sb = new StringBuilder(); -XmlWriterSettings xws = new XmlWriterSettings(); -xws.OmitXmlDeclaration = true; -using (XmlWriter xw = XmlWriter.Create(sb, xws)) -{ - XStreamingElement dstTree = new XStreamingElement("NewRoot", - from el in srcTree.Elements() - where (int)el == 5 - select new XElement("DifferentChild", (int)el) - ); - - dstTree.Save(xw); -} -Console.WriteLine(sb.ToString()); -``` - -```vb -Dim srcTree As XElement = _ - - 1 - 2 - 3 - 4 - 5 - - -Dim sb As StringBuilder = New StringBuilder() -Dim xws As XmlWriterSettings = New XmlWriterSettings() -xws.OmitXmlDeclaration = True -Using xw As XmlWriter = XmlWriter.Create(sb, xws) - Dim dstTree As XStreamingElement = New XStreamingElement("NewRoot", _ - From el In srcTree.Elements() _ - Where el.Value = 5 _ - Select <%= el.Value %> _ - ) - dstTree.Save(xw) -End Using -Console.WriteLine(sb.ToString()) -``` - - This example produces the following output: - -```xml -5 -``` - + and writes it to an . + +```csharp +XElement srcTree = new XElement("Root", + new XElement("Child", 1), + new XElement("Child", 2), + new XElement("Child", 3), + new XElement("Child", 4), + new XElement("Child", 5) + ); + +StringBuilder sb = new StringBuilder(); +XmlWriterSettings xws = new XmlWriterSettings(); +xws.OmitXmlDeclaration = true; +using (XmlWriter xw = XmlWriter.Create(sb, xws)) +{ + XStreamingElement dstTree = new XStreamingElement("NewRoot", + from el in srcTree.Elements() + where (int)el == 5 + select new XElement("DifferentChild", (int)el) + ); + + dstTree.Save(xw); +} +Console.WriteLine(sb.ToString()); +``` + +```vb +Dim srcTree As XElement = _ + + 1 + 2 + 3 + 4 + 5 + + +Dim sb As StringBuilder = New StringBuilder() +Dim xws As XmlWriterSettings = New XmlWriterSettings() +xws.OmitXmlDeclaration = True +Using xw As XmlWriter = XmlWriter.Create(sb, xws) + Dim dstTree As XStreamingElement = New XStreamingElement("NewRoot", _ + From el In srcTree.Elements() _ + Where el.Value = 5 _ + Select <%= el.Value %> _ + ) + dstTree.Save(xw) +End Using +Console.WriteLine(sb.ToString()) +``` + + This example produces the following output: + +```xml +5 +``` + ]]> LINQ to XML overview @@ -1624,15 +1624,15 @@ Console.WriteLine(sb.ToString()) A object that specifies formatting behavior. Outputs this to the specified , optionally specifying formatting behavior. - . This option will remove all extraneous insignificant white space, and add appropriate insignificant white space so that the XML is properly indented. - - If you want to save unindented XML, specify the flag for `options`. This will cause the writer to write all white spaces exactly as represented in the XML tree. - - Use option if you want to remove duplicate namespace declarations. - + . This option will remove all extraneous insignificant white space, and add appropriate insignificant white space so that the XML is properly indented. + + If you want to save unindented XML, specify the flag for `options`. This will cause the writer to write all white spaces exactly as represented in the XML tree. + + Use option if you want to remove duplicate namespace declarations. + ]]> @@ -1681,80 +1681,80 @@ Console.WriteLine(sb.ToString()) A that specifies formatting behavior. Serialize this streaming element to a , optionally disabling formatting. - flag for `options`. This will cause the writer to write all white space exactly as represented in the XML tree. - - If you want to save indented XML, do not specify the flag for `options`. This will remove all extraneous insignificant white space, and add appropriate insignificant white space so that the XML is properly indented. This is the default behavior, and the behavior of the overloads of the methods that do not take `options` as a parameter. - - For more information, see [Preserve white space while loading or parsing XML](/dotnet/standard/linq/preserve-white-space-loading-parsing-xml) and [Preserve white space while serializing](/dotnet/standard/linq/preserve-white-space-serializing). - - - -## Examples - The following example shows two uses of this method. The first use preserves white space. The second one serializes the with formatting. - -```csharp -XElement srcTree = new XElement("Root", - new XElement("Child", 1), - new XElement("Child", 2), - new XElement("Child", 3), - new XElement("Child", 4), - new XElement("Child", 5) - ); - -XStreamingElement dstTree = new XStreamingElement("NewRoot", - from el in srcTree.Elements() - where (int)el == 3 - select new XElement("DifferentChild", (int)el) - ); - -StringBuilder sb = new StringBuilder(); -dstTree.Save(new StringWriter(sb), SaveOptions.DisableFormatting); -Console.WriteLine(sb.ToString()); -Console.WriteLine("------"); -sb = new StringBuilder(); -dstTree.Save(new StringWriter(sb), SaveOptions.None); -Console.WriteLine(sb.ToString()); -``` - -```vb -Dim srcTree As XElement = _ - - 1 - 2 - 3 - 4 - 5 - - -Dim dstTree As XStreamingElement = New XStreamingElement("NewRoot", _ - From el In srcTree.Elements() _ - Where el.Value = 3 _ - Select <%= el.Value %> _ - ) - -Dim sb As StringBuilder = New StringBuilder() -dstTree.Save(New StringWriter(sb), SaveOptions.DisableFormatting) -Console.WriteLine(sb.ToString()) -Console.WriteLine("------") -sb = New StringBuilder() -dstTree.Save(New StringWriter(sb), SaveOptions.None) -Console.WriteLine(sb.ToString()) -``` - - This example produces the following output: - -```xml -3 ------- - - - 3 - -``` - + flag for `options`. This will cause the writer to write all white space exactly as represented in the XML tree. + + If you want to save indented XML, do not specify the flag for `options`. This will remove all extraneous insignificant white space, and add appropriate insignificant white space so that the XML is properly indented. This is the default behavior, and the behavior of the overloads of the methods that do not take `options` as a parameter. + + For more information, see [Preserve white space while loading or parsing XML](/dotnet/standard/linq/preserve-white-space-loading-parsing-xml) and [Preserve white space while serializing](/dotnet/standard/linq/preserve-white-space-serializing). + + + +## Examples + The following example shows two uses of this method. The first use preserves white space. The second one serializes the with formatting. + +```csharp +XElement srcTree = new XElement("Root", + new XElement("Child", 1), + new XElement("Child", 2), + new XElement("Child", 3), + new XElement("Child", 4), + new XElement("Child", 5) + ); + +XStreamingElement dstTree = new XStreamingElement("NewRoot", + from el in srcTree.Elements() + where (int)el == 3 + select new XElement("DifferentChild", (int)el) + ); + +StringBuilder sb = new StringBuilder(); +dstTree.Save(new StringWriter(sb), SaveOptions.DisableFormatting); +Console.WriteLine(sb.ToString()); +Console.WriteLine("------"); +sb = new StringBuilder(); +dstTree.Save(new StringWriter(sb), SaveOptions.None); +Console.WriteLine(sb.ToString()); +``` + +```vb +Dim srcTree As XElement = _ + + 1 + 2 + 3 + 4 + 5 + + +Dim dstTree As XStreamingElement = New XStreamingElement("NewRoot", _ + From el In srcTree.Elements() _ + Where el.Value = 3 _ + Select <%= el.Value %> _ + ) + +Dim sb As StringBuilder = New StringBuilder() +dstTree.Save(New StringWriter(sb), SaveOptions.DisableFormatting) +Console.WriteLine(sb.ToString()) +Console.WriteLine("------") +sb = New StringBuilder() +dstTree.Save(New StringWriter(sb), SaveOptions.None) +Console.WriteLine(sb.ToString()) +``` + + This example produces the following output: + +```xml +3 +------ + + + 3 + +``` + ]]> LINQ to XML overview @@ -1794,84 +1794,84 @@ Console.WriteLine(sb.ToString()) System.Void - - + + A that contains the name of the file. A object that specifies formatting behavior. Serialize this streaming element to a file, optionally disabling formatting. - flag for `options`. This will cause the writer to write all white space exactly as represented in the XML tree. - - If you want to save indented XML, do not specify the flag for `options`. This will remove all extraneous insignificant white space, and add appropriate insignificant white space so that the XML is properly indented. This is the default behavior, and the behavior of the overloads of the methods that do not take `options` as a parameter. - - For more information, see [Preserve white space while loading or parsing XML](/dotnet/standard/linq/preserve-white-space-loading-parsing-xml) and [Preserve white space while serializing](/dotnet/standard/linq/preserve-white-space-serializing). - - - -## Examples - The following example shows two uses of this method. The first use preserves white space. The second one serializes the with formatting. - -```csharp -XElement srcTree = new XElement("Root", - new XElement("Child", 1), - new XElement("Child", 2), - new XElement("Child", 3), - new XElement("Child", 4), - new XElement("Child", 5) - ); - -XStreamingElement dstTree = new XStreamingElement("NewRoot", - from el in srcTree.Elements() - where (int)el == 3 - select new XElement("DifferentChild", (int)el) - ); - -dstTree.Save("Test1.xml", SaveOptions.DisableFormatting); -dstTree.Save("Test2.xml", SaveOptions.None); -Console.WriteLine(File.ReadAllText("Test1.xml")); -Console.WriteLine("------"); -Console.WriteLine(File.ReadAllText("Test2.xml")); -``` - -```vb -Dim srcTree As XElement = _ - - 1 - 2 - 3 - 4 - 5 - - -Dim dstTree As XStreamingElement = New XStreamingElement("NewRoot", _ - From el In srcTree.Elements() _ - Where el.Value = 3 _ - Select <%= el.Value %> _ - ) - -dstTree.Save("Test1.xml", SaveOptions.DisableFormatting) -dstTree.Save("Test2.xml", SaveOptions.None) -Console.WriteLine(File.ReadAllText("Test1.xml")) -Console.WriteLine("------") -Console.WriteLine(File.ReadAllText("Test2.xml")) -``` - - This example produces the following output: - -``` -3 ------- - - - 3 - -``` - + flag for `options`. This will cause the writer to write all white space exactly as represented in the XML tree. + + If you want to save indented XML, do not specify the flag for `options`. This will remove all extraneous insignificant white space, and add appropriate insignificant white space so that the XML is properly indented. This is the default behavior, and the behavior of the overloads of the methods that do not take `options` as a parameter. + + For more information, see [Preserve white space while loading or parsing XML](/dotnet/standard/linq/preserve-white-space-loading-parsing-xml) and [Preserve white space while serializing](/dotnet/standard/linq/preserve-white-space-serializing). + + + +## Examples + The following example shows two uses of this method. The first use preserves white space. The second one serializes the with formatting. + +```csharp +XElement srcTree = new XElement("Root", + new XElement("Child", 1), + new XElement("Child", 2), + new XElement("Child", 3), + new XElement("Child", 4), + new XElement("Child", 5) + ); + +XStreamingElement dstTree = new XStreamingElement("NewRoot", + from el in srcTree.Elements() + where (int)el == 3 + select new XElement("DifferentChild", (int)el) + ); + +dstTree.Save("Test1.xml", SaveOptions.DisableFormatting); +dstTree.Save("Test2.xml", SaveOptions.None); +Console.WriteLine(File.ReadAllText("Test1.xml")); +Console.WriteLine("------"); +Console.WriteLine(File.ReadAllText("Test2.xml")); +``` + +```vb +Dim srcTree As XElement = _ + + 1 + 2 + 3 + 4 + 5 + + +Dim dstTree As XStreamingElement = New XStreamingElement("NewRoot", _ + From el In srcTree.Elements() _ + Where el.Value = 3 _ + Select <%= el.Value %> _ + ) + +dstTree.Save("Test1.xml", SaveOptions.DisableFormatting) +dstTree.Save("Test2.xml", SaveOptions.None) +Console.WriteLine(File.ReadAllText("Test1.xml")) +Console.WriteLine("------") +Console.WriteLine(File.ReadAllText("Test2.xml")) +``` + + This example produces the following output: + +``` +3 +------ + + + 3 + +``` + ]]> LINQ to XML overview @@ -1886,11 +1886,11 @@ Console.WriteLine(File.ReadAllText("Test2.xml")) Returns the XML for this streaming element, optionally disabling formatting. - , displaying the value of an object causes its method to be called. This causes the XML to be serialized. If the semantics of your streaming element query are such that the streaming element can only be streamed once, this may cause undesirable behavior in your debugging experience. - + , displaying the value of an object causes its method to be called. This causes the XML to be serialized. If the semantics of your streaming element query are such that the streaming element can only be streamed once, this may cause undesirable behavior in your debugging experience. + ]]> LINQ to XML overview @@ -1942,67 +1942,67 @@ Console.WriteLine(File.ReadAllText("Test2.xml")) Returns the formatted (indented) XML for this streaming element. A containing the indented XML. - , displaying the value of an object causes its method to be called. This causes the XML to be serialized. If the semantics of your streaming element query are such that the streaming element can only be streamed once, this may cause undesirable behavior in your debugging experience. - - - -## Examples - The following example shows two uses of . The first use preserves white space. The second one serializes the with formatting. - -```csharp -XElement srcTree = new XElement("Root", - new XElement("Child", 1), - new XElement("Child", 2), - new XElement("Child", 3), - new XElement("Child", 4), - new XElement("Child", 5) - ); - -XStreamingElement dstTree = new XStreamingElement("NewRoot", - from el in srcTree.Elements() - where (int)el == 3 - select new XElement("DifferentChild", (int)el) - ); - -Console.WriteLine(dstTree.ToString(SaveOptions.DisableFormatting)); -Console.WriteLine("------"); -Console.WriteLine(dstTree.ToString()); -``` - -```vb -Dim srcTree As XElement = _ - - 1 - 2 - 3 - 4 - 5 - - -Dim dstTree As XStreamingElement = New XStreamingElement("NewRoot", _ - From el In srcTree.Elements() _ - Where el.Value = 3 _ - Select <%= el.Value %> _ - ) - -Console.WriteLine(dstTree.ToString(SaveOptions.DisableFormatting)) -Console.WriteLine("------") -Console.WriteLine(dstTree.ToString()) -``` - - This example produces the following output: - -``` -3 ------- - - 3 - -``` - + , displaying the value of an object causes its method to be called. This causes the XML to be serialized. If the semantics of your streaming element query are such that the streaming element can only be streamed once, this may cause undesirable behavior in your debugging experience. + + + +## Examples + The following example shows two uses of . The first use preserves white space. The second one serializes the with formatting. + +```csharp +XElement srcTree = new XElement("Root", + new XElement("Child", 1), + new XElement("Child", 2), + new XElement("Child", 3), + new XElement("Child", 4), + new XElement("Child", 5) + ); + +XStreamingElement dstTree = new XStreamingElement("NewRoot", + from el in srcTree.Elements() + where (int)el == 3 + select new XElement("DifferentChild", (int)el) + ); + +Console.WriteLine(dstTree.ToString(SaveOptions.DisableFormatting)); +Console.WriteLine("------"); +Console.WriteLine(dstTree.ToString()); +``` + +```vb +Dim srcTree As XElement = _ + + 1 + 2 + 3 + 4 + 5 + + +Dim dstTree As XStreamingElement = New XStreamingElement("NewRoot", _ + From el In srcTree.Elements() _ + Where el.Value = 3 _ + Select <%= el.Value %> _ + ) + +Console.WriteLine(dstTree.ToString(SaveOptions.DisableFormatting)) +Console.WriteLine("------") +Console.WriteLine(dstTree.ToString()) +``` + + This example produces the following output: + +``` +3 +------ + + 3 + +``` + ]]> LINQ to XML overview @@ -2057,67 +2057,67 @@ Console.WriteLine(dstTree.ToString()) Returns the XML for this streaming element, optionally disabling formatting. A containing the XML. - , displaying the value of an object causes its method to be called. This causes the XML to be serialized. If the semantics of your streaming element query are such that the streaming element can only be streamed once, this may cause undesirable behavior in your debugging experience. - - - -## Examples - The following example shows two uses of . The first use preserves white space. The second one serializes the with formatting. - -```csharp -XElement srcTree = new XElement("Root", - new XElement("Child", 1), - new XElement("Child", 2), - new XElement("Child", 3), - new XElement("Child", 4), - new XElement("Child", 5) - ); - -XStreamingElement dstTree = new XStreamingElement("NewRoot", - from el in srcTree.Elements() - where (int)el == 3 - select new XElement("DifferentChild", (int)el) - ); - -Console.WriteLine(dstTree.ToString(SaveOptions.DisableFormatting)); -Console.WriteLine("------"); -Console.WriteLine(dstTree.ToString()); -``` - -```vb -Dim srcTree As XElement = _ - - 1 - 2 - 3 - 4 - 5 - - -Dim dstTree As XStreamingElement = New XStreamingElement("NewRoot", _ - From el In srcTree.Elements() _ - Where el.Value = 3 _ - Select <%= el.Value %> _ - ) - -Console.WriteLine(dstTree.ToString(SaveOptions.DisableFormatting)) -Console.WriteLine("------") -Console.WriteLine(dstTree.ToString()) -``` - - This example produces the following output: - -``` -3 ------- - - 3 - -``` - + , displaying the value of an object causes its method to be called. This causes the XML to be serialized. If the semantics of your streaming element query are such that the streaming element can only be streamed once, this may cause undesirable behavior in your debugging experience. + + + +## Examples + The following example shows two uses of . The first use preserves white space. The second one serializes the with formatting. + +```csharp +XElement srcTree = new XElement("Root", + new XElement("Child", 1), + new XElement("Child", 2), + new XElement("Child", 3), + new XElement("Child", 4), + new XElement("Child", 5) + ); + +XStreamingElement dstTree = new XStreamingElement("NewRoot", + from el in srcTree.Elements() + where (int)el == 3 + select new XElement("DifferentChild", (int)el) + ); + +Console.WriteLine(dstTree.ToString(SaveOptions.DisableFormatting)); +Console.WriteLine("------"); +Console.WriteLine(dstTree.ToString()); +``` + +```vb +Dim srcTree As XElement = _ + + 1 + 2 + 3 + 4 + 5 + + +Dim dstTree As XStreamingElement = New XStreamingElement("NewRoot", _ + From el In srcTree.Elements() _ + Where el.Value = 3 _ + Select <%= el.Value %> _ + ) + +Console.WriteLine(dstTree.ToString(SaveOptions.DisableFormatting)) +Console.WriteLine("------") +Console.WriteLine(dstTree.ToString()) +``` + + This example produces the following output: + +``` +3 +------ + + 3 + +``` + ]]> LINQ to XML overview @@ -2165,73 +2165,73 @@ Console.WriteLine(dstTree.ToString()) An into which this method will write. Writes this streaming element to an . - . It then writes the streaming element to an . - -```csharp -XElement srcTree = new XElement("Root", - new XElement("Child", 1), - new XElement("Child", 2), - new XElement("Child", 3), - new XElement("Child", 4), - new XElement("Child", 5) - ); - -XStreamingElement dstTree = new XStreamingElement("NewRoot", - from el in srcTree.Elements() - where (int)el == 3 - select new XElement("DifferentChild", (int)el) - ); - -StringBuilder sb = new StringBuilder(); -XmlWriterSettings xws = new XmlWriterSettings(); -xws.OmitXmlDeclaration = true; -xws.Indent = true; - -using (XmlWriter xw = XmlWriter.Create(sb, xws)) -{ - dstTree.WriteTo(xw); -} -Console.WriteLine(sb.ToString()); -``` - -```vb -Dim srcTree As XElement = _ - - 1 - 2 - 3 - 4 - 5 - - -Dim dstTree As XStreamingElement = _ - New XStreamingElement("NewRoot", _ - From el In srcTree.Elements() _ - Where el.Value = 3 _ - Select <%= el.Value %> ) - -Dim sb As StringBuilder = New StringBuilder() -Dim xws As XmlWriterSettings = New XmlWriterSettings() -xws.OmitXmlDeclaration = True -xws.Indent = True - -Using xw As XmlWriter = XmlWriter.Create(sb, xws) - dstTree.WriteTo(xw) -End Using -Console.WriteLine(sb.ToString()) -``` - - This example produces the following output: - -```xml - - 3 - -``` - + . It then writes the streaming element to an . + +```csharp +XElement srcTree = new XElement("Root", + new XElement("Child", 1), + new XElement("Child", 2), + new XElement("Child", 3), + new XElement("Child", 4), + new XElement("Child", 5) + ); + +XStreamingElement dstTree = new XStreamingElement("NewRoot", + from el in srcTree.Elements() + where (int)el == 3 + select new XElement("DifferentChild", (int)el) + ); + +StringBuilder sb = new StringBuilder(); +XmlWriterSettings xws = new XmlWriterSettings(); +xws.OmitXmlDeclaration = true; +xws.Indent = true; + +using (XmlWriter xw = XmlWriter.Create(sb, xws)) +{ + dstTree.WriteTo(xw); +} +Console.WriteLine(sb.ToString()); +``` + +```vb +Dim srcTree As XElement = _ + + 1 + 2 + 3 + 4 + 5 + + +Dim dstTree As XStreamingElement = _ + New XStreamingElement("NewRoot", _ + From el In srcTree.Elements() _ + Where el.Value = 3 _ + Select <%= el.Value %> ) + +Dim sb As StringBuilder = New StringBuilder() +Dim xws As XmlWriterSettings = New XmlWriterSettings() +xws.OmitXmlDeclaration = True +xws.Indent = True + +Using xw As XmlWriter = XmlWriter.Create(sb, xws) + dstTree.WriteTo(xw) +End Using +Console.WriteLine(sb.ToString()) +``` + + This example produces the following output: + +```xml + + 3 + +``` + ]]> LINQ to XML overview diff --git a/xml/System.Xml.Schema/XmlSchema.xml b/xml/System.Xml.Schema/XmlSchema.xml index cc7355b5d33..fab4b629a55 100644 --- a/xml/System.Xml.Schema/XmlSchema.xml +++ b/xml/System.Xml.Schema/XmlSchema.xml @@ -70,28 +70,28 @@ An in-memory representation of an XML Schema, as specified in the World Wide Web Consortium (W3C) XML Schema Part 1: Structures and XML Schema Part 2: Datatypes]. - [!IMPORTANT] -> - Do not use schemas from unknown or untrusted sources or locations. Doing so will compromise the security of your code. -> - XML schemas (including inline schemas) are inherently vulnerable to denial of service attacks; do not accept them in untrusted scenarios. -> - Exceptions raised as a result of using the class, such as the class, may contain sensitive information that should not be exposed in untrusted scenarios. For example, the property of an returns the URI path to the schema file that caused the exception. The property should not be exposed in untrusted scenarios. Exceptions should be properly handled so this sensitive information is not exposed in untrusted scenarios. - - - -## Examples - The following example creates a schema definition. - +> - Do not use schemas from unknown or untrusted sources or locations. Doing so will compromise the security of your code. +> - XML schemas (including inline schemas) are inherently vulnerable to denial of service attacks; do not accept them in untrusted scenarios. +> - Exceptions raised as a result of using the class, such as the class, may contain sensitive information that should not be exposed in untrusted scenarios. For example, the property of an returns the URI path to the schema file that caused the exception. The property should not be exposed in untrusted scenarios. Exceptions should be properly handled so this sensitive information is not exposed in untrusted scenarios. + + + +## Examples + The following example creates a schema definition. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/Classic WebData XmlSchema Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.Schema/XmlSchema/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/Classic WebData XmlSchema Example/VB/source.vb" id="Snippet1"::: - - The following XML file is generated for the preceding code example. - - :::code language="xml" source="~/snippets/xml/VS_Snippets_Data/Classic WebData XmlSchema Example/XML/source.xml" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/Classic WebData XmlSchema Example/VB/source.vb" id="Snippet1"::: + + The following XML file is generated for the preceding code example. + + :::code language="xml" source="~/snippets/xml/VS_Snippets_Data/Classic WebData XmlSchema Example/XML/source.xml" id="Snippet2"::: + ]]> Working with XML Schemas @@ -100,11 +100,11 @@ - - - - - + + + + + Constructor System.Xml @@ -191,19 +191,19 @@ Gets or sets the form for attributes declared in the target namespace of the schema. The value that indicates if attributes from the target namespace are required to be qualified with the namespace prefix. The default is . - values shown in the following table. - -| Value|Description| -|----------------------------------------------------------------------------------------------------------------------------------------------------|-----------------| -||The attribute form is not specified in schema.| -||Attributes from the target namespace must be qualified with the namespace prefix.| -||Attributes from the target namespace are not required to be qualified with the namespace prefix.| - - This value is the global default for all attributes declared in the target namespace. Individual attributes can override this setting for the local scope using the `form` attribute. - + values shown in the following table. + +| Value|Description| +|----------------------------------------------------------------------------------------------------------------------------------------------------|-----------------| +||The attribute form is not specified in schema.| +||Attributes from the target namespace must be qualified with the namespace prefix.| +||Attributes from the target namespace are not required to be qualified with the namespace prefix.| + + This value is the global default for all attributes declared in the target namespace. Individual attributes can override this setting for the local scope using the `form` attribute. + ]]> @@ -356,23 +356,23 @@ Gets or sets the attribute which sets the default value of the attribute on element and complex types in the of the schema. An value representing the different methods for preventing derivation. The default value is . - . - -|Value|Description| -|-----------|-----------------| -|`None`|By default, there are no restrictions on type derivations in the schema.| -|`Empty`|Overrides the default derivation method and allows any type derivations in the schema.| -|`Extension`|By default, elements in this schema cannot be derived by Extension. Applies only to element and complex type elements.| -|`Restriction`|By default, elements in this schema cannot be derived by Restriction.| -|`Union`|By default, elements in this schema cannot be derived by Union. Applies only to simple types.| -|`List`|By default, elements in this schema cannot be derived by List. Applies only to simple types.| -|`All`|`#all`. By default, elements in this schema cannot be derived by any method.| - + . + +|Value|Description| +|-----------|-----------------| +|`None`|By default, there are no restrictions on type derivations in the schema.| +|`Empty`|Overrides the default derivation method and allows any type derivations in the schema.| +|`Extension`|By default, elements in this schema cannot be derived by Extension. Applies only to element and complex type elements.| +|`Restriction`|By default, elements in this schema cannot be derived by Restriction.| +|`Union`|By default, elements in this schema cannot be derived by Union. Applies only to simple types.| +|`List`|By default, elements in this schema cannot be derived by List. Applies only to simple types.| +|`All`|`#all`. By default, elements in this schema cannot be derived by any method.| + ]]> @@ -386,13 +386,13 @@ Compiles the XML Schema Object Model (SOM) into schema information for validation. Used to check the syntactic and semantic structure of the programmatically built SOM. Semantic validation checking is performed during compilation. - [!IMPORTANT] -> The method is obsolete in the Microsoft .NET Framework version 2.0 and has been replaced by the method. - +> The method is obsolete in the Microsoft .NET Framework version 2.0 and has been replaced by the method. + ]]> @@ -451,19 +451,19 @@ System.Void - + The validation event handler that receives information about XML Schema validation errors. Compiles the XML Schema Object Model (SOM) into schema information for validation. Used to check the syntactic and semantic structure of the programmatically built SOM. Semantic validation checking is performed during compilation. - [!IMPORTANT] -> The method is obsolete in the Microsoft .NET Framework version 2.0 and has been replaced by the method. - +> The method is obsolete in the Microsoft .NET Framework version 2.0 and has been replaced by the method. + ]]> @@ -522,25 +522,25 @@ System.Void - - + + The validation event handler that receives information about the XML Schema validation errors. The used to resolve namespaces referenced in and elements. Compiles the XML Schema Object Model (SOM) into schema information for validation. Used to check the syntactic and semantic structure of the programmatically built SOM. Semantic validation checking is performed during compilation. - [!IMPORTANT] -> The method is obsolete in the Microsoft .NET Framework version 2.0 and has been replaced by the method. - +> The method is obsolete in the Microsoft .NET Framework version 2.0 and has been replaced by the method. + > [!IMPORTANT] -> The method uses the class to resolve external schemas referenced in include, import, or redefine elements by default. You can disable resolution of external schemas by passing null as the parameter. - +> The method uses the class to resolve external schemas referenced in include, import, or redefine elements by default. You can disable resolution of external schemas by passing null as the parameter. + ]]> @@ -601,19 +601,19 @@ Gets or sets the form for elements declared in the target namespace of the schema. The value that indicates if elements from the target namespace are required to be qualified with the namespace prefix. The default is . - values shown in the following table. - -| Value|Description| -|----------------------------------------------------------------------------------------------------------------------------------------------------|-----------------| -||The element form is not specified in the schema.| -||Elements from the target namespace must be qualified with the namespace prefix.| -||Elements from the target namespace are not required to be qualified with the namespace prefix.| - - This value is the global default for all elements declared in the target namespace. Individual elements can override this setting for the local scope by using the `form` attribute. - + values shown in the following table. + +| Value|Description| +|----------------------------------------------------------------------------------------------------------------------------------------------------|-----------------| +||The element form is not specified in the schema.| +||Elements from the target namespace must be qualified with the namespace prefix.| +||Elements from the target namespace are not required to be qualified with the namespace prefix.| + + This value is the global default for all elements declared in the target namespace. Individual elements can override this setting for the local scope by using the `form` attribute. + ]]> @@ -720,23 +720,23 @@ Gets or sets the attribute which sets the default value of the attribute on elements and complex types in the target namespace of the schema. An value representing the different methods for preventing derivation. The default value is . - . - -|Value|Description| -|-----------|-----------------| -|`None`|By default, there are no restrictions on type derivations in the schema.| -|`Empty`|Overrides the default derivation method and allows any type derivations in the schema.| -|`Extension`|By default, elements in this schema cannot be derived by Extension. Applies only to element and complex type elements.| -|`Restriction`|By default, elements in this schema cannot be derived by Restriction.| -|`Union`|By default, elements in this schema cannot be derived by Union. Applies only to simple types.| -|`List`|By default, elements in this schema cannot be derived by List. Applies only to simple types.| -|`All`|`#all`. By default, elements in this schema cannot be derived by any method.| - + . + +|Value|Description| +|-----------|-----------------| +|`None`|By default, there are no restrictions on type derivations in the schema.| +|`Empty`|Overrides the default derivation method and allows any type derivations in the schema.| +|`Extension`|By default, elements in this schema cannot be derived by Extension. Applies only to element and complex type elements.| +|`Restriction`|By default, elements in this schema cannot be derived by Restriction.| +|`Union`|By default, elements in this schema cannot be derived by Union. Applies only to simple types.| +|`List`|By default, elements in this schema cannot be derived by List. Applies only to simple types.| +|`All`|`#all`. By default, elements in this schema cannot be derived by any method.| + ]]> @@ -914,33 +914,33 @@ Gets the collection of included and imported schemas. An of the included and imported schemas. - method expects only and its derived types (, , and ) as parameters. The following example illustrates adding an included schema to the collection of an existing object. - -```vb -Dim schema As XmlSchema = New XmlSchema() - -Dim textReader As XmlTextReader = New XmlTextReader("include.xsd") -Dim includeSchema As XmlSchema = XmlSchema.Read(textReader, null) - -Dim include As XmlSchemaInclude = New XmlSchemaInclude() -include.Schema = includeSchema; -schema.Includes.Add(include); -``` - -```csharp -XmlSchema schema = new XmlSchema(); - -XmlTextReader textReader = new XmlTextReader("include.xsd"); -XmlSchema includeSchema = XmlSchema.Read(textReader, null); - -XmlSchemaInclude include = new XmlSchemaInclude(); -include.Schema = includeSchema; -schema.Includes.Add(include); -``` - + method expects only and its derived types (, , and ) as parameters. The following example illustrates adding an included schema to the collection of an existing object. + +```vb +Dim schema As XmlSchema = New XmlSchema() + +Dim textReader As XmlTextReader = New XmlTextReader("include.xsd") +Dim includeSchema As XmlSchema = XmlSchema.Read(textReader, null) + +Dim include As XmlSchemaInclude = New XmlSchemaInclude() +include.Schema = includeSchema; +schema.Includes.Add(include); +``` + +```csharp +XmlSchema schema = new XmlSchema(); + +XmlTextReader textReader = new XmlTextReader("include.xsd"); +XmlSchema includeSchema = XmlSchema.Read(textReader, null); + +XmlSchemaInclude include = new XmlSchemaInclude(); +include.Schema = includeSchema; +schema.Includes.Add(include); +``` + ]]> @@ -1107,11 +1107,11 @@ schema.Includes.Add(include); Gets the collection of schema elements in the schema and is used to add new element types at the element level. An of schema elements in the schema. - , , , , , , , or . - + , , , , , , , or . + ]]> @@ -1257,7 +1257,7 @@ schema.Includes.Add(include); System.Xml.Schema.XmlSchema - + [System.Runtime.CompilerServices.Nullable(1)] @@ -1265,7 +1265,7 @@ schema.Includes.Add(include); - + The supplied data stream. @@ -1318,7 +1318,7 @@ schema.Includes.Add(include); System.Xml.Schema.XmlSchema - + [System.Runtime.CompilerServices.Nullable(1)] @@ -1326,7 +1326,7 @@ schema.Includes.Add(include); - + The containing the XML Schema to read. @@ -1379,7 +1379,7 @@ schema.Includes.Add(include); System.Xml.Schema.XmlSchema - + [System.Runtime.CompilerServices.Nullable(1)] @@ -1387,7 +1387,7 @@ schema.Includes.Add(include); - + The containing the XML Schema to read. @@ -1509,11 +1509,11 @@ schema.Includes.Add(include); Gets or sets the Uniform Resource Identifier (URI) of the schema target namespace. The schema target namespace. - is the namespace of all schema components in this schema as well as any schema included using the `include` element. Included schemas must either have the same target namespace as the containing schema or have no target namespace specified. - + is the namespace of all schema components in this schema as well as any schema included using the `include` element. Included schemas must either have the same target namespace as the containing schema or have no target namespace specified. + ]]> @@ -1699,7 +1699,7 @@ schema.Includes.Add(include); System.Void - + The supplied data stream. @@ -1752,7 +1752,7 @@ schema.Includes.Add(include); System.Void - + The to write to. @@ -1805,7 +1805,7 @@ schema.Includes.Add(include); System.Void - + The to write to. @@ -1856,8 +1856,8 @@ schema.Includes.Add(include); System.Void - - + + [System.Runtime.CompilerServices.Nullable(2)] @@ -1871,13 +1871,13 @@ schema.Includes.Add(include); The . Writes the XML Schema to the supplied using the specified. - [!NOTE] -> Supplying an disables automatic namespace prefix mapping. - +> Supplying an disables automatic namespace prefix mapping. + ]]> @@ -1924,8 +1924,8 @@ schema.Includes.Add(include); System.Void - - + + [System.Runtime.CompilerServices.Nullable(2)] @@ -1939,13 +1939,13 @@ schema.Includes.Add(include); The . Writes the XML Schema to the supplied . - [!NOTE] -> Supplying an disables automatic namespace prefix mapping. - +> Supplying an disables automatic namespace prefix mapping. + ]]> @@ -1992,8 +1992,8 @@ schema.Includes.Add(include); System.Void - - + + [System.Runtime.CompilerServices.Nullable(2)] @@ -2007,13 +2007,13 @@ schema.Includes.Add(include); The . Writes the XML Schema to the supplied . - [!NOTE] -> Supplying an disables automatic namespace prefix mapping. - +> Supplying an disables automatic namespace prefix mapping. + ]]> diff --git a/xml/System.Xml.Schema/XmlSchemaDatatype.xml b/xml/System.Xml.Schema/XmlSchemaDatatype.xml index f1c5a93334b..532d640c7ce 100644 --- a/xml/System.Xml.Schema/XmlSchemaDatatype.xml +++ b/xml/System.Xml.Schema/XmlSchemaDatatype.xml @@ -52,29 +52,29 @@ The class is an abstract class for mapping XML Schema definition language (XSD) types to Common Language Runtime (CLR) types. - class. - + class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/Classic Webdata XmlSchemaDatatype Example/CPP/datatype.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.Schema/XmlSchemaDatatype/Overview/datatype.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/Classic Webdata XmlSchemaDatatype Example/VB/datatype.vb" id="Snippet1"::: - - The following XML file is used for the preceding code example. - - :::code language="xml" source="~/snippets/xml/VS_Snippets_Data/Classic Webdata XmlSchemaDatatype Example/XML/example.xsd" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/Classic Webdata XmlSchemaDatatype Example/VB/datatype.vb" id="Snippet1"::: + + The following XML file is used for the preceding code example. + + :::code language="xml" source="~/snippets/xml/VS_Snippets_Data/Classic Webdata XmlSchemaDatatype Example/XML/example.xsd" id="Snippet2"::: + ]]> - - - - - + + + + + Constructor System.Xml @@ -106,11 +106,11 @@ Initializes a new instance of the class. - @@ -168,11 +168,11 @@ Converts the value specified, whose type is one of the valid Common Language Runtime (CLR) representations of the XML schema type represented by the , to the CLR type specified. The converted input value. - classes and conversion of XML data types, see the [Type Support in the System.Xml Classes](/dotnet/standard/data/xml/type-support-in-the-system-xml-classes) topic. - + classes and conversion of XML data types, see the [Type Support in the System.Xml Classes](/dotnet/standard/data/xml/type-support-in-the-system-xml-classes) topic. + ]]> The or parameter is . @@ -224,11 +224,11 @@ Converts the value specified, whose type is one of the valid Common Language Runtime (CLR) representations of the XML schema type represented by the , to the CLR type specified using the if the represents the xs:QName type or a type derived from it. The converted input value. - classes and conversion of XML data types, see the [Type Support in the System.Xml Classes](/dotnet/standard/data/xml/type-support-in-the-system-xml-classes) topic. - + classes and conversion of XML data types, see the [Type Support in the System.Xml Classes](/dotnet/standard/data/xml/type-support-in-the-system-xml-classes) topic. + ]]> The or parameter is . @@ -338,34 +338,34 @@ When overridden in a derived class, validates the specified against a built-in or user-defined simple type. An that can be cast safely to the type returned by the property. - method validates the `string` specified against a built-in or user-defined simple type. For example, if this represents the type xs:date, then an instance of is returned. - - The following are the steps performed during the method's validation process. - -1. Convert the value specified as a `string` to its corresponding Common Language Runtime (CLR) type. - -2. Verify that the value does not violate any facets defined for the simple type. - - The converted value is then returned as an and can be cast safely to the type returned by the property. - - When the object represents a list type, the input `string` value is converted to a list of one or more objects. When the object represents a list type, an attempt is made to parse the input value as a member type of the union. If the parse attempt fails, then the conversion is attempted with the next member of the union until the parse is successful or there are no other member types to parse. If the parse is unsuccessful, an exception is thrown. - - - -## Examples - The following example retrieves the `LotteryNumber` simple type from the example.xsd file as an and then validates the `string` value of `5` using the method. - + method validates the `string` specified against a built-in or user-defined simple type. For example, if this represents the type xs:date, then an instance of is returned. + + The following are the steps performed during the method's validation process. + +1. Convert the value specified as a `string` to its corresponding Common Language Runtime (CLR) type. + +2. Verify that the value does not violate any facets defined for the simple type. + + The converted value is then returned as an and can be cast safely to the type returned by the property. + + When the object represents a list type, the input `string` value is converted to a list of one or more objects. When the object represents a list type, an attempt is made to parse the input value as a member type of the union. If the parse attempt fails, then the conversion is attempted with the next member of the union until the parse is successful or there are no other member types to parse. If the parse is unsuccessful, an exception is thrown. + + + +## Examples + The following example retrieves the `LotteryNumber` simple type from the example.xsd file as an and then validates the `string` value of `5` using the method. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/Classic Webdata XmlSchemaDatatype Example/CPP/datatype.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.Schema/XmlSchemaDatatype/Overview/datatype.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/Classic Webdata XmlSchemaDatatype Example/VB/datatype.vb" id="Snippet1"::: - - The following XML file is used for the preceding code example. - - :::code language="xml" source="~/snippets/xml/VS_Snippets_Data/Classic Webdata XmlSchemaDatatype Example/XML/example.xsd" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/Classic Webdata XmlSchemaDatatype Example/VB/datatype.vb" id="Snippet1"::: + + The following XML file is used for the preceding code example. + + :::code language="xml" source="~/snippets/xml/VS_Snippets_Data/Classic Webdata XmlSchemaDatatype Example/XML/example.xsd" id="Snippet2"::: + ]]> The input value is not a valid instance of this W3C XML Schema type. @@ -407,7 +407,7 @@ method validates the specified string against a built-in or user-defined simple type. For example, if this represents the type xs:date, then an instance of is returned. The following are the steps performed during the method's validation process. @@ -464,29 +464,29 @@ When the object represents a list typ When overridden in a derived class, gets the type for the as specified in the World Wide Web Consortium (W3C) XML 1.0 specification. An value for the . - @@ -528,19 +528,19 @@ When the object represents a list typ Gets the value for the simple type. The value for the simple type. - enumeration. Instead they are represented by the values for the xs:ENTITY, xs:NMTOKEN and xs:IDREF types with the property of the object set to . - + enumeration. Instead they are represented by the values for the xs:ENTITY, xs:NMTOKEN and xs:IDREF types with the property of the object set to . + > [!NOTE] -> Both the xs:anySimpleType and xs:anyType types are not represented by enumeration. These are represented in an object with an whose value is for xs:anySimpleType or for xs:anyType. - - - -## Examples - For an example of the property, see . - +> Both the xs:anySimpleType and xs:anyType types are not represented by enumeration. These are represented in an object with an whose value is for xs:anySimpleType or for xs:anyType. + + + +## Examples + For an example of the property, see . + ]]> @@ -584,18 +584,18 @@ When the object represents a list typ When overridden in a derived class, gets the Common Language Runtime (CLR) type of the item. The Common Language Runtime (CLR) type of the item. - property gets the CLR type of the item. For example, an element of type `xs:int` would have a of by default. However, the could be any one of the valid types that can be mapped to `xs:int`, such as or . - - For more information about type support in the namespace, see [Type Support in the System.Xml Classes](/dotnet/standard/data/xml/type-support-in-the-system-xml-classes). - - - -## Examples - For an example of the property, see . - + property gets the CLR type of the item. For example, an element of type `xs:int` would have a of by default. However, the could be any one of the valid types that can be mapped to `xs:int`, such as or . + + For more information about type support in the namespace, see [Type Support in the System.Xml Classes](/dotnet/standard/data/xml/type-support-in-the-system-xml-classes). + + + +## Examples + For an example of the property, see . + ]]> diff --git a/xml/System.Xml.Schema/XmlSchemaGroupBase.xml b/xml/System.Xml.Schema/XmlSchemaGroupBase.xml index 019938fd077..6c0c8261c06 100644 --- a/xml/System.Xml.Schema/XmlSchemaGroupBase.xml +++ b/xml/System.Xml.Schema/XmlSchemaGroupBase.xml @@ -52,21 +52,21 @@ An abstract class for , , or . - , , and for examples using this class. - + , , and for examples using this class. + ]]> - - - - - + + + + + Constructor System.Xml diff --git a/xml/System.Xml.Serialization/SoapCodeExporter.xml b/xml/System.Xml.Serialization/SoapCodeExporter.xml index c8685679cfb..478bbc74002 100644 --- a/xml/System.Xml.Serialization/SoapCodeExporter.xml +++ b/xml/System.Xml.Serialization/SoapCodeExporter.xml @@ -24,11 +24,11 @@ Generates types and attribute declarations from internal type mapping information for SOAP-encoded message parts defined in a WSDL document. - class is used by the [Web Services Description Language Tool (Wsdl.exe)](https://docs.microsoft.com/previous-versions/dotnet/netframework-4.0/7h3ystb6(v=vs.100)) and the class while generating client proxy classes or abstract server classes from a Web Services Description Language (WSDL) document. Instead of using directly, use Wsdl.exe. - + class is used by the [Web Services Description Language Tool (Wsdl.exe)](https://docs.microsoft.com/previous-versions/dotnet/netframework-4.0/7h3ystb6(v=vs.100)) and the class while generating client proxy classes or abstract server classes from a Web Services Description Language (WSDL) document. Instead of using directly, use Wsdl.exe. + ]]> @@ -67,11 +67,11 @@ A that specifies the namespace of the types to generate. Initializes a new instance of the class, assuming no code compile unit. - class, use the Wsdl.exe tool. - + class, use the Wsdl.exe tool. + ]]> @@ -100,11 +100,11 @@ A that identifies the program graph container to which used assembly references are automatically added. Initializes a new instance of the class, specifying a code compile unit parameter in addition to a namespace parameter. - class, use the Wsdl.exe tool. - + class, use the Wsdl.exe tool. + ]]> @@ -124,9 +124,9 @@ 4.0.0.0 - - - + + + A that specifies the namespace of the types to generate. @@ -134,11 +134,11 @@ A enumeration that specifies the options with which exported code is generated. Initializes a new instance of the class, specifying a code namespace, a code compile unit, and code generation options. - class, use the Wsdl.exe tool. - + class, use the Wsdl.exe tool. + ]]> @@ -158,10 +158,10 @@ 4.0.0.0 - - - - + + + + A that specifies the namespace of the types to generate. @@ -170,11 +170,11 @@ A that contains objects. Initializes a new instance of the class, specifying a code namespace, a code compile unit, code generation options, and mappings. - class, use the Wsdl.exe tool. - + class, use the Wsdl.exe tool. + ]]> @@ -200,11 +200,11 @@ - - - - - + + + + + A that specifies the namespace of the types to generate. @@ -252,11 +252,11 @@ An internal .NET Framework type mapping for a single part of a WSDL message definition. Add a declaration to a method parameter or return value corresponding to a part element of a SOAP message definition in a WSDL document. - @@ -291,11 +291,11 @@ to add an initial argument that contains the XML element name for the attribute declaration that is being generated; otherwise, . Adds a declaration to a method parameter or return value that corresponds to a part element of a SOAP message definition in a WSDL document. - @@ -325,11 +325,11 @@ Internal .NET Framework type mappings for the element parts of a WSDL message definition. Generates a .NET Framework type, plus attribute declarations, for each of the parts that belong to a SOAP message definition in a WSDL document. - @@ -359,11 +359,11 @@ Internal .NET Framework type mapping information for a SOAP header element. Generates a .NET Framework type, plus attribute declarations, for a SOAP header. - @@ -390,7 +390,7 @@ attributes can be applied to a base type to allow one or more derived types to be serialized, depending on an object's actual type at run time. Rather than use the class, use the Wsdl.exe tool. diff --git a/xml/System.Xml.Serialization/SoapSchemaImporter.xml b/xml/System.Xml.Serialization/SoapSchemaImporter.xml index 90fd426f133..c789d0a1d51 100644 --- a/xml/System.Xml.Serialization/SoapSchemaImporter.xml +++ b/xml/System.Xml.Serialization/SoapSchemaImporter.xml @@ -24,13 +24,13 @@ Used within the .NET Framework to generate internal mappings to .NET Framework types for SOAP-encoded message parts in a WSDL document. - class is used by the [Web Services Description Language Tool (Wsdl.exe)](https://msdn.microsoft.com/library/b9210348-8bc2-4367-8c91-d1a04b403e88), and the class, while generating client proxy classes or abstract server classes from a Web Services Description Language (WSDL) document. Instead of using this class directly, use Wsdl.exe. - - The class has methods to generate internal mappings to .NET Framework types for part elements defined in a WSDL document. The class is used only when a WSDL document specifies SOAP encoding, as described in Section 5 of the SOAP 1.1 specification. - + class is used by the [Web Services Description Language Tool (Wsdl.exe)](https://msdn.microsoft.com/library/b9210348-8bc2-4367-8c91-d1a04b403e88), and the class, while generating client proxy classes or abstract server classes from a Web Services Description Language (WSDL) document. Instead of using this class directly, use Wsdl.exe. + + The class has methods to generate internal mappings to .NET Framework types for part elements defined in a WSDL document. The class is used only when a WSDL document specifies SOAP encoding, as described in Section 5 of the SOAP 1.1 specification. + ]]> @@ -69,13 +69,13 @@ A collection of objects. Initializes a new instance of the class, specifying objects representing the XML schemas used by SOAP encoded messages defined in a WSDL document. - class directly, use Wsdl.exe. - + class directly, use Wsdl.exe. + ]]> @@ -104,13 +104,13 @@ A object that specifies a collection of classes being generated for bindings defined in a WSDL document. Initializes a new instance of the class, specifying objects representing the XML schemas used by SOAP encoded messages, plus classes being generated for bindings defined in a WSDL document. - class directly, use Wsdl.exe. - + class directly, use Wsdl.exe. + ]]> @@ -130,9 +130,9 @@ 4.0.0.0 - - - + + + A collection of objects. @@ -157,9 +157,9 @@ 4.0.0.0 - - - + + + A collection of objects. @@ -190,10 +190,10 @@ - - - - + + + + An containing a collection of objects. @@ -235,13 +235,13 @@ Generates internal type mapping information for the type of a SOAP-encoded element part defined in a WSDL document where a base type is specified. The .NET Framework type mapping information for a derived type corresponding to a WSDL message part. - method of the class is used by the [Web Services Description Language Tool (Wsdl.exe)](https://msdn.microsoft.com/library/b9210348-8bc2-4367-8c91-d1a04b403e88) while generating client proxy classes or abstract server classes from a Web Services Description Language (WSDL) document. Instead of calling this method directly, use Wsdl.exe. - - The class is used only when a WSDL document specifies SOAP encoding, as described in Section 5 of the SOAP 1.1 specification. - + method of the class is used by the [Web Services Description Language Tool (Wsdl.exe)](https://msdn.microsoft.com/library/b9210348-8bc2-4367-8c91-d1a04b403e88) while generating client proxy classes or abstract server classes from a Web Services Description Language (WSDL) document. Instead of calling this method directly, use Wsdl.exe. + + The class is used only when a WSDL document specifies SOAP encoding, as described in Section 5 of the SOAP 1.1 specification. + ]]> @@ -285,13 +285,13 @@ Generates internal type mapping information for a single SOAP-encoded element part defined in a WSDL document. The .NET Framework type mapping for a single element part of a WSDL message definition. - method of the class is used by the Wsdl.exe tool while generating client proxy classes or abstract server classes from a Web Services Description Language (WSDL) document. Instead of calling this method directly, use Wsdl.exe. - - The class is used only when a WSDL document specifies SOAP encoding, as described in Section 5 of the SOAP 1.1 specification. This signature of the method is used when a WSDL message is wrapped within a single part element. - + method of the class is used by the Wsdl.exe tool while generating client proxy classes or abstract server classes from a Web Services Description Language (WSDL) document. Instead of calling this method directly, use Wsdl.exe. + + The class is used only when a WSDL document specifies SOAP encoding, as described in Section 5 of the SOAP 1.1 specification. This signature of the method is used when a WSDL message is wrapped within a single part element. + ]]> @@ -332,13 +332,13 @@ Generates internal type mapping information for the element parts of a SOAP-encoded message defined in a WSDL document. The .NET Framework type mappings for the element parts of a WSDL message definition. - method of the class is used by the Wsdl.exe tool while generating client proxy classes or abstract server classes from a Web Services Description Language (WSDL) document. Instead of calling this method directly, use Wsdl.exe. - - The class is used only when a WSDL document specifies SOAP encoding, as described in Section 5 of the SOAP 1.1 specification. The parameter values to the method are taken from a message definition in a WSDL document, including the part elements the message element contains. - + method of the class is used by the Wsdl.exe tool while generating client proxy classes or abstract server classes from a Web Services Description Language (WSDL) document. Instead of calling this method directly, use Wsdl.exe. + + The class is used only when a WSDL document specifies SOAP encoding, as described in Section 5 of the SOAP 1.1 specification. The parameter values to the method are taken from a message definition in a WSDL document, including the part elements the message element contains. + ]]> @@ -382,13 +382,13 @@ Generates internal type mapping information for the element parts of a SOAP-encoded message defined in a WSDL document. The .NET Framework type mappings for the element parts of a WSDL message definition. - method of the class is used by the Wsdl.exe tool while generating client proxy classes or abstract server classes from a Web Services Description Language (WSDL) document. Instead of calling this method directly, use Wsdl.exe. - - The class is used only when a WSDL document specifies SOAP encoding, as described in Section 5 of the SOAP 1.1 specification. The parameter values to the method are taken from a message definition in a WSDL document, including the part elements the message element contains. - + method of the class is used by the Wsdl.exe tool while generating client proxy classes or abstract server classes from a Web Services Description Language (WSDL) document. Instead of calling this method directly, use Wsdl.exe. + + The class is used only when a WSDL document specifies SOAP encoding, as described in Section 5 of the SOAP 1.1 specification. The parameter values to the method are taken from a message definition in a WSDL document, including the part elements the message element contains. + ]]> @@ -431,13 +431,13 @@ Generates internal type mapping information for the element parts of a SOAP-encoded message defined in a WSDL document. The .NET Framework type mappings for the element parts of a WSDL message definition. - method of the class is used by the Wsdl.exe tool while generating client proxy classes or abstract server classes from a Web Services Description Language (WSDL) document. Instead of calling this method directly, use Wsdl.exe. - - The class is used only when a WSDL document specifies SOAP encoding, as described in Section 5 of the SOAP 1.1 specification. The parameter values to the method are taken from a message definition in a WSDL document, including the part elements the message element contains. - + method of the class is used by the Wsdl.exe tool while generating client proxy classes or abstract server classes from a Web Services Description Language (WSDL) document. Instead of calling this method directly, use Wsdl.exe. + + The class is used only when a WSDL document specifies SOAP encoding, as described in Section 5 of the SOAP 1.1 specification. The parameter values to the method are taken from a message definition in a WSDL document, including the part elements the message element contains. + ]]> diff --git a/xml/System.Xml.Serialization/XmlAttributes.xml b/xml/System.Xml.Serialization/XmlAttributes.xml index 9bbe5ca0bd4..5f9bc086533 100644 --- a/xml/System.Xml.Serialization/XmlAttributes.xml +++ b/xml/System.Xml.Serialization/XmlAttributes.xml @@ -59,22 +59,22 @@ Represents a collection of attribute objects that control how the serializes and deserializes an object. - is part of a process that overrides the default way the serializes class instances. For example, suppose you want to serialize an object that is created from a DLL which has an inaccessible source. By using the , you can augment or otherwise control how the object is serialized. - - The members of the class correspond directly to a family of attribute classes that control serialization. For example, the property must be set to an , which allows you to override serialization of a field or property by instructing the to serialize the property value as XML text. For a complete list of attributes that control serialization, see the . - + is part of a process that overrides the default way the serializes class instances. For example, suppose you want to serialize an object that is created from a DLL which has an inaccessible source. By using the , you can augment or otherwise control how the object is serialized. + + The members of the class correspond directly to a family of attribute classes that control serialization. For example, the property must be set to an , which allows you to override serialization of a field or property by instructing the to serialize the property value as XML text. For a complete list of attributes that control serialization, see the . + For more details on using the with the class, see [How to: Specify an Alternate Element Name for an XML Stream](/dotnet/standard/serialization/how-to-specify-an-alternate-element-name-for-an-xml-stream). - -## Examples - The following example serializes an instance of a class named `Orchestra`, which contains a single field named `Instruments` that returns an array of `Instrument` objects. A second class named `Brass` inherits from the `Instrument` class. The example creates an object to override the `Instrument` field--allowing the field to accept `Brass` objects--and adds the object to an instance of the class. - + +## Examples + The following example serializes an instance of a class named `Orchestra`, which contains a single field named `Instruments` that returns an array of `Instrument` objects. A second class named `Brass` inherits from the `Instrument` class. The example creates an object to override the `Instrument` field--allowing the field to accept `Brass` objects--and adds the object to an instance of the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/Classic XmlAttributes.XmlAttributes Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.Serialization/XmlAttributes/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic XmlAttributes.XmlAttributes Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic XmlAttributes.XmlAttributes Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -134,15 +134,15 @@ Initializes a new instance of the class. - object to override the `Instrument` field--allowing the field to accept `Brass` objects--and adds the object to an instance of the class. - + object to override the `Instrument` field--allowing the field to accept `Brass` objects--and adds the object to an instance of the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/Classic XmlAttributes.XmlAttributes Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.Serialization/XmlAttributes/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic XmlAttributes.XmlAttributes Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic XmlAttributes.XmlAttributes Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -188,17 +188,17 @@ - + A class that can provide alternative implementations of attributes that control XML serialization. Initializes a new instance of the class and customizes how the serializes and deserializes an object. - class, rather than using this constructor. - + class, rather than using this constructor. + ]]> @@ -256,13 +256,13 @@ Gets or sets the to override. The to override. - can be applied to a member that returns an array of objects on deserialization. This allows the to deserialize any attributes that do not have a corresponding member in the object being deserialized--thus those elements are "unknown" to the . This is useful when the XML stream has been altered by an XML Web service, or when it is known that random data is always included with the XML stream. - - The property allows you to override the serialization of a member to which the has been applied. - + can be applied to a member that returns an array of objects on deserialization. This allows the to deserialize any attributes that do not have a corresponding member in the object being deserialized--thus those elements are "unknown" to the . This is useful when the XML stream has been altered by an XML Web service, or when it is known that random data is always included with the XML stream. + + The property allows you to override the serialization of a member to which the has been applied. + ]]> @@ -323,20 +323,20 @@ Gets the collection of objects to override. An object that represents the collection of objects. - can be applied to a member that returns an array of objects on deserialization. This allows the to deserialize any elements that do not have a corresponding member in the object being deserialized--thus those elements are "unknown" to the . This is useful when the XML stream has been altered by an XML Web service, or when it is known that random data is always included with the XML stream. - + can be applied to a member that returns an array of objects on deserialization. This allows the to deserialize any elements that do not have a corresponding member in the object being deserialized--thus those elements are "unknown" to the . This is useful when the XML stream has been altered by an XML Web service, or when it is known that random data is always included with the XML stream. + The property allows you to override the serialization of a member to function as a member to which the has been applied. - -## Examples - The following example creates a new object and adds it to the collection of objects accessed through the property. The object is then added to a object which is used to create an object. The is used to serialize or deserialize an object. To see the effect of using the property, create an XML document named "UnknownElements.xml" by running the `SerializeObject` method in the `Main` method. Edit the resulting document to include other (unknown) elements. Comment out the `SerializeObject` call in the `Main` method, and uncomment the call to the `DeserializeObject` method, which prints out the name and value of any unknown XML element. - + +## Examples + The following example creates a new object and adds it to the collection of objects accessed through the property. The object is then added to a object which is used to create an object. The is used to serialize or deserialize an object. To see the effect of using the property, create an XML document named "UnknownElements.xml" by running the `SerializeObject` method in the `Main` method. Edit the resulting document to include other (unknown) elements. Comment out the `SerializeObject` call in the `Main` method, and uncomment the call to the `DeserializeObject` method, which prints out the name and value of any unknown XML element. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/XmlAttributes.XmlAnyElements/CPP/xmlanyover.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.Serialization/XmlAnyElementAttributes/Overview/xmlanyover.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/XmlAttributes.XmlAnyElements/VB/xmlanyover.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/XmlAttributes.XmlAnyElements/VB/xmlanyover.vb" id="Snippet1"::: + ]]> @@ -395,26 +395,26 @@ Gets or sets an object that specifies how the serializes a public field or read/write property that returns an array. An that specifies how the serializes a public field or read/write property that returns an array. - : the default serialization, and the controlled serialization. - - In the default serialization, no attribute is applied to the member. When serialized, the array is serialized as a nested sequence of XML elements with the XML element name of the nested sequence taken from the member name. - - To control the serialization more precisely, apply an to the field or property. For example, you can change the generated XML element name from the default to a different name by setting the property to a new value. - - The property allows you to override the default serialization, as well as the serialization controlled by applying an to the member. For example, you can change the XML element name generated from the default (the member identifier) to a new value. In addition, if you apply an to a member, it is overridden by any that is assigned to the property. - - - -## Examples - The following example serializes a class that contains a field named `Members` that returns an array of objects. The is used to override the serialization of the field, and rename the element name to `Staff`. - + : the default serialization, and the controlled serialization. + + In the default serialization, no attribute is applied to the member. When serialized, the array is serialized as a nested sequence of XML elements with the XML element name of the nested sequence taken from the member name. + + To control the serialization more precisely, apply an to the field or property. For example, you can change the generated XML element name from the default to a different name by setting the property to a new value. + + The property allows you to override the default serialization, as well as the serialization controlled by applying an to the member. For example, you can change the XML element name generated from the default (the member identifier) to a new value. In addition, if you apply an to a member, it is overridden by any that is assigned to the property. + + + +## Examples + The following example serializes a class that contains a field named `Members` that returns an array of objects. The is used to override the serialization of the field, and rename the element name to `Staff`. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/Classic XmlAttributes.XmlArray Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.Serialization/XmlAttributes/XmlArray/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic XmlAttributes.XmlArray Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic XmlAttributes.XmlArray Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -475,18 +475,18 @@ Gets or sets a collection of objects that specify how the serializes items inserted into an array returned by a public field or read/write property. An object that contains a collection of objects. - property allows you to specify the derived types that can be inserted into an array returned by a public field or public read/write property. For each new type you want the field or property to accept, create an object and it to the ) returned by the property. (The new type must be derived from the type already accepted by the field or property.) the object to an object and specify the type of the object that contains the field or property, and the name of the field or property. Construct an with the object before calling or method. - -## Examples - The following example serializes a class that contains a field named `Members` that returns an array of objects. Two objects are created to allow the field to accept objects that derive from the base class named `Member`. Each object is added to the through the property. - + +## Examples + The following example serializes a class that contains a field named `Members` that returns an array of objects. Two objects are created to allow the field to accept objects that derive from the base class named `Member`. Each object is added to the through the property. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/Classic XmlAttributes.XmlArrayItems Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.Serialization/XmlAttributes/XmlArrayItems/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic XmlAttributes.XmlArrayItems Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic XmlAttributes.XmlArrayItems Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -544,20 +544,20 @@ Gets or sets an object that specifies how the serializes a public field or public read/write property as an XML attribute. An that controls the serialization of a public field or read/write property as an XML attribute. - to generate an XML attribute by applying an to the field or property. - + to generate an XML attribute by applying an to the field or property. + The property allows you to override the default serialization, as well as the serialization controlled by applying an to the member. To do this, create an and set its properties (such as ). Assign the new object to the property of an object. Add the object to an object and specify the type of the object that contains the field or property, and the name of the field or property. Lastly, create an using the object and call the or method. - -## Examples - The following example serializes a class named `Group` that contains a property named `GroupName`; the `GroupName` property is serialized as an XML attribute. The example creates an and an object to override the default serialization of the field. The example then creates an to specifically override the property, and the object is set to the property The object is added to the object with the name of the overridden member specified. Finally, an is constructed and returned using the object. - + +## Examples + The following example serializes a class named `Group` that contains a property named `GroupName`; the `GroupName` property is serialized as an XML attribute. The example creates an and an object to override the default serialization of the field. The example then creates an to specifically override the property, and the object is set to the property The object is added to the object with the name of the overridden member specified. Finally, an is constructed and returned using the object. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/Classic XmlAttributes.XmlAttribute Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.Serialization/XmlAttributes/XmlAttribute/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic XmlAttributes.XmlAttribute Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic XmlAttributes.XmlAttribute Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -666,39 +666,39 @@ Gets or sets the default value of an XML element or attribute. An that represents the default value of an XML element or attribute. - to a member. To examine the result of applying the value, compile the application into a DLL or executable, and pass the resulting file as an argument to the XML Schema Definition tool (XSD.exe). In the XML schema document, a default value is assigned to the `default` attribute. In the following example, the default for the \ element is "Dogs." - -``` - - - - - - - - - -``` - - To override the default value, create an and assign it to the . - - If the value assigned to a field or property is equal to the default value for that field or property, the does not serialize the value to the XML-instance. This is because the assigned value can be recovered from the XML schema. In other words, setting a field or property to its own default value is equivalent of not setting it at all. Likewise, if no value is set for the field or property, the uses the default value found in the schema. In both cases, (setting the property to its default, or not setting it at all), the XML-document instance does not contain any value for the property. - + to a member. To examine the result of applying the value, compile the application into a DLL or executable, and pass the resulting file as an argument to the XML Schema Definition tool (XSD.exe). In the XML schema document, a default value is assigned to the `default` attribute. In the following example, the default for the \ element is "Dogs." + +``` + + + + + + + + + +``` + + To override the default value, create an and assign it to the . + + If the value assigned to a field or property is equal to the default value for that field or property, the does not serialize the value to the XML-instance. This is because the assigned value can be recovered from the XML schema. In other words, setting a field or property to its own default value is equivalent of not setting it at all. Likewise, if no value is set for the field or property, the uses the default value found in the schema. In both cases, (setting the property to its default, or not setting it at all), the XML-document instance does not contain any value for the property. + You can use the class constructors instead of the schema to assign the default values. If you are using Xsd.exe to generate a classes from schemas, you can comment out or remove all of the [System.ComponentModel.DefaultValueAttribute("myFieldName")] attributes from the class files. - -## Examples - The following example shows a class named `Pet` that contains a field that has a default value set to "Dog". However, the example also creates an object, and sets its property to a new default value ("Cat"). This overrides the original default value. Thus, if the field value is set to "Cat", the treats it as the default value, and not serialize it. If it is set to any other value, the serializes the value. - + +## Examples + The following example shows a class named `Pet` that contains a field that has a default value set to "Dog". However, the example also creates an object, and sets its property to a new default value ("Cat"). This overrides the original default value. Thus, if the field value is set to "Cat", the treats it as the default value, and not serialize it. If it is set to any other value, the serializes the value. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/Classic XmlAttributes.XmlDefaultValue Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.Serialization/XmlAttributes/XmlDefaultValue/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic XmlAttributes.XmlDefaultValue Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic XmlAttributes.XmlDefaultValue Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -759,18 +759,18 @@ Gets a collection of objects that specify how the serializes a public field or read/write property as an XML element. An that contains a collection of objects. - to an by calling the method. By default, an object is created and assigned to the property. - -## Examples - The following example serializes the `Transportation` class, which contains a single field named `Vehicles` that returns an . The example applies two attributes to the `Vehicles` field. The example creates two objects and adds them to the collection of an object. To allow the array to accept different object types, the object is added to the object. - + +## Examples + The following example serializes the `Transportation` class, which contains a single field named `Vehicles` that returns an . The example applies two attributes to the `Vehicles` field. The example creates two objects and adds them to the collection of an object. To allow the array to accept different object types, the object is added to the object. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/Classic XmlAttributes.XmlElements Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.Serialization/XmlAttributes/XmlElements/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic XmlAttributes.XmlElements Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic XmlAttributes.XmlElements Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -828,18 +828,18 @@ Gets or sets an object that specifies how the serializes an enumeration member. An that specifies how the serializes an enumeration member. - object, and set the property to an that overrides the identifier. Add the object to the object and specify both the of the class that contains the enumeration, and the overridden member name. - -## Examples - The following example serializes two classes named `Food` and `FoodType`. The `FoodType` class contains two enumerations that are overridden and, for each enumeration, the example creates an object that it assigns to the property of an object. The example then adds the object to an object, which is used to create an . - + +## Examples + The following example serializes two classes named `Food` and `FoodType`. The `FoodType` class contains two enumerations that are overridden and, for each enumeration, the example creates an object that it assigns to the property of an object. The example then adds the object to an object, which is used to create an . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/Classic XmlAttributes.XmlEnum Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.Serialization/XmlAttributes/XmlEnum/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic XmlAttributes.XmlEnum Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic XmlAttributes.XmlEnum Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -897,22 +897,22 @@ if the must not serialize the field or property; otherwise, . - . That is, the value of each public field or property is persisted as an XML element or XML attribute in an XML-document instance. - - To override the default serialization of a field or property, create an object, and set its property to `true`. the object to an object and specify the type of the object that contains the field or property to ignore, and the name of the field or property to ignore. - + . That is, the value of each public field or property is persisted as an XML element or XML attribute in an XML-document instance. + + To override the default serialization of a field or property, create an object, and set its property to `true`. the object to an object and specify the type of the object that contains the field or property to ignore, and the name of the field or property to ignore. + If an is applied to a field or property, the field or property is ignored. However you can override that behavior by creating an object, setting its property to `false`, adding it to an object specifying the type of the object that contains the field or property, and the name of the field or property. - -## Examples - The following example serializes a class named `Group`, which contains a member named `Comment` to which the is applied. The example creates an object, and sets the property to `false`, thereby overriding the . - + +## Examples + The following example serializes a class named `Group`, which contains a member named `Comment` to which the is applied. The example creates an object, and sets the property to `false`, thereby overriding the . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/Classic XmlAttributes.XmlIgnore Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.Serialization/XmlAttributes/XmlIgnore/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic XmlAttributes.XmlIgnore Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic XmlAttributes.XmlIgnore Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -971,15 +971,15 @@ if the namespace declarations should be kept; otherwise, . - object. The example creates an object that is added to an instance of the class. The property is set to `true`, which instructs the to preserve the namespaces when the serialization of the `Student` object is overridden. - + object. The example creates an object that is added to an instance of the class. The property is set to `true`, which instructs the to preserve the namespaces when the serialization of the `Student` object is overridden. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/XmlAttributes.Xmlns property example/CPP/xmlns.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.Serialization/XmlAttributes/Xmlns/xmlns.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/XmlAttributes.Xmlns property example/VB/xmlns.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/XmlAttributes.Xmlns property example/VB/xmlns.vb" id="Snippet1"::: + ]]> @@ -1037,15 +1037,15 @@ Gets or sets an object that specifies how the serializes a class as an XML root element. An that overrides a class attributed as an XML root element. - object, an object, and an object. The example assigns the to the property of the object, and adds the object to the object. Lastly, the example gets the object by passing the of the serialized class to the object. (In this example, the is `Group`.) - + object, an object, and an object. The example assigns the to the property of the object, and adds the object to the object. Lastly, the example gets the object by passing the of the serialized class to the object. (In this example, the is `Group`.) + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/Classic XmlAttributes.XmlRoot Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.Serialization/XmlAttributes/XmlRoot/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic XmlAttributes.XmlRoot Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic XmlAttributes.XmlRoot Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -1103,23 +1103,23 @@ Gets or sets an object that instructs the to serialize a public field or public read/write property as XML text. An that overrides the default serialization of a public property or field. - . However, it can force the field or property to be serialized as XML text by applying an to the field or property. - + . However, it can force the field or property to be serialized as XML text by applying an to the field or property. + > [!NOTE] -> The cannot be applied to a field or property that returns an array. - +> The cannot be applied to a field or property that returns an array. + To override the default serialization of a field or property (that does not return an array), create an and assign it to the property of an object. Add the object to an object and specify the type of the object that contains the overridden field or property, and the name of the overridden field or property. - -## Examples - The following example serializes the class named `Group`, which contains a field named `Comment`. To override the default way the serializes the field, the example creates an and an object. The example then creates an object, which it assigns to the property, and adds the object (with the name of the field to be serialized as XML text) to the object. Lastly the example creates an using the object. - + +## Examples + The following example serializes the class named `Group`, which contains a field named `Comment`. To override the default way the serializes the field, the example creates an and an object. The example then creates an object, which it assigns to the property, and adds the object (with the name of the field to be serialized as XML text) to the object. Lastly the example creates an using the object. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/Classic XmlAttributes.XmlText Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.Serialization/XmlAttributes/XmlText/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic XmlAttributes.XmlText Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic XmlAttributes.XmlText Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -1177,18 +1177,18 @@ Gets or sets an object that specifies how the serializes a class to which the has been applied. An that overrides an applied to a class declaration. - can be used to control how a type is serialized by the . For example, by default, when a type is serialized, the uses the class name as the XML element name. By creating an , setting the property to it, and creating an object, you can change the XML element name. - -## Examples - The following example creates an object, and assigns it to the property of an object. - + +## Examples + The following example creates an object, and assigns it to the property of an object. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/Classic XmlAttributes.XmlType Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.Serialization/XmlAttributes/XmlType/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic XmlAttributes.XmlType Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic XmlAttributes.XmlType Example/VB/source.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.Xml.Serialization/XmlCodeExporter.xml b/xml/System.Xml.Serialization/XmlCodeExporter.xml index d9df3b207c0..3c917684be4 100644 --- a/xml/System.Xml.Serialization/XmlCodeExporter.xml +++ b/xml/System.Xml.Serialization/XmlCodeExporter.xml @@ -24,19 +24,19 @@ Generates types and attribute declarations from internal type mapping information for XML schema element declarations. - class generates .NET Framework types or attribute declarations from internal mappings to .NET Framework types. These internal mappings are generated by the class for elements defined in an XSD document or as parts in a Web Services Description Language (WSDL) document. is not used directly; it is used with the Web Services Description Language tool (Wsdl.exe) or the XML Schema Definition tool (Xsd.exe). - - Wsdl.exe uses the types or attribute declarations that are generated by and the internal mappings generated by the class to generate client proxy classes or abstract server classes from a WSDL document. Wsdl.exe uses and the class when a WSDL document specifies: - -- Literal use, indicating that the contents of SOAP message parameters and return values (or request and response documents) are literally specified with XML schema definitions. - -- Non-SOAP implementations of Web services using the HTTP-GET and HTTP-POST operations. - -- Xsd.exe uses to generate classes from XML Schema Definition (XSD) documents. - + class generates .NET Framework types or attribute declarations from internal mappings to .NET Framework types. These internal mappings are generated by the class for elements defined in an XSD document or as parts in a Web Services Description Language (WSDL) document. is not used directly; it is used with the Web Services Description Language tool (Wsdl.exe) or the XML Schema Definition tool (Xsd.exe). + + Wsdl.exe uses the types or attribute declarations that are generated by and the internal mappings generated by the class to generate client proxy classes or abstract server classes from a WSDL document. Wsdl.exe uses and the class when a WSDL document specifies: + +- Literal use, indicating that the contents of SOAP message parameters and return values (or request and response documents) are literally specified with XML schema definitions. + +- Non-SOAP implementations of Web services using the HTTP-GET and HTTP-POST operations. + +- Xsd.exe uses to generate classes from XML Schema Definition (XSD) documents. + ]]> @@ -76,11 +76,11 @@ The namespace of the types to generate. Initializes a new instance of the class using the specified namespace. - class directly, use the Web Services Description Language tool (Wsdl.exe) or the XML Schema Definition tool (Xsd.exe). - + class directly, use the Web Services Description Language tool (Wsdl.exe) or the XML Schema Definition tool (Xsd.exe). + ]]> @@ -109,11 +109,11 @@ A CodeDOM graph container to which used assembly references are automatically added. Initializes a new instance of the class using the specified namespace and code compile unit. - class directly, use the Web Services Description Language tool (Wsdl.exe) or the XML Schema Definition tool (Xsd.exe). - + class directly, use the Web Services Description Language tool (Wsdl.exe) or the XML Schema Definition tool (Xsd.exe). + ]]> @@ -133,9 +133,9 @@ 4.0.0.0 - - - + + + The namespace of the types to generate. @@ -143,11 +143,11 @@ An enumeration value that provides options for generating .NET Framework types from XML schema custom data types. Initializes a new instance of the class using the specified namespace, code compile unit, and code generation options. - class directly, use the Web Services Description Language tool (Wsdl.exe) or the XML Schema Definition tool (Xsd.exe). - + class directly, use the Web Services Description Language tool (Wsdl.exe) or the XML Schema Definition tool (Xsd.exe). + ]]> @@ -167,10 +167,10 @@ 4.0.0.0 - - - - + + + + The namespace of the types to generate. @@ -202,11 +202,11 @@ - - - - - + + + + + The namespace of the types to generate. @@ -256,11 +256,11 @@ The XML namespace of the SOAP message part for which the type mapping information in the member parameter has been generated. Adds an declaration to a method parameter or return value that corresponds to a element of a SOAP message definition in a Web Services Description Language (WSDL) document. - @@ -294,11 +294,11 @@ The XML namespace of the SOAP message part for which the type mapping information in the member parameter has been generated. Adds an declaration to a method return value that corresponds to a element of a non-SOAP message definition in a Web Services Description Language (WSDL) document. - @@ -334,11 +334,11 @@ Flag that helps determine whether to add an initial argument containing the XML element name for the attribute declaration being generated. Adds an declaration to a method parameter or return value that corresponds to a element of a SOAP message definition in a Web Services Description Language (WSDL) document. - @@ -368,11 +368,11 @@ The internal .NET Framework type mappings for the element parts of a WSDL message definition. Generates a .NET Framework type, plus attribute declarations, for each of the parts that belong to a SOAP message definition in a Web Services Description Language (WSDL) document. - @@ -402,11 +402,11 @@ The internal .NET Framework type mapping information for an XML schema element. Generates a .NET Framework type, plus attribute declarations, for an XML schema element. - diff --git a/xml/System.Xml.Serialization/XmlMemberMapping.xml b/xml/System.Xml.Serialization/XmlMemberMapping.xml index e7c70a94fef..62dbca02a97 100644 --- a/xml/System.Xml.Serialization/XmlMemberMapping.xml +++ b/xml/System.Xml.Serialization/XmlMemberMapping.xml @@ -52,27 +52,27 @@ Maps a code entity in a .NET Web service method to an element in a Web Services Description Language (WSDL) message. - class is used with the class, which references an array of objects. - - An object can represent any one of the following: - -- A Web service method input parameter. - -- A Web service method output parameter. - -- A Web service return type, if not void. - -- A SOAP input header. - -- A SOAP output header. - - The objects are accessible through the indexed operator property. - - See the class for an explanation of the conditions under which an object corresponds to a WSDL message definition's `` element. - + class is used with the class, which references an array of objects. + + An object can represent any one of the following: + +- A Web service method input parameter. + +- A Web service method output parameter. + +- A Web service return type, if not void. + +- A SOAP input header. + +- A SOAP output header. + + The objects are accessible through the indexed operator property. + + See the class for an explanation of the conditions under which an object corresponds to a WSDL message definition's `` element. + ]]> @@ -119,11 +119,11 @@ , if the type maps to an XML any element or attribute; otherwise, . - property corresponds to the `` element declaration and the `anyAttribute` attribute declaration in an XML Schema document. - + property corresponds to the `` element declaration and the `anyAttribute` attribute declaration in an XML Schema document. + ]]> @@ -168,11 +168,11 @@ , if the accompanying field has a value specified; otherwise, . - property checks whether such a `bool` field exists. - + property checks whether such a `bool` field exists. + ]]> @@ -242,7 +242,7 @@ System.String - + A that contains the name of the type. @@ -290,15 +290,15 @@ Gets the name of the Web service method member that is represented by this mapping. The name of the Web service method member represented by this mapping. - class for cases when a member corresponds to a `` element defined in a Web Services Description Language (WSDL) document. Note, however, that with a wrapped binding between a WSDL operation and a .NET Framework method, (indicated by the enumeration member), the method parameters and return value do not appear in the WSDL document. - - When a Web service class is being reflected into a object, the return type's property becomes the method name (made unique from other member names, if necessary) with "Result" appended. This convention also is used, in some circumstances, while importing Web service classes from objects generated from WSDL documents. - + class for cases when a member corresponds to a `` element defined in a Web Services Description Language (WSDL) document. Note, however, that with a wrapped binding between a WSDL operation and a .NET Framework method, (indicated by the enumeration member), the method parameters and return value do not appear in the WSDL document. + + When a Web service class is being reflected into a object, the return type's property becomes the method name (made unique from other member names, if necessary) with "Result" appended. This convention also is used, in some circumstances, while importing Web service classes from objects generated from WSDL documents. + ]]> diff --git a/xml/System.Xml.Serialization/XmlSchemaImporter.xml b/xml/System.Xml.Serialization/XmlSchemaImporter.xml index 0793406c8d2..3f7bb347d66 100644 --- a/xml/System.Xml.Serialization/XmlSchemaImporter.xml +++ b/xml/System.Xml.Serialization/XmlSchemaImporter.xml @@ -58,17 +58,17 @@ Generates internal mappings to .NET types for XML schema element declarations, including literal XSD message parts in a WSDL document. - class is used by the [Web Services Description Language Tool (Wsdl.exe)](https://msdn.microsoft.com/library/b9210348-8bc2-4367-8c91-d1a04b403e88) and the class while generating client proxy classes or abstract server classes from a Web Services Description Language (WSDL) document. The class is also used by the [Web Services Description Language Tool (Wsdl.exe)](https://msdn.microsoft.com/library/b9210348-8bc2-4367-8c91-d1a04b403e88) while generating classes from XML Schema Definition (XSD) documents. Instead of using this class directly, use Wsdl.exe or Xsd.exe. - - The class has methods to generate internal mappings to .NET types for elements defined in an XSD document or as parts in a WSDL document. The following list shows when the class is used by Wsdl.exe: - -- A WSDL document specifies literal use, where the content of SOAP message parameters and return values (or request and response documents) is literally specified with XML schema definitions. - -- A WSDL document specifies the .NET Framework's non-SOAP implementations of Web services via the HTTP-GET and HTTP-POST operations. - + class is used by the [Web Services Description Language Tool (Wsdl.exe)](https://msdn.microsoft.com/library/b9210348-8bc2-4367-8c91-d1a04b403e88) and the class while generating client proxy classes or abstract server classes from a Web Services Description Language (WSDL) document. The class is also used by the [Web Services Description Language Tool (Wsdl.exe)](https://msdn.microsoft.com/library/b9210348-8bc2-4367-8c91-d1a04b403e88) while generating classes from XML Schema Definition (XSD) documents. Instead of using this class directly, use Wsdl.exe or Xsd.exe. + + The class has methods to generate internal mappings to .NET types for elements defined in an XSD document or as parts in a WSDL document. The following list shows when the class is used by Wsdl.exe: + +- A WSDL document specifies literal use, where the content of SOAP message parameters and return values (or request and response documents) is literally specified with XML schema definitions. + +- A WSDL document specifies the .NET Framework's non-SOAP implementations of Web services via the HTTP-GET and HTTP-POST operations. + ]]> @@ -131,13 +131,13 @@ A collection of objects. Initializes a new instance of the class, taking a collection of objects representing the XML schemas used by SOAP literal messages defined in a WSDL document. - ). - - Instead of directly creating an instance of the class, use Wsdl.exe or Xsd.exe. - + ). + + Instead of directly creating an instance of the class, use Wsdl.exe or Xsd.exe. + ]]> @@ -197,13 +197,13 @@ A object that specifies a collection of classes being generated for bindings defined in a WSDL document. Initializes a new instance of the class, taking a collection of objects that represents the XML schemas used by SOAP literal messages, plus classes being generated for bindings defined in a Web Services Description Language (WSDL) document. - ). - - Instead of directly creating an instance of the class, use Wsdl.exe or Xsd.exe. - + ). + + Instead of directly creating an instance of the class, use Wsdl.exe or Xsd.exe. + ]]> @@ -229,9 +229,9 @@ netstandard - - - + + + A collection of objects. @@ -262,9 +262,9 @@ netstandard - - - + + + A collection of objects. @@ -272,13 +272,13 @@ A bitwise combination of the values that specifies the options to use when generating .NET Framework types for a Web service. Initializes a new instance of the class, taking a collection of objects that represents the XML schemas used by SOAP literal messages, plus classes being generated for bindings defined in a WSDL document, and a enumeration value. - ). - - Instead of directly creating an instance of the `XmlSchemaImporter` class, use Wsdl.exe or Xsd.exe. - + ). + + Instead of directly creating an instance of the `XmlSchemaImporter` class, use Wsdl.exe or Xsd.exe. + ]]> @@ -310,10 +310,10 @@ - - - - + + + + A collection of objects. @@ -376,13 +376,13 @@ Generates internal type mapping information for a single, (SOAP) literal element part defined in a WSDL document. An representing the .NET Framework type mapping for a single element part of a WSDL message definition. - method is used by the Wsdl.exe tool while generating client proxy classes or abstract server classes from a Web Services Description Language (WSDL) document. Instead of calling this method directly, use Wsdl.exe or Xsd.exe. - - The class is used only when a WSDL document specifies literal use. The method is used when a WSDL message has a single part element but the part has not been identified as a wrapper element. - + method is used by the Wsdl.exe tool while generating client proxy classes or abstract server classes from a Web Services Description Language (WSDL) document. Instead of calling this method directly, use Wsdl.exe or Xsd.exe. + + The class is used only when a WSDL document specifies literal use. The method is used when a WSDL message has a single part element but the part has not been identified as a wrapper element. + ]]> @@ -460,11 +460,11 @@ Generates internal type mapping information for an element defined in an XML schema document. An representing the.NET Framework type mapping information for an XML schema element. - method is used by the Xsd.exe tool to generate classes from an XML Schema Definition (XSD) document. Instead of calling this method directly, use Xsd.exe. - + method is used by the Xsd.exe tool to generate classes from an XML Schema Definition (XSD) document. Instead of calling this method directly, use Xsd.exe. + ]]> @@ -531,11 +531,11 @@ Generates internal type mapping information for an element defined in an XML schema document or as a part in a WSDL document. The .NET Framework type mapping information for an XML schema element. - method is used by the Xsd.exe tool to generate classes from an XML Schema Definition (XSD) document. It also is used by the Wsdl.exe tool while generating client proxy classes or abstract server classes from a Web Services Description Language (WSDL) document. Instead of calling this method directly, use Wsdl.exe or Xsd.exe. - + method is used by the Xsd.exe tool to generate classes from an XML Schema Definition (XSD) document. It also is used by the Wsdl.exe tool while generating client proxy classes or abstract server classes from a Web Services Description Language (WSDL) document. Instead of calling this method directly, use Wsdl.exe or Xsd.exe. + ]]> @@ -599,13 +599,13 @@ Generates internal type mapping information for a single element part of a literal-use SOAP message defined in a WSDL document. The .NET Framework type mapping for a WSDL message definition containing a single element part. - method of the class is used by the Wsdl.exe tool while generating client proxy classes or abstract server classes from a Web Services Description Language (WSDL) document. Instead of calling this method directly, use Wsdl.exe or Xsd.exe. - - The class is used only when a WSDL document specifies literal use. This overload is used when a WSDL message is wrapped within a single part element. - + method of the class is used by the Wsdl.exe tool while generating client proxy classes or abstract server classes from a Web Services Description Language (WSDL) document. Instead of calling this method directly, use Wsdl.exe or Xsd.exe. + + The class is used only when a WSDL document specifies literal use. This overload is used when a WSDL message is wrapped within a single part element. + ]]> @@ -663,15 +663,15 @@ Generates internal type mapping information for the element parts of a literal-use SOAP message defined in a WSDL document. An that represents the .NET Framework type mappings for the element parts of a WSDL message definition. - method is used by the Wsdl.exe tool while generating client proxy classes or abstract server classes from a Web Services Description Language (WSDL) document. Instead of calling this method directly, use Wsdl.exe or Xsd.exe. - - The class is used only when a WSDL document specifies literal use. The value of the `names` parameter contains the qualified names of the parts elements under a message definition in a WSDL document. - - This method does not account for the part elements' types. - + method is used by the Wsdl.exe tool while generating client proxy classes or abstract server classes from a Web Services Description Language (WSDL) document. Instead of calling this method directly, use Wsdl.exe or Xsd.exe. + + The class is used only when a WSDL document specifies literal use. The value of the `names` parameter contains the qualified names of the parts elements under a message definition in a WSDL document. + + This method does not account for the part elements' types. + ]]> @@ -800,15 +800,15 @@ Generates internal type mapping information for the element parts of a literal-use SOAP message defined in a WSDL document. The .NET Framework type mappings for the element parts of a WSDL message definition. - method is used by the Wsdl.exe tool while generating client proxy classes or abstract server classes from a Web Services Description Language (WSDL) document. Instead of calling this method directly, use Wsdl.exe or Xsd.exe. - - The class is used only when a WSDL document specifies literal use. The value of the `names` parameter contains the qualified names of the parts elements under a message definition in a WSDL document. - - This method does not account for the part elements' types. - + method is used by the Wsdl.exe tool while generating client proxy classes or abstract server classes from a Web Services Description Language (WSDL) document. Instead of calling this method directly, use Wsdl.exe or Xsd.exe. + + The class is used only when a WSDL document specifies literal use. The value of the `names` parameter contains the qualified names of the parts elements under a message definition in a WSDL document. + + This method does not account for the part elements' types. + ]]> @@ -1056,13 +1056,13 @@ Generates internal type mapping information for an element defined in an XML schema document. The .NET Framework type mapping information for an XML schema element. - method is used by the Xsd.exe tool while generating classes XML Schema Definition (XSD) document. Instead of calling this method directly, use Xsd.exe. - - This method does not account for the XML schema element's type. - + method is used by the Xsd.exe tool while generating classes XML Schema Definition (XSD) document. Instead of calling this method directly, use Xsd.exe. + + This method does not account for the XML schema element's type. + ]]> diff --git a/xml/System.Xml.Serialization/XmlSerializer.xml b/xml/System.Xml.Serialization/XmlSerializer.xml index c8f3e7050cf..a155bce4936 100644 --- a/xml/System.Xml.Serialization/XmlSerializer.xml +++ b/xml/System.Xml.Serialization/XmlSerializer.xml @@ -252,7 +252,7 @@ The following example contains two main classes: `PurchaseOrder` and `Test`. The - + An that maps one type to another. @@ -769,7 +769,7 @@ The following example contains two main classes: `PurchaseOrder` and `Test`. The - + [System.Runtime.CompilerServices.Nullable(1)] @@ -777,8 +777,8 @@ The following example contains two main classes: `PurchaseOrder` and `Test`. The - - + + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 2, 1 })] @@ -786,9 +786,9 @@ The following example contains two main classes: `PurchaseOrder` and `Test`. The - - - + + + The type of the object that this can serialize. @@ -830,13 +830,13 @@ The following example contains two main classes: `PurchaseOrder` and `Test`. The - - - - - - - + + + + + + + The type of the object that this can serialize. @@ -1241,7 +1241,7 @@ The following example contains two main classes: `PurchaseOrder` and `Test`. The System.Object - + The that contains the XML document to deserialize. @@ -1391,7 +1391,7 @@ The following example contains two main classes: `PurchaseOrder` and `Test`. The System.Object - + [System.Runtime.CompilerServices.Nullable(1)] @@ -1399,7 +1399,7 @@ The following example contains two main classes: `PurchaseOrder` and `Test`. The - + The that contains the XML document to deserialize. @@ -1480,8 +1480,8 @@ The following example contains two main classes: `PurchaseOrder` and `Test`. The System.Object - - + + The that contains the document to deserialize. @@ -1546,7 +1546,7 @@ The following example contains two main classes: `PurchaseOrder` and `Test`. The System.Object - + [System.Runtime.CompilerServices.Nullable(1)] @@ -1554,8 +1554,8 @@ The following example contains two main classes: `PurchaseOrder` and `Test`. The - - + + An instance of the class used to read the document. @@ -1633,7 +1633,7 @@ The following example contains two main classes: `PurchaseOrder` and `Test`. The System.Xml.Serialization.XmlSerializer[] - + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 2, 1 })] @@ -1681,8 +1681,8 @@ The following example contains two main classes: `PurchaseOrder` and `Test`. The System.Xml.Serialization.XmlSerializer[] - - + + An array of objects used to map one type to another. @@ -1741,7 +1741,7 @@ The following example contains two main classes: `PurchaseOrder` and `Test`. The System.Xml.Serialization.XmlSerializer[] - + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 2, 1 })] @@ -1749,7 +1749,7 @@ The following example contains two main classes: `PurchaseOrder` and `Test`. The - + An array of objects. @@ -1889,8 +1889,8 @@ The following example contains two main classes: `PurchaseOrder` and `Test`. The System.Reflection.Assembly - - + + A collection of types. @@ -1926,9 +1926,9 @@ The following example contains two main classes: `PurchaseOrder` and `Test`. The System.Reflection.Assembly - - - + + + An array of type that contains objects used to serialize and deserialize data. @@ -2002,7 +2002,7 @@ The following example contains two main classes: `PurchaseOrder` and `Test`. The System.String - + The you are deserializing. @@ -2058,8 +2058,8 @@ The following example contains two main classes: `PurchaseOrder` and `Test`. The System.String - - + + [System.Runtime.CompilerServices.Nullable(2)] @@ -2336,7 +2336,7 @@ The following example contains two main classes: `PurchaseOrder` and `Test`. The System.Void - + [System.Runtime.CompilerServices.Nullable(2)] @@ -2344,7 +2344,7 @@ The following example contains two main classes: `PurchaseOrder` and `Test`. The - + The to serialize. @@ -2812,7 +2812,7 @@ The following example contains two main classes: `PurchaseOrder` and `Test`. The System.Void - + [System.Runtime.CompilerServices.Nullable(1)] @@ -2820,9 +2820,9 @@ The following example contains two main classes: `PurchaseOrder` and `Test`. The - - - + + + The used to write the XML document. @@ -2903,7 +2903,7 @@ The following example contains two main classes: `PurchaseOrder` and `Test`. The System.Void - + [System.Runtime.CompilerServices.Nullable(1)] @@ -2911,10 +2911,10 @@ The following example contains two main classes: `PurchaseOrder` and `Test`. The - - - - + + + + The used to write the XML document. diff --git a/xml/System.Xml.Serialization/XmlSerializerFactory.xml b/xml/System.Xml.Serialization/XmlSerializerFactory.xml index c5a168f52f3..f9b5fe43439 100644 --- a/xml/System.Xml.Serialization/XmlSerializerFactory.xml +++ b/xml/System.Xml.Serialization/XmlSerializerFactory.xml @@ -331,11 +331,11 @@ Returns a derivation of the class that is used to serialize the specified type. If a property or field returns an array, the parameter specifies objects that can be inserted into the array. A derivation of the . - to create an instance of the class. - + to create an instance of the class. + ]]> @@ -398,11 +398,11 @@ Returns a derivation of the class that can serialize objects of the specified type into XML documents, and vice versa. Each object to be serialized can itself contain instances of classes, which this overload can override with other classes. A derivation of the . - to create an instance of the class. - + to create an instance of the class. + ]]> @@ -465,11 +465,11 @@ Returns a derivation of the class that can serialize objects of the specified type into XML documents, and vice versa. Specifies the object that represents the XML root element. A derivation of the . - to create an instance of the class. - + to create an instance of the class. + ]]> @@ -553,11 +553,11 @@ Returns a derivation of the class that can serialize objects of the specified type into XML document instances, and vice versa. Each object to be serialized can itself contain instances of classes, which this overload can override with other classes. This overload also specifies the default namespace for all the XML elements, and the class to use as the XML root element. A derivation of the . - to create an instance of the class. - + to create an instance of the class. + ]]> @@ -674,13 +674,13 @@ System.Xml.Serialization.XmlSerializer - - - - - - - + + + + + + + The of the object that this can serialize. @@ -693,11 +693,11 @@ Returns a derivation of the class that can serialize objects of the specified type into XML document instances, and vice versa. Each object to be serialized can itself contain instances of classes, which this overload can override with other classes. This overload also specifies the default namespace for all the XML elements, and the class to use as the XML root element. A derivation of the . - to create an instance of the class. - + to create an instance of the class. + ]]> diff --git a/xml/System.Xml.Xsl/XslCompiledTransform.xml b/xml/System.Xml.Xsl/XslCompiledTransform.xml index 12fe6d13640..b7abcba8d79 100644 --- a/xml/System.Xml.Xsl/XslCompiledTransform.xml +++ b/xml/System.Xml.Xsl/XslCompiledTransform.xml @@ -231,12 +231,12 @@ The sample uses the following two input files: System.CodeDom.Compiler.CompilerErrorCollection - - - - - - + + + + + + An positioned at the beginning of the style sheet to be compiled. diff --git a/xml/System.Xml.Xsl/XslTransform.xml b/xml/System.Xml.Xsl/XslTransform.xml index e6fbcdc1aec..63d734a2369 100644 --- a/xml/System.Xml.Xsl/XslTransform.xml +++ b/xml/System.Xml.Xsl/XslTransform.xml @@ -56,102 +56,102 @@ Transforms XML data using an Extensible Stylesheet Language for Transformations (XSLT) style sheet. - [!NOTE] -> The class is obsolete in the Microsoft .NET Framework version 2.0. The class is the new XSLT processor. For more information, see [Using the XslCompiledTransform Class](/dotnet/standard/data/xml/using-the-xslcompiledtransform-class) and [Migrating From the XslTransform Class](/dotnet/standard/data/xml/migrating-from-the-xsltransform-class). - - supports the XSLT 1.0 syntax. The XSLT style sheet must use the namespace `http://www.w3.org/1999/XSL/Transform`. - - Additional arguments can also be added to the style sheet using the class. This class contains input parameters for the style sheet and extension objects which can be called from the style sheet. - - To transform XML data: - -1. Create an object. - -2. Use the method to load the style sheet for the transformation. This method has several overloads and can load a style sheet using an , , , or a URL with the location of the file. - -3. Use the method to transform the XML data. This method has several overloads and can handle different types of input and output. You can also specify an containing additional arguments to use as input during the transformation. - - **Security Considerations** - - When creating an application that uses the class, you should be aware of the following items and their implications: - -- Extension objects are enabled by default. If an object containing extension objects is passed to the method, they are utilized. - -- XSLT style sheets can include references to other files and embedded script blocks. A malicious user can exploit this by supplying you with data or style sheets that when executed will cause your system to process until the computer runs low on resources. - -- XSLT applications that run in a mixed trust environment can result in style sheet spoofing. For example, a malicious user can load an object with a harmful style sheet and hand it off to another user who subsequently calls the method and executes the transformation. - - These security issues can be mitigated by not accepting objects, XSLT style sheets, or XML source data from untrusted sources. - - **Scripting Support** - - This class supports embedded scripting using the `msxsl:script` element. - - In version 1.1 of the .NET Framework, the evidence of the style sheet determines what permissions are given to embedded scripts. - -- If the style sheet was loaded from a Uniform Resource Identifier (URI), the URI is used to create the evidence. This evidence includes the URI along with its site and zone. - -- If the style sheet was loaded using another source, you can provide evidence by passing a object to the method. Otherwise, the script assembly has full trust. - - Semi-trusted callers: `UnmanagedCode` permission is required to compile the embedded script. `ControlEvidence` permission is required to provide to the method. A is thrown if the caller does not have the necessary permissions. See and for more information. - - The `msxsl:script` element has the following requirements: - -- The `msxsl:script` element belongs to the `urn:schemas-microsoft-com:xslt` namespace. The style sheet must include the namespace declaration `xmlns:msxsl=urn:schemas-microsoft-com:xslt`. - -- The `msxsl:script` element can include a `language` attribute that specifies the scripting language to use. The value of the `language` attribute must be one of the following: C#, CSharp, VB, VisualBasic, JScript, or JavaScript. Because the language name is not case-sensitive, JavaScript and javascript are both valid. If a `language` attribute is not specified, it defaults to JScript. - -- The `msxsl:script` element must include an `implements-prefix` attribute that contains the prefix representing the namespace associated with the script block. This namespace must be defined within the style sheet. A style sheet can include multiple script blocks which are grouped by namespace. You cannot have script blocks with multiple languages within the same namespace. Script blocks can call a function defined in another script block, provided the script blocks reside within the same namespace. The contents of a script block are parsed according to the rules and syntax of the scripting language (supplied by the `language` attribute). For example, if you had a C# script block, comments would be prefixed by the `//` characters. The comments must be valid XML content. - +> The class is obsolete in the Microsoft .NET Framework version 2.0. The class is the new XSLT processor. For more information, see [Using the XslCompiledTransform Class](/dotnet/standard/data/xml/using-the-xslcompiledtransform-class) and [Migrating From the XslTransform Class](/dotnet/standard/data/xml/migrating-from-the-xsltransform-class). + + supports the XSLT 1.0 syntax. The XSLT style sheet must use the namespace `http://www.w3.org/1999/XSL/Transform`. + + Additional arguments can also be added to the style sheet using the class. This class contains input parameters for the style sheet and extension objects which can be called from the style sheet. + + To transform XML data: + +1. Create an object. + +2. Use the method to load the style sheet for the transformation. This method has several overloads and can load a style sheet using an , , , or a URL with the location of the file. + +3. Use the method to transform the XML data. This method has several overloads and can handle different types of input and output. You can also specify an containing additional arguments to use as input during the transformation. + + **Security Considerations** + + When creating an application that uses the class, you should be aware of the following items and their implications: + +- Extension objects are enabled by default. If an object containing extension objects is passed to the method, they are utilized. + +- XSLT style sheets can include references to other files and embedded script blocks. A malicious user can exploit this by supplying you with data or style sheets that when executed will cause your system to process until the computer runs low on resources. + +- XSLT applications that run in a mixed trust environment can result in style sheet spoofing. For example, a malicious user can load an object with a harmful style sheet and hand it off to another user who subsequently calls the method and executes the transformation. + + These security issues can be mitigated by not accepting objects, XSLT style sheets, or XML source data from untrusted sources. + + **Scripting Support** + + This class supports embedded scripting using the `msxsl:script` element. + + In version 1.1 of the .NET Framework, the evidence of the style sheet determines what permissions are given to embedded scripts. + +- If the style sheet was loaded from a Uniform Resource Identifier (URI), the URI is used to create the evidence. This evidence includes the URI along with its site and zone. + +- If the style sheet was loaded using another source, you can provide evidence by passing a object to the method. Otherwise, the script assembly has full trust. + + Semi-trusted callers: `UnmanagedCode` permission is required to compile the embedded script. `ControlEvidence` permission is required to provide to the method. A is thrown if the caller does not have the necessary permissions. See and for more information. + + The `msxsl:script` element has the following requirements: + +- The `msxsl:script` element belongs to the `urn:schemas-microsoft-com:xslt` namespace. The style sheet must include the namespace declaration `xmlns:msxsl=urn:schemas-microsoft-com:xslt`. + +- The `msxsl:script` element can include a `language` attribute that specifies the scripting language to use. The value of the `language` attribute must be one of the following: C#, CSharp, VB, VisualBasic, JScript, or JavaScript. Because the language name is not case-sensitive, JavaScript and javascript are both valid. If a `language` attribute is not specified, it defaults to JScript. + +- The `msxsl:script` element must include an `implements-prefix` attribute that contains the prefix representing the namespace associated with the script block. This namespace must be defined within the style sheet. A style sheet can include multiple script blocks which are grouped by namespace. You cannot have script blocks with multiple languages within the same namespace. Script blocks can call a function defined in another script block, provided the script blocks reside within the same namespace. The contents of a script block are parsed according to the rules and syntax of the scripting language (supplied by the `language` attribute). For example, if you had a C# script block, comments would be prefixed by the `//` characters. The comments must be valid XML content. + > [!NOTE] > It is recommended that you wrap script blocks in a CDATA section. - - [!INCLUDE [xsltransform-script](~/includes/xsltransform-script.md)] - - Functions can be declared within the `msxsl:script` element. The following table shows the namespaces that are supported by default. - -|Supported Namespaces|Description| -|--------------------------|-----------------| -|`System`|System classes.| -|`System.Collection`|Collection classes.| -|`System.Text`|Text handling classes.| -|`System.Xml`|Core XML classes.| -|`System.Xml.Xsl`|XSLT classes.| -|`System.Xml.XPath`|XML Path Language (XPath) classes.| - - The supplied arguments and return values defined by the script functions must be one of the World Wide Web Consortium (W3C) types listed below. The following table details the mapping between the W3C types, either XPath or XSLT, and the corresponding .NET Framework classes. - -|W3C Type|Equivalent .NET class| -|--------------|---------------------------| -|String (XPath)|`System.String`| -|Boolean (XPath)|`System.Boolean`| -|Number (XPath)|`System.Double`| -|Result Tree Fragment (XSLT)|`System.Xml.XPath.XPathNavigator`| -|Node Set (XPath)|`System.Xml.XPath.XPathNodeIterator`| - - If the script function utilizes one of the following numeric types: Int16, UInt16, Int32, UInt32, Int64, UInt64, Single, or Decimal, these types are coerced to Double, which maps to the W3C XPath type number. - - An exception is thrown when a function is called that cannot convert the argument result to one of the required types. - + + [!INCLUDE [xsltransform-script](~/includes/xsltransform-script.md)] + + Functions can be declared within the `msxsl:script` element. The following table shows the namespaces that are supported by default. + +|Supported Namespaces|Description| +|--------------------------|-----------------| +|`System`|System classes.| +|`System.Collection`|Collection classes.| +|`System.Text`|Text handling classes.| +|`System.Xml`|Core XML classes.| +|`System.Xml.Xsl`|XSLT classes.| +|`System.Xml.XPath`|XML Path Language (XPath) classes.| + + The supplied arguments and return values defined by the script functions must be one of the World Wide Web Consortium (W3C) types listed below. The following table details the mapping between the W3C types, either XPath or XSLT, and the corresponding .NET Framework classes. + +|W3C Type|Equivalent .NET class| +|--------------|---------------------------| +|String (XPath)|`System.String`| +|Boolean (XPath)|`System.Boolean`| +|Number (XPath)|`System.Double`| +|Result Tree Fragment (XSLT)|`System.Xml.XPath.XPathNavigator`| +|Node Set (XPath)|`System.Xml.XPath.XPathNodeIterator`| + + If the script function utilizes one of the following numeric types: Int16, UInt16, Int32, UInt32, Int64, UInt64, Single, or Decimal, these types are coerced to Double, which maps to the W3C XPath type number. + + An exception is thrown when a function is called that cannot convert the argument result to one of the required types. + > [!NOTE] -> `msxsl:script` and `msxsl:node-list` are the only functions from the `urn:schemas-microsoft-com:xslt` namespace that are supported by the class. - - has the ability to utilize common language runtime (CLR) code as an extension mechanism. This is accomplished by passing an instance of a class to the class and calling its public methods within an XSLT style sheet. Methods that are defined with the `params` keyword, which allows an unspecified number of parameters to be passed, do not work correctly in this scenario. See [params](/dotnet/csharp/language-reference/keywords/params) for more details. - - For more information see [XSLT Transformations with the XslTransform Class](/dotnet/standard/data/xml/xslt-transformations-with-the-xsltransform-class). - - - -## Examples - The following example transforms the specified XML document and outputs the result to the console. - +> `msxsl:script` and `msxsl:node-list` are the only functions from the `urn:schemas-microsoft-com:xslt` namespace that are supported by the class. + + has the ability to utilize common language runtime (CLR) code as an extension mechanism. This is accomplished by passing an instance of a class to the class and calling its public methods within an XSLT style sheet. Methods that are defined with the `params` keyword, which allows an unspecified number of parameters to be passed, do not work correctly in this scenario. See [params](/dotnet/csharp/language-reference/keywords/params) for more details. + + For more information see [XSLT Transformations with the XslTransform Class](/dotnet/standard/data/xml/xslt-transformations-with-the-xsltransform-class). + + + +## Examples + The following example transforms the specified XML document and outputs the result to the console. + :::code language="csharp" source="~/snippets/csharp/System.Xml.Xsl/XslTransform/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/Classic WebData XslTransform Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/Classic WebData XslTransform Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -203,13 +203,13 @@ Loads the XSLT style sheet, including style sheets referenced in and elements. - [!NOTE] -> The class is obsolete in the .NET Framework version 2.0. The class is the new XSLT processor. For more information, see [Using the XslCompiledTransform Class](/dotnet/standard/data/xml/using-the-xslcompiledtransform-class) and [Migrating From the XslTransform Class](/dotnet/standard/data/xml/migrating-from-the-xsltransform-class). - +> The class is obsolete in the .NET Framework version 2.0. The class is the new XSLT processor. For more information, see [Using the XslCompiledTransform Class](/dotnet/standard/data/xml/using-the-xslcompiledtransform-class) and [Migrating From the XslTransform Class](/dotnet/standard/data/xml/migrating-from-the-xsltransform-class). + ]]> @@ -262,41 +262,41 @@ The URL that specifies the XSLT style sheet to load. Loads the XSLT style sheet specified by a URL. - [!NOTE] -> The class is obsolete in the .NET Framework version 2.0. The class is the new XSLT processor. For more information, see [Using the XslCompiledTransform Class](/dotnet/standard/data/xml/using-the-xslcompiledtransform-class) and [Migrating From the XslTransform Class](/dotnet/standard/data/xml/migrating-from-the-xsltransform-class). - - supports the XSLT 1.0 syntax. The XSLT style sheet must include the namespace declaration `xmlns:xsl="http://www.w3.org/1999/XSL/Transform"`. - - This method loads the XSLT style sheet, including any style sheets referenced in `xsl:include` and `xsl:import` elements. External resources are resolved using an with no user credentials. If the style sheet(s) are located on a network resource which requires authentication, use the overload that takes an as one of its arguments and specify an with the necessary credentials. - +> The class is obsolete in the .NET Framework version 2.0. The class is the new XSLT processor. For more information, see [Using the XslCompiledTransform Class](/dotnet/standard/data/xml/using-the-xslcompiledtransform-class) and [Migrating From the XslTransform Class](/dotnet/standard/data/xml/migrating-from-the-xsltransform-class). + + supports the XSLT 1.0 syntax. The XSLT style sheet must include the namespace declaration `xmlns:xsl="http://www.w3.org/1999/XSL/Transform"`. + + This method loads the XSLT style sheet, including any style sheets referenced in `xsl:include` and `xsl:import` elements. External resources are resolved using an with no user credentials. If the style sheet(s) are located on a network resource which requires authentication, use the overload that takes an as one of its arguments and specify an with the necessary credentials. + If the style sheet contains embedded scripting, the script is compiled to an assembly. The URI of the style sheet is used to create evidence, which is applied to the assembly. - + > [!NOTE] -> If the caller does not have `UnmanagedCode` permission, the embedded script is not compiled and a is thrown. See and for more information. - - - -## Examples - The following example transforms an XML document into an HTML document. It displays the ISBN, title, and price for each book in a table. - +> If the caller does not have `UnmanagedCode` permission, the embedded script is not compiled and a is thrown. See and for more information. + + + +## Examples + The following example transforms an XML document into an HTML document. It displays the ISBN, title, and price for each book in a table. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/Classic WebData XslTransform.Transform7 Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.Xsl/XslTransform/Load/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/Classic WebData XslTransform.Transform7 Example/VB/source.vb" id="Snippet1"::: - - The sample uses the following two input files. - - `books.xml` - - :::code language="xml" source="~/snippets/xml/VS_Snippets_Data/Classic WebData XslTransform.Transform7 Example/XML/books.xml" id="Snippet2"::: - - `output.xsl` - - :::code language="xml" source="~/snippets/xml/VS_Snippets_Data/Classic WebData XslTransform.Transform7 Example/XML/output.xsl" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/Classic WebData XslTransform.Transform7 Example/VB/source.vb" id="Snippet1"::: + + The sample uses the following two input files. + + `books.xml` + + :::code language="xml" source="~/snippets/xml/VS_Snippets_Data/Classic WebData XslTransform.Transform7 Example/XML/books.xml" id="Snippet2"::: + + `output.xsl` + + :::code language="xml" source="~/snippets/xml/VS_Snippets_Data/Classic WebData XslTransform.Transform7 Example/XML/output.xsl" id="Snippet3"::: + ]]> The loaded resource is not a valid style sheet. @@ -350,45 +350,45 @@ An object that contains the XSLT style sheet. Loads the XSLT style sheet contained in the . - [!NOTE] -> The class is obsolete in the .NET Framework version 2.0. The class is the new XSLT processor. For more information, see [Using the XslCompiledTransform Class](/dotnet/standard/data/xml/using-the-xslcompiledtransform-class) and [Migrating From the XslTransform Class](/dotnet/standard/data/xml/migrating-from-the-xsltransform-class). - - supports the XSLT 1.0 syntax. The XSLT style sheet must include the namespace declaration `xmlns:xsl= http://www.w3.org/1999/XSL/Transform`. - - This method loads the XSLT style sheet, including any style sheets referenced in `xsl:include` and `xsl:import` elements. External resources are resolved using an with no user credentials. If the style sheet(s) are located on a network resource which requires authentication, use the overload that takes an as one of its arguments and specify an with the necessary credentials. - - The style sheet loads from the current node of the through all its children. This enables you to use a portion of a document as the style sheet. After the method returns, the is positioned on the next node after the end of the style sheet. If the end of the document is reached, the is positioned at the end of file (EOF). - - If the style sheet contains entities, you should specify an that can resolve entities ( returns `true`). In this case, an can be used. - +> The class is obsolete in the .NET Framework version 2.0. The class is the new XSLT processor. For more information, see [Using the XslCompiledTransform Class](/dotnet/standard/data/xml/using-the-xslcompiledtransform-class) and [Migrating From the XslTransform Class](/dotnet/standard/data/xml/migrating-from-the-xsltransform-class). + + supports the XSLT 1.0 syntax. The XSLT style sheet must include the namespace declaration `xmlns:xsl= http://www.w3.org/1999/XSL/Transform`. + + This method loads the XSLT style sheet, including any style sheets referenced in `xsl:include` and `xsl:import` elements. External resources are resolved using an with no user credentials. If the style sheet(s) are located on a network resource which requires authentication, use the overload that takes an as one of its arguments and specify an with the necessary credentials. + + The style sheet loads from the current node of the through all its children. This enables you to use a portion of a document as the style sheet. After the method returns, the is positioned on the next node after the end of the style sheet. If the end of the document is reached, the is positioned at the end of file (EOF). + + If the style sheet contains entities, you should specify an that can resolve entities ( returns `true`). In this case, an can be used. + If the style sheet contains embedded scripting, the script is compiled to an assembly. The assembly has full trust. The recommended practice is to provide evidence using the method. - + > [!NOTE] -> If the caller does not have `UnmanagedCode` permission, the embedded script is not compiled and a is thrown. See and for more information. - - - -## Examples - The following example transforms an XML file sorting all the books by title. - +> If the caller does not have `UnmanagedCode` permission, the embedded script is not compiled and a is thrown. See and for more information. + + + +## Examples + The following example transforms an XML file sorting all the books by title. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/XslTransform.Load3/CPP/trans3.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.Xsl/XslTransform/Load/trans3.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XslTransform.Load3/VB/trans3.vb" id="Snippet1"::: - - The example uses the following data files as input. - - `books.xml` - - :::code language="xml" source="~/snippets/xml/VS_Snippets_Data/XslTransform.Load3/XML/books.xml" id="Snippet2"::: - - `titles.xsl` - - :::code language="xml" source="~/snippets/xml/VS_Snippets_Data/XslTransform.Load3/XML/titles.xsl" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XslTransform.Load3/VB/trans3.vb" id="Snippet1"::: + + The example uses the following data files as input. + + `books.xml` + + :::code language="xml" source="~/snippets/xml/VS_Snippets_Data/XslTransform.Load3/XML/books.xml" id="Snippet2"::: + + `titles.xsl` + + :::code language="xml" source="~/snippets/xml/VS_Snippets_Data/XslTransform.Load3/XML/titles.xsl" id="Snippet3"::: + ]]> The current node does not conform to a valid style sheet. @@ -442,22 +442,22 @@ An object implementing the interface. In the .NET Framework, this can be either an (typically an ), or an containing the XSLT style sheet. Loads the XSLT style sheet contained in the . - [!NOTE] -> The class is obsolete in the .NET Framework version 2.0. The class is the new XSLT processor. For more information, see [Using the XslCompiledTransform Class](/dotnet/standard/data/xml/using-the-xslcompiledtransform-class) and [Migrating From the XslTransform Class](/dotnet/standard/data/xml/migrating-from-the-xsltransform-class). - - supports the XSLT 1.0 syntax. The XSLT style sheet must include the namespace declaration `xmlns:xsl= http://www.w3.org/1999/XSL/Transform`. - - This method loads the XSLT style sheet, including any style sheets referenced in `xsl:include` and `xsl:import` elements. External resources are resolved using an with no user credentials. If the style sheet(s) are located on a network resource which requires authentication, use the overload that takes an as one of its arguments and specify an with the necessary credentials. - +> The class is obsolete in the .NET Framework version 2.0. The class is the new XSLT processor. For more information, see [Using the XslCompiledTransform Class](/dotnet/standard/data/xml/using-the-xslcompiledtransform-class) and [Migrating From the XslTransform Class](/dotnet/standard/data/xml/migrating-from-the-xsltransform-class). + + supports the XSLT 1.0 syntax. The XSLT style sheet must include the namespace declaration `xmlns:xsl= http://www.w3.org/1999/XSL/Transform`. + + This method loads the XSLT style sheet, including any style sheets referenced in `xsl:include` and `xsl:import` elements. External resources are resolved using an with no user credentials. If the style sheet(s) are located on a network resource which requires authentication, use the overload that takes an as one of its arguments and specify an with the necessary credentials. + If the style sheet contains embedded scripting, the script is compiled to an assembly. The assembly has full trust. The recommended practice is to provide evidence using the method. - + > [!NOTE] -> If the caller does not have `UnmanagedCode` permission, the embedded script is not compiled and a is thrown. See and for more information. - +> If the caller does not have `UnmanagedCode` permission, the embedded script is not compiled and a is thrown. See and for more information. + ]]> The loaded resource is not a valid style sheet. @@ -511,24 +511,24 @@ An object that contains the XSLT style sheet. Loads the XSLT style sheet contained in the . - [!NOTE] -> The class is obsolete in the .NET Framework version 2.0. The class is the new XSLT processor. For more information, see [Using the XslCompiledTransform Class](/dotnet/standard/data/xml/using-the-xslcompiledtransform-class) and [Migrating From the XslTransform Class](/dotnet/standard/data/xml/migrating-from-the-xsltransform-class). - - supports the XSLT 1.0 syntax. The XSLT style sheet must include the namespace declaration `xmlns:xsl= http://www.w3.org/1999/XSL/Transform`. - - This method loads the XSLT style sheet, including any style sheets referenced in `xsl:include` and `xsl:import` elements. External resources are resolved using an with no user credentials. If the style sheet(s) are located on a network resource which requires authentication, use the overload that takes an as one of its arguments and specify an with the necessary credentials. - - The style sheet is loaded from the current position of the . To use just a portion of the loaded document as the style sheet, navigate to the node corresponding to the beginning of the style sheet. After the method returns, the is positioned at the beginning of the style sheet (on the `xsl:style sheet` node). - +> The class is obsolete in the .NET Framework version 2.0. The class is the new XSLT processor. For more information, see [Using the XslCompiledTransform Class](/dotnet/standard/data/xml/using-the-xslcompiledtransform-class) and [Migrating From the XslTransform Class](/dotnet/standard/data/xml/migrating-from-the-xsltransform-class). + + supports the XSLT 1.0 syntax. The XSLT style sheet must include the namespace declaration `xmlns:xsl= http://www.w3.org/1999/XSL/Transform`. + + This method loads the XSLT style sheet, including any style sheets referenced in `xsl:include` and `xsl:import` elements. External resources are resolved using an with no user credentials. If the style sheet(s) are located on a network resource which requires authentication, use the overload that takes an as one of its arguments and specify an with the necessary credentials. + + The style sheet is loaded from the current position of the . To use just a portion of the loaded document as the style sheet, navigate to the node corresponding to the beginning of the style sheet. After the method returns, the is positioned at the beginning of the style sheet (on the `xsl:style sheet` node). + If the style sheet contains embedded scripting, the script is compiled to an assembly. The assembly has full trust. The recommended practice is to provide evidence using the method. - + > [!NOTE] -> If the caller does not have `UnmanagedCode` permission, the embedded script is not compiled and a is thrown. See and for more information. - +> If the caller does not have `UnmanagedCode` permission, the embedded script is not compiled and a is thrown. See and for more information. + ]]> The current node does not conform to a valid style sheet. @@ -590,49 +590,49 @@ The URL that specifies the XSLT style sheet to load. - The to use to load the style sheet and any style sheet(s) referenced in xsl:import and xsl:include elements. - - If this is , a default with no user credentials is used to open the style sheet. The default is not used to resolve any external resources in the style sheet, so xsl:import and xsl:include elements are not resolved. - + The to use to load the style sheet and any style sheet(s) referenced in xsl:import and xsl:include elements. + + If this is , a default with no user credentials is used to open the style sheet. The default is not used to resolve any external resources in the style sheet, so xsl:import and xsl:include elements are not resolved. + The is not cached after the method completes. Loads the XSLT style sheet specified by a URL. - [!NOTE] -> The class is obsolete in the .NET Framework version 2.0. The class is the new XSLT processor. For more information, see [Using the XslCompiledTransform Class](/dotnet/standard/data/xml/using-the-xslcompiledtransform-class) and [Migrating From the XslTransform Class](/dotnet/standard/data/xml/migrating-from-the-xsltransform-class). - - supports the XSLT 1.0 syntax. The XSLT style sheet must include the namespace declaration `xmlns:xsl= http://www.w3.org/1999/XSL/Transform`. - +> The class is obsolete in the .NET Framework version 2.0. The class is the new XSLT processor. For more information, see [Using the XslCompiledTransform Class](/dotnet/standard/data/xml/using-the-xslcompiledtransform-class) and [Migrating From the XslTransform Class](/dotnet/standard/data/xml/migrating-from-the-xsltransform-class). + + supports the XSLT 1.0 syntax. The XSLT style sheet must include the namespace declaration `xmlns:xsl= http://www.w3.org/1999/XSL/Transform`. + If the style sheet contains embedded scripting, the script is compiled to an assembly. The URI of the style sheet is used to create evidence, which is applied to the assembly. - + > [!NOTE] -> If the caller does not have `UnmanagedCode` permission, the embedded script is not compiled and a is thrown. See and for more information. - - - -## Examples - The following example transforms an XML document into an HTML document. The example loads an XSLT style sheet which contains an `xsl:include` element referencing another style sheet. An is passed to the method which sets the credentials necessary to access the network resource for the included style sheet. - +> If the caller does not have `UnmanagedCode` permission, the embedded script is not compiled and a is thrown. See and for more information. + + + +## Examples + The following example transforms an XML document into an HTML document. The example loads an XSLT style sheet which contains an `xsl:include` element referencing another style sheet. An is passed to the method which sets the credentials necessary to access the network resource for the included style sheet. + :::code language="csharp" source="~/snippets/csharp/System.Xml.Xsl/XslTransform/Load/trans2.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XslTransform.Load2/VB/trans2.vb" id="Snippet1"::: - - The example uses the following data files as input. - - `books.xml` - - :::code language="xml" source="~/snippets/xml/VS_Snippets_Data/XslTransform.Load2/XML/books.xml" id="Snippet2"::: - - `sort.xsl` - - :::code language="xml" source="~/snippets/xml/VS_Snippets_Data/XslTransform.Load2/XML/sort.xsl" id="Snippet3"::: - - `includefile.xsl` - - :::code language="xml" source="~/snippets/xml/VS_Snippets_Data/XslTransform.Load2/XML/includefile.xsl" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XslTransform.Load2/VB/trans2.vb" id="Snippet1"::: + + The example uses the following data files as input. + + `books.xml` + + :::code language="xml" source="~/snippets/xml/VS_Snippets_Data/XslTransform.Load2/XML/books.xml" id="Snippet2"::: + + `sort.xsl` + + :::code language="xml" source="~/snippets/xml/VS_Snippets_Data/XslTransform.Load2/XML/sort.xsl" id="Snippet3"::: + + `includefile.xsl` + + :::code language="xml" source="~/snippets/xml/VS_Snippets_Data/XslTransform.Load2/XML/includefile.xsl" id="Snippet4"::: + ]]> The loaded resource is not a valid style sheet. @@ -697,31 +697,31 @@ An object that contains the XSLT style sheet. - The used to load any style sheets referenced in xsl:import and xsl:include elements. If this is , external resources are not resolved. - + The used to load any style sheets referenced in xsl:import and xsl:include elements. If this is , external resources are not resolved. + The is not cached after the method completes. Loads the XSLT style sheet contained in the . - [!NOTE] -> The class is obsolete in the .NET Framework version 2.0. The class is the new XSLT processor. For more information, see [Using the XslCompiledTransform Class](/dotnet/standard/data/xml/using-the-xslcompiledtransform-class) and [Migrating From the XslTransform Class](/dotnet/standard/data/xml/migrating-from-the-xsltransform-class). - - supports the XSLT 1.0 syntax. The XSLT style sheet must include the namespace declaration `xmlns:xsl= http://www.w3.org/1999/XSL/Transform`. - - This method loads the XSLT style sheet, including any style sheets referenced in `xsl:include` and `xsl:import` elements. The style sheet loads from the current node of the through all its children. This enables you to use a portion of a document as the style sheet. - - After the method returns, the is positioned on the next node after the end of the style sheet. If the end of the document is reached, the is positioned at the end of file (EOF). - - If the style sheet contains entities, you should specify an that can resolve entities ( returns `true`). In this case, an can be used. - +> The class is obsolete in the .NET Framework version 2.0. The class is the new XSLT processor. For more information, see [Using the XslCompiledTransform Class](/dotnet/standard/data/xml/using-the-xslcompiledtransform-class) and [Migrating From the XslTransform Class](/dotnet/standard/data/xml/migrating-from-the-xsltransform-class). + + supports the XSLT 1.0 syntax. The XSLT style sheet must include the namespace declaration `xmlns:xsl= http://www.w3.org/1999/XSL/Transform`. + + This method loads the XSLT style sheet, including any style sheets referenced in `xsl:include` and `xsl:import` elements. The style sheet loads from the current node of the through all its children. This enables you to use a portion of a document as the style sheet. + + After the method returns, the is positioned on the next node after the end of the style sheet. If the end of the document is reached, the is positioned at the end of file (EOF). + + If the style sheet contains entities, you should specify an that can resolve entities ( returns `true`). In this case, an can be used. + If the style sheet contains embedded scripting, the script is compiled to an assembly. The assembly has full trust. The recommended practice is to provide evidence using the method. - + > [!NOTE] -> If the caller does not have `UnmanagedCode` permission, the embedded script is not compiled and a is thrown. See and for more information. - +> If the caller does not have `UnmanagedCode` permission, the embedded script is not compiled and a is thrown. See and for more information. + ]]> The current node does not conform to a valid style sheet. @@ -785,25 +785,25 @@ An object implementing the interface. In the .NET Framework, this can be either an (typically an ), or an containing the XSLT style sheet. - The used to load any style sheets referenced in xsl:import and xsl:include elements. If this is , external resources are not resolved. - + The used to load any style sheets referenced in xsl:import and xsl:include elements. If this is , external resources are not resolved. + The is not cached after the method completes. Loads the XSLT style sheet contained in the . - [!NOTE] -> The class is obsolete in the .NET Framework version 2.0. The class is the new XSLT processor. For more information, see [Using the XslCompiledTransform Class](/dotnet/standard/data/xml/using-the-xslcompiledtransform-class) and [Migrating From the XslTransform Class](/dotnet/standard/data/xml/migrating-from-the-xsltransform-class). - - supports the XSLT 1.0 syntax. The XSLT style sheet must include the namespace declaration `xmlns:xsl= http://www.w3.org/1999/XSL/Transform`. - +> The class is obsolete in the .NET Framework version 2.0. The class is the new XSLT processor. For more information, see [Using the XslCompiledTransform Class](/dotnet/standard/data/xml/using-the-xslcompiledtransform-class) and [Migrating From the XslTransform Class](/dotnet/standard/data/xml/migrating-from-the-xsltransform-class). + + supports the XSLT 1.0 syntax. The XSLT style sheet must include the namespace declaration `xmlns:xsl= http://www.w3.org/1999/XSL/Transform`. + If the style sheet contains embedded scripting, the script is compiled to an assembly. The assembly has full trust. The recommended practice is to provide evidence using the method. - + > [!NOTE] -> If the caller does not have `UnmanagedCode` permission, the embedded script is not compiled and a is thrown. See and for more information. - +> If the caller does not have `UnmanagedCode` permission, the embedded script is not compiled and a is thrown. See and for more information. + ]]> The loaded resource is not a valid style sheet. @@ -867,27 +867,27 @@ An object that contains the XSLT style sheet. - The used to load any style sheets referenced in xsl:import and xsl:include elements. If this is , external resources are not resolved. - + The used to load any style sheets referenced in xsl:import and xsl:include elements. If this is , external resources are not resolved. + The is not cached after the method completes. Loads the XSLT style sheet contained in the . - [!NOTE] -> The class is obsolete in the .NET Framework version 2.0. The class is the new XSLT processor. For more information, see [Using the XslCompiledTransform Class](/dotnet/standard/data/xml/using-the-xslcompiledtransform-class) and [Migrating From the XslTransform Class](/dotnet/standard/data/xml/migrating-from-the-xsltransform-class). - - supports the XSLT 1.0 syntax. The XSLT style sheet must include the namespace declaration `xmlns:xsl= http://www.w3.org/1999/XSL/Transform`. - - The style sheet is loaded from the current position of the . To use a portion of the loaded document as the style sheet, navigate to the node corresponding to the beginning of the style sheet. After the method returns, the is positioned at the beginning of the style sheet (on the `xsl:style sheet` node). - +> The class is obsolete in the .NET Framework version 2.0. The class is the new XSLT processor. For more information, see [Using the XslCompiledTransform Class](/dotnet/standard/data/xml/using-the-xslcompiledtransform-class) and [Migrating From the XslTransform Class](/dotnet/standard/data/xml/migrating-from-the-xsltransform-class). + + supports the XSLT 1.0 syntax. The XSLT style sheet must include the namespace declaration `xmlns:xsl= http://www.w3.org/1999/XSL/Transform`. + + The style sheet is loaded from the current position of the . To use a portion of the loaded document as the style sheet, navigate to the node corresponding to the beginning of the style sheet. After the method returns, the is positioned at the beginning of the style sheet (on the `xsl:style sheet` node). + If the style sheet contains embedded scripting, the script is compiled to an assembly. The assembly has full trust. The recommended practice is to provide evidence using the . - + > [!NOTE] -> If the caller does not have `UnmanagedCode` permission, the embedded script is not compiled and a is thrown. See and for more information. - +> If the caller does not have `UnmanagedCode` permission, the embedded script is not compiled and a is thrown. See and for more information. + ]]> The current node does not conform to a valid style sheet. @@ -921,58 +921,58 @@ System.Void - - - + + + An object containing the style sheet to load. - The used to load any style sheets referenced in xsl:import and xsl:include elements. If this is , external resources are not resolved. - + The used to load any style sheets referenced in xsl:import and xsl:include elements. If this is , external resources are not resolved. + The is not cached after the method completes. - The set on the assembly generated for the script block in the XSLT style sheet. - - If this is , script blocks are not processed, the XSLT document() function is not supported, and privileged extension objects are disallowed. - + The set on the assembly generated for the script block in the XSLT style sheet. + + If this is , script blocks are not processed, the XSLT document() function is not supported, and privileged extension objects are disallowed. + The caller must have permission in order to supply evidence for the script assembly. Semi-trusted callers can set this parameter to . Loads the XSLT style sheet contained in the . This method allows you to limit the permissions of the style sheet by specifying evidence. - [!NOTE] -> The class is obsolete in the .NET Framework version 2.0. The class is the new XSLT processor. For more information, see [Using the XslCompiledTransform Class](/dotnet/standard/data/xml/using-the-xslcompiledtransform-class) and [Migrating From the XslTransform Class](/dotnet/standard/data/xml/migrating-from-the-xsltransform-class). - - supports the XSLT 1.0 syntax. The XSLT style sheet must include the namespace declaration `xmlns:xsl= http://www.w3.org/1999/XSL/Transform`. - - This method loads the XSLT style sheet, including any style sheets referenced in `xsl:include` and `xsl:import` elements. The style sheet loads from the current node of the through all its children. This enables you to use a portion of a document as the style sheet. - - After the method returns, the is positioned on the next node after the end of the style sheet. If the end of the document is reached, the is positioned at the end of file (EOF). - +> The class is obsolete in the .NET Framework version 2.0. The class is the new XSLT processor. For more information, see [Using the XslCompiledTransform Class](/dotnet/standard/data/xml/using-the-xslcompiledtransform-class) and [Migrating From the XslTransform Class](/dotnet/standard/data/xml/migrating-from-the-xsltransform-class). + + supports the XSLT 1.0 syntax. The XSLT style sheet must include the namespace declaration `xmlns:xsl= http://www.w3.org/1999/XSL/Transform`. + + This method loads the XSLT style sheet, including any style sheets referenced in `xsl:include` and `xsl:import` elements. The style sheet loads from the current node of the through all its children. This enables you to use a portion of a document as the style sheet. + + After the method returns, the is positioned on the next node after the end of the style sheet. If the end of the document is reached, the is positioned at the end of file (EOF). + If the style sheet contains entities, you should specify an that can resolve entities ( returns `true`). In this case, an can be used. - There are different ways to provide evidence. The following table describes what type of evidence to provide for common user scenarios. - -|Scenario|Type of evidence to provide| -|--------------|---------------------------------| -|The XSLT style sheet is self-contained or comes from a code base that you trust.|Use the evidence from your assembly.

`XsltTransform xslt = new XslTransform(); 
xslt.Load(xslReader, resolver, this.GetType().Assembly.Evidence);`
| -|The XSLT style sheet comes from an outside source. The origin of the source is known, and there is a verifiable URL.|Create evidence using the URL.

`XsltTransform xslt = new XslTransform();
 Evidence evidence = XmlSecureResolver.CreateEvidenceForUrl(stylesheetURL); 
xslt.Load(xslReader,resolver,evidence);`
| -|The XSLT style sheet comes from an outside source. The origin of the source is not known.|Set evidence to `null`. Script blocks are not processed, the XSLT `document()` function is not supported, and privileged extension objects are disallowed.

Additionally, you can also set the `resolver` parameter to `null`. This ensures that `xsl:import` and `xsl:include` elements are not processed.| + There are different ways to provide evidence. The following table describes what type of evidence to provide for common user scenarios. + +|Scenario|Type of evidence to provide| +|--------------|---------------------------------| +|The XSLT style sheet is self-contained or comes from a code base that you trust.|Use the evidence from your assembly.

`XsltTransform xslt = new XslTransform(); 
xslt.Load(xslReader, resolver, this.GetType().Assembly.Evidence);`
| +|The XSLT style sheet comes from an outside source. The origin of the source is known, and there is a verifiable URL.|Create evidence using the URL.

`XsltTransform xslt = new XslTransform();
 Evidence evidence = XmlSecureResolver.CreateEvidenceForUrl(stylesheetURL); 
xslt.Load(xslReader,resolver,evidence);`
| +|The XSLT style sheet comes from an outside source. The origin of the source is not known.|Set evidence to `null`. Script blocks are not processed, the XSLT `document()` function is not supported, and privileged extension objects are disallowed.

Additionally, you can also set the `resolver` parameter to `null`. This ensures that `xsl:import` and `xsl:include` elements are not processed.| |The XSLT style sheet comes from an outside source. The origin of the source is not known, but you require script support.|Request evidence from the caller. The API of the caller must provide a way to provide evidence, typically the class.| -## Examples - The following example performs an XSLT transformation where `xsltReader` is an containing a style sheet and `secureURL` is a trusted URL that can be used to create . The method is used to create which is applied to the style sheet. - +## Examples + The following example performs an XSLT transformation where `xsltReader` is an containing a style sheet and `secureURL` is a trusted URL that can be used to create . The method is used to create which is applied to the style sheet. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/XslTransform.Load4/CPP/trans_ev.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.Xsl/XslTransform/Load/trans_ev.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XslTransform.Load4/VB/trans_ev.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XslTransform.Load4/VB/trans_ev.vb" id="Snippet1"::: + ]]>
The current node does not conform to a valid style sheet. - The referenced style sheet requires functionality that is not allowed by the evidence provided. - + The referenced style sheet requires functionality that is not allowed by the evidence provided. + The caller tries to supply evidence and does not have permission. @@ -1006,45 +1006,45 @@ System.Void - - - + + + An object implementing the interface. In the .NET Framework, this can be either an (typically an ), or an containing the XSLT style sheet. - The used to load any style sheets referenced in xsl:import and xsl:include elements. If this is , external resources are not resolved. - + The used to load any style sheets referenced in xsl:import and xsl:include elements. If this is , external resources are not resolved. + The is not cached after the method completes. - The set on the assembly generated for the script block in the XSLT style sheet. - - If this is , script blocks are not processed, the XSLT document() function is not supported, and privileged extension objects are disallowed. - + The set on the assembly generated for the script block in the XSLT style sheet. + + If this is , script blocks are not processed, the XSLT document() function is not supported, and privileged extension objects are disallowed. + The caller must have permission in order to supply evidence for the script assembly. Semi-trusted callers can set this parameter to . Loads the XSLT style sheet contained in the . This method allows you to limit the permissions of the style sheet by specifying evidence. - [!NOTE] -> The class is obsolete in .NET Framework version 2.0. The class is the new XSLT processor. For more information, see [Using the XslCompiledTransform Class](/dotnet/standard/data/xml/using-the-xslcompiledtransform-class) and [Migrating From the XslTransform Class](/dotnet/standard/data/xml/migrating-from-the-xsltransform-class). - +> The class is obsolete in .NET Framework version 2.0. The class is the new XSLT processor. For more information, see [Using the XslCompiledTransform Class](/dotnet/standard/data/xml/using-the-xslcompiledtransform-class) and [Migrating From the XslTransform Class](/dotnet/standard/data/xml/migrating-from-the-xsltransform-class). + supports the XSLT 1.0 syntax. The XSLT style sheet must include the namespace declaration `xmlns:xsl= http://www.w3.org/1999/XSL/Transform`. - There are different ways to provide evidence. The following table describes what type of evidence to provide for common user scenarios. - -|Scenario|Type of evidence to provide| -|--------------|---------------------------------| -|The XSLT style sheet is self-contained or comes from a code base that you trust.|Use the evidence from your assembly.

`XsltTransform xslt = new XslTransform(); 
xslt.Load(style sheet, resolver, this.GetType().Assembly.Evidence);`
| -|The XSLT style sheet comes from an outside source. The origin of the source is known, and there is a verifiable URL.|Create evidence using the URL.

`XsltTransform xslt = new XslTransform(); 
Evidence evidence = XmlSecureResolver.CreateEvidenceForUrl(style sheetURL); 
xslt.Load(style sheet,resolver,evidence);`
| -|The XSLT style sheet comes from an outside source. The origin of the source is not known.|Set evidence to `null`. Script blocks are not processed, the XSLT `document()` function is not supported, and privileged extension objects are disallowed.

Additionally, you can also set the `resolver` parameter to `null`. This ensures that `xsl:import` and `xsl:include` elements are not processed.| -|The XSLT style sheet comes from an outside source. The origin of the source is not known, but you require script support.|Request evidence from the caller. The API of the caller must provide a way to provide evidence, typically the class.| - + There are different ways to provide evidence. The following table describes what type of evidence to provide for common user scenarios. + +|Scenario|Type of evidence to provide| +|--------------|---------------------------------| +|The XSLT style sheet is self-contained or comes from a code base that you trust.|Use the evidence from your assembly.

`XsltTransform xslt = new XslTransform(); 
xslt.Load(style sheet, resolver, this.GetType().Assembly.Evidence);`
| +|The XSLT style sheet comes from an outside source. The origin of the source is known, and there is a verifiable URL.|Create evidence using the URL.

`XsltTransform xslt = new XslTransform(); 
Evidence evidence = XmlSecureResolver.CreateEvidenceForUrl(style sheetURL); 
xslt.Load(style sheet,resolver,evidence);`
| +|The XSLT style sheet comes from an outside source. The origin of the source is not known.|Set evidence to `null`. Script blocks are not processed, the XSLT `document()` function is not supported, and privileged extension objects are disallowed.

Additionally, you can also set the `resolver` parameter to `null`. This ensures that `xsl:import` and `xsl:include` elements are not processed.| +|The XSLT style sheet comes from an outside source. The origin of the source is not known, but you require script support.|Request evidence from the caller. The API of the caller must provide a way to provide evidence, typically the class.| + ]]>
The loaded resource is not a valid style sheet. - The referenced style sheet requires functionality that is not allowed by the evidence provided. - + The referenced style sheet requires functionality that is not allowed by the evidence provided. + The caller tries to supply evidence and does not have permission. @@ -1078,57 +1078,57 @@ System.Void - - - + + + An object containing the style sheet to load. - The used to load any style sheets referenced in xsl:import and xsl:include elements. If this is , external resources are not resolved. - + The used to load any style sheets referenced in xsl:import and xsl:include elements. If this is , external resources are not resolved. + The is not cached after the method completes. - The set on the assembly generated for the script block in the XSLT style sheet. - - If this is , script blocks are not processed, the XSLT document() function is not supported, and privileged extension objects are disallowed. - + The set on the assembly generated for the script block in the XSLT style sheet. + + If this is , script blocks are not processed, the XSLT document() function is not supported, and privileged extension objects are disallowed. + The caller must have permission in order to supply evidence for the script assembly. Semi-trusted callers can set this parameter to . Loads the XSLT style sheet contained in the . This method allows you to limit the permissions of the style sheet by specifying evidence. - [!NOTE] -> The class is obsolete in the .NET Framework version 2.0. The class is the new XSLT processor. For more information, see [Using the XslCompiledTransform Class](/dotnet/standard/data/xml/using-the-xslcompiledtransform-class) and [Migrating From the XslTransform Class](/dotnet/standard/data/xml/migrating-from-the-xsltransform-class). - - supports the XSLT 1.0 syntax. The XSLT style sheet must include the namespace declaration `xmlns:xsl= http://www.w3.org/1999/XSL/Transform`. - - The style sheet is loaded from the current position of the . To use a portion of the loaded document as the style sheet, navigate to the node corresponding to the beginning of the style sheet. After the method returns, the is positioned at the beginning of the style sheet (on the `xsl:style sheet` node). - - - - There are different ways to provide evidence. The following table describes what type of evidence to provide for common user scenarios. - -|Scenario|Type of evidence to provide| -|--------------|---------------------------------| -|The XSLT style sheet is self-contained or comes from a code base that you trust.|Use the evidence from your assembly.

`XsltTransform xslt = new XslTransform(); 
xslt.Load(xslNav, resolver, this.GetType().Assembly.Evidence);`
| -|The XSLT style sheet comes from an outside source. The origin of the source is known, and there is a verifiable URL.|Create evidence using the URL.

`XsltTransform xslt = new XslTransform(); 
Evidence evidence = XmlSecureResolver.CreateEvidenceForUrl(style sheetURL); 
xslt.Load(xslNav,resolver,evidence);`
| -|The XSLT style sheet comes from an outside source. The origin of the source is not known.|Set evidence to `null`. Script blocks are not processed, the XSLT `document()` function is not supported, and privileged extension objects are disallowed.

Additionally, you can also set the `resolver` parameter to `null`. This ensures that `xsl:import` and `xsl:include` elements are not processed.| -|The XSLT style sheet comes from an outside source. The origin of the source is not known, but you require script support.|Request evidence from the caller. The API of the caller must provide a way to provide evidence, typically the `Evidence` class.| - - - -## Examples - The following example performs an XSLT transformation using a style sheet from an outside source. Because the style sheet comes from an untrusted source, the `resolver` and `evidence` parameters are set to `null`. - +> The class is obsolete in the .NET Framework version 2.0. The class is the new XSLT processor. For more information, see [Using the XslCompiledTransform Class](/dotnet/standard/data/xml/using-the-xslcompiledtransform-class) and [Migrating From the XslTransform Class](/dotnet/standard/data/xml/migrating-from-the-xsltransform-class). + + supports the XSLT 1.0 syntax. The XSLT style sheet must include the namespace declaration `xmlns:xsl= http://www.w3.org/1999/XSL/Transform`. + + The style sheet is loaded from the current position of the . To use a portion of the loaded document as the style sheet, navigate to the node corresponding to the beginning of the style sheet. After the method returns, the is positioned at the beginning of the style sheet (on the `xsl:style sheet` node). + + + + There are different ways to provide evidence. The following table describes what type of evidence to provide for common user scenarios. + +|Scenario|Type of evidence to provide| +|--------------|---------------------------------| +|The XSLT style sheet is self-contained or comes from a code base that you trust.|Use the evidence from your assembly.

`XsltTransform xslt = new XslTransform(); 
xslt.Load(xslNav, resolver, this.GetType().Assembly.Evidence);`
| +|The XSLT style sheet comes from an outside source. The origin of the source is known, and there is a verifiable URL.|Create evidence using the URL.

`XsltTransform xslt = new XslTransform(); 
Evidence evidence = XmlSecureResolver.CreateEvidenceForUrl(style sheetURL); 
xslt.Load(xslNav,resolver,evidence);`
| +|The XSLT style sheet comes from an outside source. The origin of the source is not known.|Set evidence to `null`. Script blocks are not processed, the XSLT `document()` function is not supported, and privileged extension objects are disallowed.

Additionally, you can also set the `resolver` parameter to `null`. This ensures that `xsl:import` and `xsl:include` elements are not processed.| +|The XSLT style sheet comes from an outside source. The origin of the source is not known, but you require script support.|Request evidence from the caller. The API of the caller must provide a way to provide evidence, typically the `Evidence` class.| + + + +## Examples + The following example performs an XSLT transformation using a style sheet from an outside source. Because the style sheet comes from an untrusted source, the `resolver` and `evidence` parameters are set to `null`. + :::code language="csharp" source="~/snippets/csharp/System.Xml.Xsl/XslTransform/Load/trans_noev.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XslTransform.Load5/VB/trans_noev.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XslTransform.Load5/VB/trans_noev.vb" id="Snippet1"::: + ]]>
The current node does not conform to a valid style sheet. - The referenced style sheet requires functionality that is not allowed by the evidence provided. - + The referenced style sheet requires functionality that is not allowed by the evidence provided. + The caller tries to supply evidence and does not have permission. @@ -1147,13 +1147,13 @@ Transforms the XML data using the loaded XSLT style sheet. - [!NOTE] -> The class is obsolete in the .NET Framework version 2.0. The class is the new XSLT processor. For more information, see [Using the XslCompiledTransform Class](/dotnet/standard/data/xml/using-the-xslcompiledtransform-class) and [Migrating From the XslTransform Class](/dotnet/standard/data/xml/migrating-from-the-xsltransform-class). - +> The class is obsolete in the .NET Framework version 2.0. The class is the new XSLT processor. For more information, see [Using the XslCompiledTransform Class](/dotnet/standard/data/xml/using-the-xslcompiledtransform-class) and [Migrating From the XslTransform Class](/dotnet/standard/data/xml/migrating-from-the-xsltransform-class). + ]]> @@ -1207,37 +1207,37 @@ The URL of the output file. Transforms the XML data in the input file and outputs the result to an output file. - [!NOTE] -> The class is obsolete in the .NET Framework version 2.0. The class is the new XSLT processor. For more information, see [Using the XslCompiledTransform Class](/dotnet/standard/data/xml/using-the-xslcompiledtransform-class) and [Migrating From the XslTransform Class](/dotnet/standard/data/xml/migrating-from-the-xsltransform-class). - - supports the XSLT 1.0 syntax. The XSLT style sheet must include the namespace declaration `xmlns:xsl= http://www.w3.org/1999/XSL/Transform`. - +> The class is obsolete in the .NET Framework version 2.0. The class is the new XSLT processor. For more information, see [Using the XslCompiledTransform Class](/dotnet/standard/data/xml/using-the-xslcompiledtransform-class) and [Migrating From the XslTransform Class](/dotnet/standard/data/xml/migrating-from-the-xsltransform-class). + + supports the XSLT 1.0 syntax. The XSLT style sheet must include the namespace declaration `xmlns:xsl= http://www.w3.org/1999/XSL/Transform`. + > [!NOTE] -> This method is obsolete in version 1.1 of the .NET Framework. The setting of the property determines how the XSLT `document()` function is resolved. The recommended practice is to use the method which takes an object as one of its arguments. - - - -## Examples - The following example transforms the `books.xml` file using the `output.xsl` style sheet and outputs the results to the `books.html` file. - +> This method is obsolete in version 1.1 of the .NET Framework. The setting of the property determines how the XSLT `document()` function is resolved. The recommended practice is to use the method which takes an object as one of its arguments. + + + +## Examples + The following example transforms the `books.xml` file using the `output.xsl` style sheet and outputs the results to the `books.html` file. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/xsltransform.transform3/CPP/trans_snip2.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.Xsl/XslTransform/Transform/trans_snip2.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/xsltransform.transform3/VB/trans_snip2.vb" id="Snippet1"::: - - The sample uses the following two input files: - - `books.xml` - - :::code language="xml" source="~/snippets/xml/VS_Snippets_Data/Classic WebData XslTransform.Transform7 Example/XML/books.xml" id="Snippet2"::: - - `output.xsl` - - :::code language="xml" source="~/snippets/xml/VS_Snippets_Data/Classic WebData XslTransform.Transform7 Example/XML/output.xsl" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/xsltransform.transform3/VB/trans_snip2.vb" id="Snippet1"::: + + The sample uses the following two input files: + + `books.xml` + + :::code language="xml" source="~/snippets/xml/VS_Snippets_Data/Classic WebData XslTransform.Transform7 Example/XML/books.xml" id="Snippet2"::: + + `output.xsl` + + :::code language="xml" source="~/snippets/xml/VS_Snippets_Data/Classic WebData XslTransform.Transform7 Example/XML/output.xsl" id="Snippet3"::: + ]]> Implementation of Discretionary Behaviors in the XslTransform Class @@ -1302,72 +1302,72 @@ Transforms the XML data in the using the specified and outputs the result to an . An containing the results of the transformation. - [!NOTE] -> The class is obsolete in the .NET Framework version 2.0. The class is the new XSLT processor. For more information, see [Using the XslCompiledTransform Class](/dotnet/standard/data/xml/using-the-xslcompiledtransform-class) and [Migrating From the XslTransform Class](/dotnet/standard/data/xml/migrating-from-the-xsltransform-class). - - supports the XSLT 1.0 syntax. The XSLT style sheet must include the namespace declaration `xmlns:xsl= http://www.w3.org/1999/XSL/Transform`. - +> The class is obsolete in the .NET Framework version 2.0. The class is the new XSLT processor. For more information, see [Using the XslCompiledTransform Class](/dotnet/standard/data/xml/using-the-xslcompiledtransform-class) and [Migrating From the XslTransform Class](/dotnet/standard/data/xml/migrating-from-the-xsltransform-class). + + supports the XSLT 1.0 syntax. The XSLT style sheet must include the namespace declaration `xmlns:xsl= http://www.w3.org/1999/XSL/Transform`. + > [!NOTE] -> This method is now obsolete. The setting of the property determines how the XSLT `document()` function is resolved. The recommended practice is to use the method which takes an object as one of its arguments. - - The `args` are matched with the `xsl:param` elements defined in the style sheet. The `xsl:output` element is not supported when outputting to an (the `xsl:output` element is ignored). See [Outputs from an XslTransform](/dotnet/standard/data/xml/outputs-from-an-xsltransform) for more information. - - This method enables you to do an asynchronous transformation of the source document. - - Transformations apply to the document as a whole. In other words, if you pass in a node other than the document root node, this does not prevent the transformation process from accessing all nodes in the loaded document. To transform a node fragment, you must create an containing just the node fragment and pass that to the method. - - The following example performs a transformation on a node fragment. - -```csharp -XslTransform xslt = new XslTransform(); -xslt.Load("print_root.xsl"); -XmlDocument doc = new XmlDocument(); -doc.Load("library.xml"); -// Create a new document containing just the node fragment. -XmlNode testNode = doc.DocumentElement.FirstChild; -XmlDocument tmpDoc = new XmlDocument(); -tmpDoc.LoadXml(testNode.OuterXml); -// Pass the document containing the node fragment -// to the Transform method. -Console.WriteLine("Passing " + tmpDoc.OuterXml + " to print_root.xsl"); -xslt.Transform(tmpDoc, null, Console.Out); -``` - - The example uses the `library.xml` and `print_root.xsl` files as input and outputs the following to the console. - -``` -Passing Pride And Prejudice to print_root.xsl -Root node is book. -``` - - `library.xml` - -```xml - - - Pride And Prejudice - - - Hook - - -``` - - `print_root.xsl` - -```xml - - - - -``` - +> This method is now obsolete. The setting of the property determines how the XSLT `document()` function is resolved. The recommended practice is to use the method which takes an object as one of its arguments. + + The `args` are matched with the `xsl:param` elements defined in the style sheet. The `xsl:output` element is not supported when outputting to an (the `xsl:output` element is ignored). See [Outputs from an XslTransform](/dotnet/standard/data/xml/outputs-from-an-xsltransform) for more information. + + This method enables you to do an asynchronous transformation of the source document. + + Transformations apply to the document as a whole. In other words, if you pass in a node other than the document root node, this does not prevent the transformation process from accessing all nodes in the loaded document. To transform a node fragment, you must create an containing just the node fragment and pass that to the method. + + The following example performs a transformation on a node fragment. + +```csharp +XslTransform xslt = new XslTransform(); +xslt.Load("print_root.xsl"); +XmlDocument doc = new XmlDocument(); +doc.Load("library.xml"); +// Create a new document containing just the node fragment. +XmlNode testNode = doc.DocumentElement.FirstChild; +XmlDocument tmpDoc = new XmlDocument(); +tmpDoc.LoadXml(testNode.OuterXml); +// Pass the document containing the node fragment +// to the Transform method. +Console.WriteLine("Passing " + tmpDoc.OuterXml + " to print_root.xsl"); +xslt.Transform(tmpDoc, null, Console.Out); +``` + + The example uses the `library.xml` and `print_root.xsl` files as input and outputs the following to the console. + +``` +Passing Pride And Prejudice to print_root.xsl +Root node is book. +``` + + `library.xml` + +```xml + + + Pride And Prejudice + + + Hook + + +``` + + `print_root.xsl` + +```xml + + + + +``` + ]]> Implementation of Discretionary Behaviors in the XslTransform Class @@ -1432,28 +1432,28 @@ Root node is book. Transforms the XML data in the using the specified and outputs the result to an . An containing the results of the transformation. - [!NOTE] -> The class is obsolete in the .NET Framework version 2.0. The class is the new XSLT processor. For more information, see [Using the XslCompiledTransform Class](/dotnet/standard/data/xml/using-the-xslcompiledtransform-class) and [Migrating From the XslTransform Class](/dotnet/standard/data/xml/migrating-from-the-xsltransform-class). - - supports the XSLT 1.0 syntax. The XSLT style sheet must include the namespace declaration `xmlns:xsl= http://www.w3.org/1999/XSL/Transform`. - - The `args` are matched with the `xsl:param` elements defined in the style sheet. The transformation selections apply to the document as a whole. In other words, if the current node is set on a node tree other than the document root node, this does not prevent the transformation process from accessing all nodes in the loaded document. After the transformation has been performed, the remains in its original state. This means that the node, which is current before the transformation process, remains the current node after the method has been called. - - Because provides read-only output, the `xsl:output` element is ignored. See [Outputs from an XslTransform](/dotnet/standard/data/xml/outputs-from-an-xsltransform) for more information. - - This method enables you to do an asynchronous transformation of the source document. - +> The class is obsolete in the .NET Framework version 2.0. The class is the new XSLT processor. For more information, see [Using the XslCompiledTransform Class](/dotnet/standard/data/xml/using-the-xslcompiledtransform-class) and [Migrating From the XslTransform Class](/dotnet/standard/data/xml/migrating-from-the-xsltransform-class). + + supports the XSLT 1.0 syntax. The XSLT style sheet must include the namespace declaration `xmlns:xsl= http://www.w3.org/1999/XSL/Transform`. + + The `args` are matched with the `xsl:param` elements defined in the style sheet. The transformation selections apply to the document as a whole. In other words, if the current node is set on a node tree other than the document root node, this does not prevent the transformation process from accessing all nodes in the loaded document. After the transformation has been performed, the remains in its original state. This means that the node, which is current before the transformation process, remains the current node after the method has been called. + + Because provides read-only output, the `xsl:output` element is ignored. See [Outputs from an XslTransform](/dotnet/standard/data/xml/outputs-from-an-xsltransform) for more information. + + This method enables you to do an asynchronous transformation of the source document. + > [!NOTE] -> This method is obsolete. The setting of the property determines how the XSLT document() function is resolved. The recommended practice is to use the method which takes an object as one of its arguments. - +> This method is obsolete. The setting of the property determines how the XSLT document() function is resolved. The recommended practice is to use the method which takes an object as one of its arguments. + ]]> - There was an error processing the XSLT transformation. - + There was an error processing the XSLT transformation. + Note: This is a change in behavior from earlier versions. An is thrown if you are using Microsoft .NET Framework version 1.1 or earlier. Implementation of Discretionary Behaviors in the XslTransform Class
@@ -1508,29 +1508,29 @@ Root node is book. The URL of the source document to be transformed. The URL of the output file. - The used to resolve the XSLT document() function. If this is , the document() function is not resolved. - + The used to resolve the XSLT document() function. If this is , the document() function is not resolved. + The is not cached after the method completes. Transforms the XML data in the input file and outputs the result to an output file. - [!NOTE] -> The class is obsolete in the .NET Framework version 2.0. The class is the new XSLT processor. For more information, see [Using the XslCompiledTransform Class](/dotnet/standard/data/xml/using-the-xslcompiledtransform-class) and [Migrating From the XslTransform Class](/dotnet/standard/data/xml/migrating-from-the-xsltransform-class). - - supports the XSLT 1.0 syntax. The XSLT style sheet must include the namespace declaration `xmlns:xsl= http://www.w3.org/1999/XSL/Transform`. - - - -## Examples - The following example performs an XSLT transformation and outputs to a file. An with default credentials is used resolve an external resources. See for details. - +> The class is obsolete in the .NET Framework version 2.0. The class is the new XSLT processor. For more information, see [Using the XslCompiledTransform Class](/dotnet/standard/data/xml/using-the-xslcompiledtransform-class) and [Migrating From the XslTransform Class](/dotnet/standard/data/xml/migrating-from-the-xsltransform-class). + + supports the XSLT 1.0 syntax. The XSLT style sheet must include the namespace declaration `xmlns:xsl= http://www.w3.org/1999/XSL/Transform`. + + + +## Examples + The following example performs an XSLT transformation and outputs to a file. An with default credentials is used resolve an external resources. See for details. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/XslTRansform.Transform7/CPP/trans_snip4.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.Xsl/XslTransform/Transform/trans_snip4.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XslTRansform.Transform7/VB/trans_snip4.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XslTRansform.Transform7/VB/trans_snip4.vb" id="Snippet1"::: + ]]> @@ -1597,74 +1597,74 @@ Root node is book. The stream to which you want to output. Transforms the XML data in the using the specified and outputs the result to a . - [!NOTE] -> The class is obsolete in the .NET Framework version 2.0. The class is the new XSLT processor. For more information, see [Using the XslCompiledTransform Class](/dotnet/standard/data/xml/using-the-xslcompiledtransform-class) and [Migrating From the XslTransform Class](/dotnet/standard/data/xml/migrating-from-the-xsltransform-class). - - supports the XSLT 1.0 syntax. The XSLT style sheet must include the namespace declaration `xmlns:xsl= http://www.w3.org/1999/XSL/Transform`. - +> The class is obsolete in the .NET Framework version 2.0. The class is the new XSLT processor. For more information, see [Using the XslCompiledTransform Class](/dotnet/standard/data/xml/using-the-xslcompiledtransform-class) and [Migrating From the XslTransform Class](/dotnet/standard/data/xml/migrating-from-the-xsltransform-class). + + supports the XSLT 1.0 syntax. The XSLT style sheet must include the namespace declaration `xmlns:xsl= http://www.w3.org/1999/XSL/Transform`. + > [!NOTE] -> This method is now obsolete. The setting of the property determines how the XSLT `document()` function is resolved. The recommended practice is to use the method which takes an object as one of its arguments. - - The `args` are matched with the `xsl:param` elements defined in the style sheet. - - Transformations apply to the document as a whole. In other words, if you pass in a node other than the document root node, this does not prevent the transformation process from accessing all nodes in the loaded document. To transform a node fragment, you must create an containing just the node fragment and pass that to the method. - - The following example performs a transformation on a node fragment. - -```csharp -XslTransform xslt = new XslTransform(); -xslt.Load("print_root.xsl"); -XmlDocument doc = new XmlDocument(); -doc.Load("library.xml"); -// Create a new document containing just the node fragment. -XmlNode testNode = doc.DocumentElement.FirstChild; -XmlDocument tmpDoc = new XmlDocument(); -tmpDoc.LoadXml(testNode.OuterXml); -// Pass the document containing the node fragment -// to the Transform method. -Console.WriteLine("Passing " + tmpDoc.OuterXml + " to print_root.xsl"); -xslt.Transform(tmpDoc, null, Console.Out); -``` - - The example uses the `library.xml` and `print_root.xsl` files as input and outputs the following to the console. - -``` -Passing Pride And Prejudice to print_root.xsl -Root node is book. -``` - - `library.xml` - -```xml - - - Pride And Prejudice - - - Hook - - -``` - - `print_root.xsl` - -```xml - - - - -``` - +> This method is now obsolete. The setting of the property determines how the XSLT `document()` function is resolved. The recommended practice is to use the method which takes an object as one of its arguments. + + The `args` are matched with the `xsl:param` elements defined in the style sheet. + + Transformations apply to the document as a whole. In other words, if you pass in a node other than the document root node, this does not prevent the transformation process from accessing all nodes in the loaded document. To transform a node fragment, you must create an containing just the node fragment and pass that to the method. + + The following example performs a transformation on a node fragment. + +```csharp +XslTransform xslt = new XslTransform(); +xslt.Load("print_root.xsl"); +XmlDocument doc = new XmlDocument(); +doc.Load("library.xml"); +// Create a new document containing just the node fragment. +XmlNode testNode = doc.DocumentElement.FirstChild; +XmlDocument tmpDoc = new XmlDocument(); +tmpDoc.LoadXml(testNode.OuterXml); +// Pass the document containing the node fragment +// to the Transform method. +Console.WriteLine("Passing " + tmpDoc.OuterXml + " to print_root.xsl"); +xslt.Transform(tmpDoc, null, Console.Out); +``` + + The example uses the `library.xml` and `print_root.xsl` files as input and outputs the following to the console. + +``` +Passing Pride And Prejudice to print_root.xsl +Root node is book. +``` + + `library.xml` + +```xml + + + Pride And Prejudice + + + Hook + + +``` + + `print_root.xsl` + +```xml + + + + +``` + ]]> - There was an error processing the XSLT transformation. - + There was an error processing the XSLT transformation. + Note: This is a change in behavior from earlier versions. An is thrown if you are using Microsoft .NET Framework version 1.1 or earlier. Implementation of Discretionary Behaviors in the XslTransform Class Outputs from an XslTransform @@ -1729,76 +1729,76 @@ Root node is book. The to which you want to output. Transforms the XML data in the using the specified and outputs the result to a . - [!NOTE] -> The class is obsolete in the .NET Framework version 2.0. The class is the new XSLT processor. For more information, see [Using the XslCompiledTransform Class](/dotnet/standard/data/xml/using-the-xslcompiledtransform-class) and [Migrating From the XslTransform Class](/dotnet/standard/data/xml/migrating-from-the-xsltransform-class). - - supports the XSLT 1.0 syntax. The XSLT style sheet must include the namespace declaration `xmlns:xsl= http://www.w3.org/1999/XSL/Transform`. - +> The class is obsolete in the .NET Framework version 2.0. The class is the new XSLT processor. For more information, see [Using the XslCompiledTransform Class](/dotnet/standard/data/xml/using-the-xslcompiledtransform-class) and [Migrating From the XslTransform Class](/dotnet/standard/data/xml/migrating-from-the-xsltransform-class). + + supports the XSLT 1.0 syntax. The XSLT style sheet must include the namespace declaration `xmlns:xsl= http://www.w3.org/1999/XSL/Transform`. + > [!NOTE] -> This method is now obsolete. The setting of the property determines how the XSLT `document()` function is resolved. The recommended practice is to use the method which takes an object as one of its arguments. - - The `args` are matched with the `xsl:param` elements defined in the style sheet. - - The encoding attribute on an `xsl:output` element is not supported when outputting to a . See [Outputs from an XslTransform](/dotnet/standard/data/xml/outputs-from-an-xsltransform) for specifics on which `xsl:output` attributes are supported. - - Transformations apply to the document as a whole. In other words, if you pass in a node other than the document root node, this does not prevent the transformation process from accessing all nodes in the loaded document. To transform a node fragment, you must create an containing just the node fragment, and pass that to the method. - - The following example performs a transformation on a node fragment. - -```csharp -XslTransform xslt = new XslTransform(); -xslt.Load("print_root.xsl"); -XmlDocument doc = new XmlDocument(); -doc.Load("library.xml"); -// Create a new document containing just the node fragment. -XmlNode testNode = doc.DocumentElement.FirstChild; -XmlDocument tmpDoc = new XmlDocument(); -tmpDoc.LoadXml(testNode.OuterXml); -// Pass the document containing the node fragment -// to the Transform method. -Console.WriteLine("Passing " + tmpDoc.OuterXml + " to print_root.xsl"); -xslt.Transform(tmpDoc, null, Console.Out); -``` - - The example uses the `library.xml` and `print_root.xsl` files as input and outputs the following to the console. - -``` -Passing Pride And Prejudice to print_root.xsl -Root node is book. -``` - - `library.xml` - -```xml - - - Pride And Prejudice - - - Hook - - -``` - - `print_root.xsl` - -```xml - - - - -``` - +> This method is now obsolete. The setting of the property determines how the XSLT `document()` function is resolved. The recommended practice is to use the method which takes an object as one of its arguments. + + The `args` are matched with the `xsl:param` elements defined in the style sheet. + + The encoding attribute on an `xsl:output` element is not supported when outputting to a . See [Outputs from an XslTransform](/dotnet/standard/data/xml/outputs-from-an-xsltransform) for specifics on which `xsl:output` attributes are supported. + + Transformations apply to the document as a whole. In other words, if you pass in a node other than the document root node, this does not prevent the transformation process from accessing all nodes in the loaded document. To transform a node fragment, you must create an containing just the node fragment, and pass that to the method. + + The following example performs a transformation on a node fragment. + +```csharp +XslTransform xslt = new XslTransform(); +xslt.Load("print_root.xsl"); +XmlDocument doc = new XmlDocument(); +doc.Load("library.xml"); +// Create a new document containing just the node fragment. +XmlNode testNode = doc.DocumentElement.FirstChild; +XmlDocument tmpDoc = new XmlDocument(); +tmpDoc.LoadXml(testNode.OuterXml); +// Pass the document containing the node fragment +// to the Transform method. +Console.WriteLine("Passing " + tmpDoc.OuterXml + " to print_root.xsl"); +xslt.Transform(tmpDoc, null, Console.Out); +``` + + The example uses the `library.xml` and `print_root.xsl` files as input and outputs the following to the console. + +``` +Passing Pride And Prejudice to print_root.xsl +Root node is book. +``` + + `library.xml` + +```xml + + + Pride And Prejudice + + + Hook + + +``` + + `print_root.xsl` + +```xml + + + + +``` + ]]> - There was an error processing the XSLT transformation. - + There was an error processing the XSLT transformation. + Note: This is a change in behavior from earlier versions. An is thrown if you are using Microsoft .NET Framework version 1.1 or earlier. Implementation of Discretionary Behaviors in the XslTransform Class Outputs from an XslTransform @@ -1861,84 +1861,84 @@ Root node is book. An object implementing the interface. In the .NET Framework, this can be either an (typically an ), or an containing the data to be transformed. An containing the namespace-qualified arguments used as input to the transformation. - The used to resolve the XSLT document() function. If this is , the document() function is not resolved. - + The used to resolve the XSLT document() function. If this is , the document() function is not resolved. + The is not cached after the method completes. Transforms the XML data in the using the specified and outputs the result to an . An containing the results of the transformation. - [!NOTE] -> The class is obsolete in the .NET Framework version 2.0. The class is the new XSLT processor. For more information, see [Using the XslCompiledTransform Class](/dotnet/standard/data/xml/using-the-xslcompiledtransform-class) and [Migrating From the XslTransform Class](/dotnet/standard/data/xml/migrating-from-the-xsltransform-class). - - supports the XSLT 1.0 syntax. The XSLT style sheet must include the namespace declaration `xmlns:xsl= http://www.w3.org/1999/XSL/Transform`. - - The `args` are matched with the `xsl:param` elements defined in the style sheet. The `xsl:output` element is not supported when outputting to an (the `xsl:output` element is ignored). See [Outputs from an XslTransform](/dotnet/standard/data/xml/outputs-from-an-xsltransform) for more information. - - This method enables you to do an asynchronous transformation of the source document. - - Transformations apply to the document as a whole. In other words, if you pass in a node other than the document root node, this does not prevent the transformation process from accessing all nodes in the loaded document. To transform a node fragment, you must create an containing just the node fragment, and pass that to the method. - - The following example performs a transformation on a node fragment. - -```csharp -XslTransform xslt = new XslTransform(); -xslt.Load("print_root.xsl"); -XmlDocument doc = new XmlDocument(); -doc.Load("library.xml"); -// Create a new document containing just the node fragment. -XmlNode testNode = doc.DocumentElement.FirstChild; -XmlDocument tmpDoc = new XmlDocument(); -tmpDoc.LoadXml(testNode.OuterXml); -// Pass the document containing the node fragment -// to the Transform method. -Console.WriteLine("Passing " + tmpDoc.OuterXml + " to print_root.xsl"); -xslt.Transform(tmpDoc, null, Console.Out, null); -``` - - The example uses the `library.xml` and `print_root.xsl` files as input and outputs the following to the console. - -``` -Passing Pride And Prejudice to print_root.xsl -Root node is book. -``` - - `library.xml` - -```xml - - - Pride And Prejudice - - - Hook - - -``` - - `print_root.xsl` - -```xml - - - - -``` - - - -## Examples - The following example transforms an XML document and outputs the results to an `XmlReader`. An with the necessary credentials is used to process any XSLT `document()` functions. - +> The class is obsolete in the .NET Framework version 2.0. The class is the new XSLT processor. For more information, see [Using the XslCompiledTransform Class](/dotnet/standard/data/xml/using-the-xslcompiledtransform-class) and [Migrating From the XslTransform Class](/dotnet/standard/data/xml/migrating-from-the-xsltransform-class). + + supports the XSLT 1.0 syntax. The XSLT style sheet must include the namespace declaration `xmlns:xsl= http://www.w3.org/1999/XSL/Transform`. + + The `args` are matched with the `xsl:param` elements defined in the style sheet. The `xsl:output` element is not supported when outputting to an (the `xsl:output` element is ignored). See [Outputs from an XslTransform](/dotnet/standard/data/xml/outputs-from-an-xsltransform) for more information. + + This method enables you to do an asynchronous transformation of the source document. + + Transformations apply to the document as a whole. In other words, if you pass in a node other than the document root node, this does not prevent the transformation process from accessing all nodes in the loaded document. To transform a node fragment, you must create an containing just the node fragment, and pass that to the method. + + The following example performs a transformation on a node fragment. + +```csharp +XslTransform xslt = new XslTransform(); +xslt.Load("print_root.xsl"); +XmlDocument doc = new XmlDocument(); +doc.Load("library.xml"); +// Create a new document containing just the node fragment. +XmlNode testNode = doc.DocumentElement.FirstChild; +XmlDocument tmpDoc = new XmlDocument(); +tmpDoc.LoadXml(testNode.OuterXml); +// Pass the document containing the node fragment +// to the Transform method. +Console.WriteLine("Passing " + tmpDoc.OuterXml + " to print_root.xsl"); +xslt.Transform(tmpDoc, null, Console.Out, null); +``` + + The example uses the `library.xml` and `print_root.xsl` files as input and outputs the following to the console. + +``` +Passing Pride And Prejudice to print_root.xsl +Root node is book. +``` + + `library.xml` + +```xml + + + Pride And Prejudice + + + Hook + + +``` + + `print_root.xsl` + +```xml + + + + +``` + + + +## Examples + The following example transforms an XML document and outputs the results to an `XmlReader`. An with the necessary credentials is used to process any XSLT `document()` functions. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/XslTransform.Transform4/CPP/trans_snip3.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.Xsl/XslTransform/Transform/trans_snip3.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XslTransform.Transform4/VB/trans_snip3.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XslTransform.Transform4/VB/trans_snip3.vb" id="Snippet1"::: + ]]> @@ -2005,74 +2005,74 @@ Root node is book. The to which you want to output. Transforms the XML data in the using the specified and outputs the result to an . - [!NOTE] -> The class is obsolete in the .NET Framework version 2.0. The class is the new XSLT processor. For more information, see [Using the XslCompiledTransform Class](/dotnet/standard/data/xml/using-the-xslcompiledtransform-class) and [Migrating From the XslTransform Class](/dotnet/standard/data/xml/migrating-from-the-xsltransform-class). - - supports the XSLT 1.0 syntax. The XSLT style sheet must include the namespace declaration `xmlns:xsl= http://www.w3.org/1999/XSL/Transform`. - +> The class is obsolete in the .NET Framework version 2.0. The class is the new XSLT processor. For more information, see [Using the XslCompiledTransform Class](/dotnet/standard/data/xml/using-the-xslcompiledtransform-class) and [Migrating From the XslTransform Class](/dotnet/standard/data/xml/migrating-from-the-xsltransform-class). + + supports the XSLT 1.0 syntax. The XSLT style sheet must include the namespace declaration `xmlns:xsl= http://www.w3.org/1999/XSL/Transform`. + > [!NOTE] -> This method is now obsolete. The setting of the property determines how the XSLT `document()` function is resolved. The recommended practice is to use the method which takes an object as one of its arguments. - - The `args` are matched with the `xsl:param` elements defined in the style sheet. The `xsl:output` element is not supported when outputting to an (`xsl:output` is ignored). See [Outputs from an XslTransform](/dotnet/standard/data/xml/outputs-from-an-xsltransform) for more information. - - Transformations apply to the document as a whole. In other words, if you pass in a node other than the document root node, this does not prevent the transformation process from accessing all nodes in the loaded document. To transform a node fragment, you must create an containing just the node fragment and pass that to the method. - - The following example performs a transformation on a node fragment. - -```csharp -XslTransform xslt = new XslTransform(); -xslt.Load("print_root.xsl"); -XmlDocument doc = new XmlDocument(); -doc.Load("library.xml"); -// Create a new document containing just the node fragment. -XmlNode testNode = doc.DocumentElement.FirstChild; -XmlDocument tmpDoc = new XmlDocument(); -tmpDoc.LoadXml(testNode.OuterXml); -// Pass the document containing the node fragment -// to the Transform method. -Console.WriteLine("Passing " + tmpDoc.OuterXml + " to print_root.xsl"); -xslt.Transform(tmpDoc, null, Console.Out); -``` - - The example uses the `library.xml` and `print_root.xsl` files as input and outputs the following to the console. - -``` -Passing Pride And Prejudice to print_root.xsl -Root node is book. -``` - - `library.xml` - -```xml - - - Pride And Prejudice - - - Hook - - -``` - - `print_root.xsl` - -```xml - - - - -``` - +> This method is now obsolete. The setting of the property determines how the XSLT `document()` function is resolved. The recommended practice is to use the method which takes an object as one of its arguments. + + The `args` are matched with the `xsl:param` elements defined in the style sheet. The `xsl:output` element is not supported when outputting to an (`xsl:output` is ignored). See [Outputs from an XslTransform](/dotnet/standard/data/xml/outputs-from-an-xsltransform) for more information. + + Transformations apply to the document as a whole. In other words, if you pass in a node other than the document root node, this does not prevent the transformation process from accessing all nodes in the loaded document. To transform a node fragment, you must create an containing just the node fragment and pass that to the method. + + The following example performs a transformation on a node fragment. + +```csharp +XslTransform xslt = new XslTransform(); +xslt.Load("print_root.xsl"); +XmlDocument doc = new XmlDocument(); +doc.Load("library.xml"); +// Create a new document containing just the node fragment. +XmlNode testNode = doc.DocumentElement.FirstChild; +XmlDocument tmpDoc = new XmlDocument(); +tmpDoc.LoadXml(testNode.OuterXml); +// Pass the document containing the node fragment +// to the Transform method. +Console.WriteLine("Passing " + tmpDoc.OuterXml + " to print_root.xsl"); +xslt.Transform(tmpDoc, null, Console.Out); +``` + + The example uses the `library.xml` and `print_root.xsl` files as input and outputs the following to the console. + +``` +Passing Pride And Prejudice to print_root.xsl +Root node is book. +``` + + `library.xml` + +```xml + + + Pride And Prejudice + + + Hook + + +``` + + `print_root.xsl` + +```xml + + + + +``` + ]]> - There was an error processing the XSLT transformation. - + There was an error processing the XSLT transformation. + Note: This is a change in behavior from earlier versions. An is thrown if you are using Microsoft .NET Framework version 1.1 or earlier. Implementation of Discretionary Behaviors in the XslTransform Class Outputs from an XslTransform @@ -2137,26 +2137,26 @@ Root node is book. The stream to which you want to output. Transforms the XML data in the using the specified and outputs the result to a . - [!NOTE] -> The class is obsolete in the .NET Framework version 2.0. The class is the new XSLT processor. For more information, see [Using the XslCompiledTransform Class](/dotnet/standard/data/xml/using-the-xslcompiledtransform-class) and [Migrating From the XslTransform Class](/dotnet/standard/data/xml/migrating-from-the-xsltransform-class). - - supports the XSLT 1.0 syntax. The XSLT style sheet must include the namespace declaration `xmlns:xsl= http://www.w3.org/1999/XSL/Transform`. - - The `args` are matched with the `xsl:param` elements defined in the style sheet. The transformation selections apply to the document as a whole. In other words, if the current node is set on a node tree other than the document root node, this does not prevent the transformation process from accessing all nodes in the loaded document. After the transformation has been performed, the remains in its original state. This means that the node, which is current before the transformation process, remains the current node after the method has been called. - - See [Outputs from an XslTransform](/dotnet/standard/data/xml/outputs-from-an-xsltransform) for specifics on which `xsl:output` attributes are supported. - +> The class is obsolete in the .NET Framework version 2.0. The class is the new XSLT processor. For more information, see [Using the XslCompiledTransform Class](/dotnet/standard/data/xml/using-the-xslcompiledtransform-class) and [Migrating From the XslTransform Class](/dotnet/standard/data/xml/migrating-from-the-xsltransform-class). + + supports the XSLT 1.0 syntax. The XSLT style sheet must include the namespace declaration `xmlns:xsl= http://www.w3.org/1999/XSL/Transform`. + + The `args` are matched with the `xsl:param` elements defined in the style sheet. The transformation selections apply to the document as a whole. In other words, if the current node is set on a node tree other than the document root node, this does not prevent the transformation process from accessing all nodes in the loaded document. After the transformation has been performed, the remains in its original state. This means that the node, which is current before the transformation process, remains the current node after the method has been called. + + See [Outputs from an XslTransform](/dotnet/standard/data/xml/outputs-from-an-xsltransform) for specifics on which `xsl:output` attributes are supported. + > [!NOTE] -> This method is now obsolete. The setting of the property determines how the XSLT `document()` function is resolved. The recommended practice is to use the method which takes an object as one of its arguments. - +> This method is now obsolete. The setting of the property determines how the XSLT `document()` function is resolved. The recommended practice is to use the method which takes an object as one of its arguments. + ]]> - There was an error processing the XSLT transformation. - + There was an error processing the XSLT transformation. + Note: This is a change in behavior from earlier versions. An is thrown if you are using Microsoft .NET Framework version 1.1 or earlier. Implementation of Discretionary Behaviors in the XslTransform Class @@ -2221,26 +2221,26 @@ Root node is book. The to which you want to output. Transforms the XML data in the using the specified and outputs the result to a . - [!NOTE] -> The class is obsolete in the .NET Framework version 2.0. The class is the new XSLT processor. For more information, see [Using the XslCompiledTransform Class](/dotnet/standard/data/xml/using-the-xslcompiledtransform-class) and [Migrating From the XslTransform Class](/dotnet/standard/data/xml/migrating-from-the-xsltransform-class). - - supports the XSLT 1.0 syntax. The XSLT style sheet must include the namespace declaration `xmlns:xsl= http://www.w3.org/1999/XSL/Transform`. - - The `args` are matched with the `xsl:param` elements defined in the style sheet. The transformation selections apply to the document as a whole. In other words, if the current node is set on a node tree other than the document root node, this does not prevent the transformation process from accessing all nodes in the loaded document. After the transformation is performed, the remains in its original state. This means that the node, which is current before the transformation process, remains the current node after the method has been called. - - The encoding attribute on an `xsl:output` element is not supported when outputting to a . See [Outputs from an XslTransform](/dotnet/standard/data/xml/outputs-from-an-xsltransform) for specifics on which `xsl:output` attributes are supported. - +> The class is obsolete in the .NET Framework version 2.0. The class is the new XSLT processor. For more information, see [Using the XslCompiledTransform Class](/dotnet/standard/data/xml/using-the-xslcompiledtransform-class) and [Migrating From the XslTransform Class](/dotnet/standard/data/xml/migrating-from-the-xsltransform-class). + + supports the XSLT 1.0 syntax. The XSLT style sheet must include the namespace declaration `xmlns:xsl= http://www.w3.org/1999/XSL/Transform`. + + The `args` are matched with the `xsl:param` elements defined in the style sheet. The transformation selections apply to the document as a whole. In other words, if the current node is set on a node tree other than the document root node, this does not prevent the transformation process from accessing all nodes in the loaded document. After the transformation is performed, the remains in its original state. This means that the node, which is current before the transformation process, remains the current node after the method has been called. + + The encoding attribute on an `xsl:output` element is not supported when outputting to a . See [Outputs from an XslTransform](/dotnet/standard/data/xml/outputs-from-an-xsltransform) for specifics on which `xsl:output` attributes are supported. + > [!NOTE] -> This method is now obsolete. The setting of the property determines how the XSLT `document()` function is resolved. The recommended practice is to use the method which takes an object as one of its arguments. - +> This method is now obsolete. The setting of the property determines how the XSLT `document()` function is resolved. The recommended practice is to use the method which takes an object as one of its arguments. + ]]> - There was an error processing the XSLT transformation. - + There was an error processing the XSLT transformation. + Note: This is a change in behavior from earlier versions. An is thrown if you are using Microsoft .NET Framework version 1.1 or earlier. Implementation of Discretionary Behaviors in the XslTransform Class @@ -2303,31 +2303,31 @@ Root node is book. An containing the data to be transformed. An containing the namespace-qualified arguments used as input to the transformation. - The used to resolve the XSLT document() function. If this is , the document() function is not resolved. - + The used to resolve the XSLT document() function. If this is , the document() function is not resolved. + The is not cached after the method completes. Transforms the XML data in the using the specified and outputs the result to an . An containing the results of the transformation. - [!NOTE] -> The class is obsolete in the .NET Framework version 2.0. The class is the new XSLT processor. For more information, see [Using the XslCompiledTransform Class](/dotnet/standard/data/xml/using-the-xslcompiledtransform-class) and [Migrating From the XslTransform Class](/dotnet/standard/data/xml/migrating-from-the-xsltransform-class). - - supports the XSLT 1.0 syntax. The XSLT style sheet must include the namespace declaration `xmlns:xsl= http://www.w3.org/1999/XSL/Transform`. - - The `args` are matched with the `xsl:param` elements defined in the style sheet. The transformation selections apply to the document as a whole. In other words, if the current node is set on a node tree other than the document root node, this does not prevent the transformation process from accessing all nodes in the loaded document. After the transformation has been performed, the remains in its original state. This means that the node, which is current before the transformation process, remains the current node after the method has been called. - - Because provides read-only output, the `xsl:output` element is ignored. See [Outputs from an XslTransform](/dotnet/standard/data/xml/outputs-from-an-xsltransform) for more information. - - This method enables you to do an asynchronous transformation of the source document. - +> The class is obsolete in the .NET Framework version 2.0. The class is the new XSLT processor. For more information, see [Using the XslCompiledTransform Class](/dotnet/standard/data/xml/using-the-xslcompiledtransform-class) and [Migrating From the XslTransform Class](/dotnet/standard/data/xml/migrating-from-the-xsltransform-class). + + supports the XSLT 1.0 syntax. The XSLT style sheet must include the namespace declaration `xmlns:xsl= http://www.w3.org/1999/XSL/Transform`. + + The `args` are matched with the `xsl:param` elements defined in the style sheet. The transformation selections apply to the document as a whole. In other words, if the current node is set on a node tree other than the document root node, this does not prevent the transformation process from accessing all nodes in the loaded document. After the transformation has been performed, the remains in its original state. This means that the node, which is current before the transformation process, remains the current node after the method has been called. + + Because provides read-only output, the `xsl:output` element is ignored. See [Outputs from an XslTransform](/dotnet/standard/data/xml/outputs-from-an-xsltransform) for more information. + + This method enables you to do an asynchronous transformation of the source document. + ]]> - There was an error processing the XSLT transformation. - + There was an error processing the XSLT transformation. + Note: This is a change in behavior from earlier versions. An is thrown if you are using Microsoft .NET Framework version 1.1 or earlier. Implementation of Discretionary Behaviors in the XslTransform Class @@ -2392,26 +2392,26 @@ Root node is book. The to which you want to output. Transforms the XML data in the using the specified args and outputs the result to an . - [!NOTE] -> The class is obsolete in the .NET Framework version 2.0. The class is the new XSLT processor. For more information, see [Using the XslCompiledTransform Class](/dotnet/standard/data/xml/using-the-xslcompiledtransform-class) and [Migrating From the XslTransform Class](/dotnet/standard/data/xml/migrating-from-the-xsltransform-class). - - supports the XSLT 1.0 syntax. The XSLT style sheet must include the namespace declaration `xmlns:xsl= http://www.w3.org/1999/XSL/Transform`. - - The `args` are matched with the `xsl:param` elements defined in the style sheet. The transformation selections apply to the document as a whole. In other words, if the current node is set on a node tree other than the document root node, this does not prevent the transformation process from accessing all nodes in the loaded document. After the transformation is performed, the remains in its original state. This means that the node, that is current before the transformation process, remains the current node after the method has been called. - - The `xsl:output` element is not supported when outputting to an (`xsl:output` is ignored). See [Outputs from an XslTransform](/dotnet/standard/data/xml/outputs-from-an-xsltransform) for more information. - +> The class is obsolete in the .NET Framework version 2.0. The class is the new XSLT processor. For more information, see [Using the XslCompiledTransform Class](/dotnet/standard/data/xml/using-the-xslcompiledtransform-class) and [Migrating From the XslTransform Class](/dotnet/standard/data/xml/migrating-from-the-xsltransform-class). + + supports the XSLT 1.0 syntax. The XSLT style sheet must include the namespace declaration `xmlns:xsl= http://www.w3.org/1999/XSL/Transform`. + + The `args` are matched with the `xsl:param` elements defined in the style sheet. The transformation selections apply to the document as a whole. In other words, if the current node is set on a node tree other than the document root node, this does not prevent the transformation process from accessing all nodes in the loaded document. After the transformation is performed, the remains in its original state. This means that the node, that is current before the transformation process, remains the current node after the method has been called. + + The `xsl:output` element is not supported when outputting to an (`xsl:output` is ignored). See [Outputs from an XslTransform](/dotnet/standard/data/xml/outputs-from-an-xsltransform) for more information. + > [!NOTE] -> This method is now obsolete. The setting of the property determines how the XSLT `document()` function is resolved. The recommended practice is to use the method which takes an object as one of its arguments. - +> This method is now obsolete. The setting of the property determines how the XSLT `document()` function is resolved. The recommended practice is to use the method which takes an object as one of its arguments. + ]]> - There was an error processing the XSLT transformation. - + There was an error processing the XSLT transformation. + Note: This is a change in behavior from earlier versions. An is thrown if you are using Microsoft .NET Framework version 1.1 or earlier. Implementation of Discretionary Behaviors in the XslTransform Class @@ -2476,84 +2476,84 @@ Root node is book. An object implementing the interface. In the .NET Framework, this can be either an (typically an ), or an containing the data to be transformed. An containing the namespace-qualified arguments used as input to the transformation. The stream to which you want to output. - The used to resolve the XSLT document() function. If this is , the document() function is not resolved. - + The used to resolve the XSLT document() function. If this is , the document() function is not resolved. + The is not cached after the method completes. Transforms the XML data in the using the specified and outputs the result to a . - [!NOTE] -> The class is obsolete in the .NET Framework version 2.0. The class is the new XSLT processor. For more information, see [Using the XslCompiledTransform Class](/dotnet/standard/data/xml/using-the-xslcompiledtransform-class) and [Migrating From the XslTransform Class](/dotnet/standard/data/xml/migrating-from-the-xsltransform-class). - - supports the XSLT 1.0 syntax. The XSLT style sheet must include the namespace declaration `xmlns:xsl= http://www.w3.org/1999/XSL/Transform`. - - The `args` are matched with the `xsl:param` elements defined in the style sheet. - - Transformations apply to the document as a whole. In other words, if you pass in a node other than the document root node, this does not prevent the transformation process from accessing all nodes in the loaded document. To transform a node fragment, you must create an containing just the node fragment and pass that to the method. - - The following example performs a transformation on a node fragment. - -```csharp -XslTransform xslt = new XslTransform(); -xslt.Load("print_root.xsl"); -XmlDocument doc = new XmlDocument(); -doc.Load("library.xml"); -// Create a new document containing just the node fragment. -XmlNode testNode = doc.DocumentElement.FirstChild; -XmlDocument tmpDoc = new XmlDocument(); -tmpDoc.LoadXml(testNode.OuterXml); -// Pass the document containing the node fragment -// to the Transform method. -Console.WriteLine("Passing " + tmpDoc.OuterXml + " to print_root.xsl"); -xslt.Transform(tmpDoc, null, Console.Out, null); -``` - - The example uses the `library.xml` and `print_root.xsl` files as input and outputs the following to the console. - -``` -Passing Pride And Prejudice to print_root.xsl -Root node is book. -``` - - `library.xml` - -```xml - - - Pride And Prejudice - - - Hook - - -``` - - `print_root.xsl` - -```xml - - - - -``` - - - -## Examples - The following example performs a transformation within an ASP.NET page. - +> The class is obsolete in the .NET Framework version 2.0. The class is the new XSLT processor. For more information, see [Using the XslCompiledTransform Class](/dotnet/standard/data/xml/using-the-xslcompiledtransform-class) and [Migrating From the XslTransform Class](/dotnet/standard/data/xml/migrating-from-the-xsltransform-class). + + supports the XSLT 1.0 syntax. The XSLT style sheet must include the namespace declaration `xmlns:xsl= http://www.w3.org/1999/XSL/Transform`. + + The `args` are matched with the `xsl:param` elements defined in the style sheet. + + Transformations apply to the document as a whole. In other words, if you pass in a node other than the document root node, this does not prevent the transformation process from accessing all nodes in the loaded document. To transform a node fragment, you must create an containing just the node fragment and pass that to the method. + + The following example performs a transformation on a node fragment. + +```csharp +XslTransform xslt = new XslTransform(); +xslt.Load("print_root.xsl"); +XmlDocument doc = new XmlDocument(); +doc.Load("library.xml"); +// Create a new document containing just the node fragment. +XmlNode testNode = doc.DocumentElement.FirstChild; +XmlDocument tmpDoc = new XmlDocument(); +tmpDoc.LoadXml(testNode.OuterXml); +// Pass the document containing the node fragment +// to the Transform method. +Console.WriteLine("Passing " + tmpDoc.OuterXml + " to print_root.xsl"); +xslt.Transform(tmpDoc, null, Console.Out, null); +``` + + The example uses the `library.xml` and `print_root.xsl` files as input and outputs the following to the console. + +``` +Passing Pride And Prejudice to print_root.xsl +Root node is book. +``` + + `library.xml` + +```xml + + + Pride And Prejudice + + + Hook + + +``` + + `print_root.xsl` + +```xml + + + + +``` + + + +## Examples + The following example performs a transformation within an ASP.NET page. + :::code language="aspx-csharp" source="~/snippets/csharp/System.Xml.Xsl/XslTransform/Transform/transcs.aspx" id="Snippet1"::: - :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_Data/XslTransform.Transform5/VB/transvb.aspx" id="Snippet1"::: - + :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_Data/XslTransform.Transform5/VB/transvb.aspx" id="Snippet1"::: + ]]> - There was an error processing the XSLT transformation. - + There was an error processing the XSLT transformation. + Note: This is a change in behavior from earlier versions. An is thrown if you are using Microsoft .NET Framework version 1.1 or earlier. @@ -2620,90 +2620,90 @@ Root node is book. An object implementing the interface. In the .NET Framework, this can be either an (typically an ), or an containing the data to be transformed. An containing the namespace-qualified arguments used as input to the transformation. The to which you want to output. - The used to resolve the XSLT document() function. If this is , the document() function is not resolved. - + The used to resolve the XSLT document() function. If this is , the document() function is not resolved. + The is not cached after the method completes. Transforms the XML data in the using the specified and outputs the result to a . - [!NOTE] -> The class is obsolete in the .NET Framework version 2.0. The class is the new XSLT processor. For more information, see [Using the XslCompiledTransform Class](/dotnet/standard/data/xml/using-the-xslcompiledtransform-class) and [Migrating From the XslTransform Class](/dotnet/standard/data/xml/migrating-from-the-xsltransform-class). - - supports the XSLT 1.0 syntax. The XSLT style sheet must include the namespace declaration `xmlns:xsl= http://www.w3.org/1999/XSL/Transform`. - - The `args` are matched with the `xsl:param` elements defined in the style sheet. - - The encoding attribute on an `xsl:output` element is not supported when outputting to a . See [Outputs from an XslTransform](/dotnet/standard/data/xml/outputs-from-an-xsltransform) for specifics on which `xsl:output` attributes are supported. - - Transformations apply to the document as a whole. In other words, if you pass in a node other than the document root node, this does not prevent the transformation process from accessing all nodes in the loaded document. To transform a node fragment, you must create an containing just the node fragment and pass that to the method. - - The following example performs a transformation on a node fragment. - -```csharp -XslTransform xslt = new XslTransform(); -xslt.Load("print_root.xsl"); -XmlDocument doc = new XmlDocument(); -doc.Load("library.xml"); -// Create a new document containing just the node fragment. -XmlNode testNode = doc.DocumentElement.FirstChild; -XmlDocument tmpDoc = new XmlDocument(); -tmpDoc.LoadXml(testNode.OuterXml); -// Pass the document containing the node fragment -// to the Transform method. -Console.WriteLine("Passing " + tmpDoc.OuterXml + " to print_root.xsl"); -xslt.Transform(tmpDoc, null, Console.Out, null); -``` - - The example uses the `library.xml` and `print_root.xsl` files as input and outputs the following to the console. - -``` -Passing Pride And Prejudice to print_root.xsl -Root node is book. -``` - - `library.xml` - -```xml - - - Pride And Prejudice - - - Hook - - -``` - - `print_root.xsl` - -```xml - - - - -``` - - - -## Examples - The following example transforms an XML file and outputs an HTML string. The and classes are used to read and write the strings. - +> The class is obsolete in the .NET Framework version 2.0. The class is the new XSLT processor. For more information, see [Using the XslCompiledTransform Class](/dotnet/standard/data/xml/using-the-xslcompiledtransform-class) and [Migrating From the XslTransform Class](/dotnet/standard/data/xml/migrating-from-the-xsltransform-class). + + supports the XSLT 1.0 syntax. The XSLT style sheet must include the namespace declaration `xmlns:xsl= http://www.w3.org/1999/XSL/Transform`. + + The `args` are matched with the `xsl:param` elements defined in the style sheet. + + The encoding attribute on an `xsl:output` element is not supported when outputting to a . See [Outputs from an XslTransform](/dotnet/standard/data/xml/outputs-from-an-xsltransform) for specifics on which `xsl:output` attributes are supported. + + Transformations apply to the document as a whole. In other words, if you pass in a node other than the document root node, this does not prevent the transformation process from accessing all nodes in the loaded document. To transform a node fragment, you must create an containing just the node fragment and pass that to the method. + + The following example performs a transformation on a node fragment. + +```csharp +XslTransform xslt = new XslTransform(); +xslt.Load("print_root.xsl"); +XmlDocument doc = new XmlDocument(); +doc.Load("library.xml"); +// Create a new document containing just the node fragment. +XmlNode testNode = doc.DocumentElement.FirstChild; +XmlDocument tmpDoc = new XmlDocument(); +tmpDoc.LoadXml(testNode.OuterXml); +// Pass the document containing the node fragment +// to the Transform method. +Console.WriteLine("Passing " + tmpDoc.OuterXml + " to print_root.xsl"); +xslt.Transform(tmpDoc, null, Console.Out, null); +``` + + The example uses the `library.xml` and `print_root.xsl` files as input and outputs the following to the console. + +``` +Passing Pride And Prejudice to print_root.xsl +Root node is book. +``` + + `library.xml` + +```xml + + + Pride And Prejudice + + + Hook + + +``` + + `print_root.xsl` + +```xml + + + + +``` + + + +## Examples + The following example transforms an XML file and outputs an HTML string. The and classes are used to read and write the strings. + :::code language="csharp" source="~/snippets/csharp/System.Xml.Xsl/XslTransform/Transform/transstring.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XslTransform.Transform6/VB/transstring.vb" id="Snippet1"::: - - The example uses the `books.xml` file as input. - - :::code language="xml" source="~/snippets/xml/VS_Snippets_Data/XslTransform.Transform6/XML/books.xml" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XslTransform.Transform6/VB/transstring.vb" id="Snippet1"::: + + The example uses the `books.xml` file as input. + + :::code language="xml" source="~/snippets/xml/VS_Snippets_Data/XslTransform.Transform6/XML/books.xml" id="Snippet2"::: + ]]> - There was an error processing the XSLT transformation. - + There was an error processing the XSLT transformation. + Note: This is a change in behavior from earlier versions. An is thrown if you are using Microsoft .NET Framework version 1.1 or earlier. @@ -2770,95 +2770,95 @@ Root node is book. An object implementing the interface. In the .NET Framework, this can be either an (typically an ), or an containing the data to be transformed. An containing the namespace-qualified arguments used as input to the transformation. The to which you want to output. - The used to resolve the XSLT document() function. If this is , the document() function is not resolved. - + The used to resolve the XSLT document() function. If this is , the document() function is not resolved. + The is not cached after the method completes. Transforms the XML data in the using the specified and outputs the result to an . - [!NOTE] -> The class is obsolete in the .NET Framework version 2.0. The class is the new XSLT processor. For more information, see [Using the XslCompiledTransform Class](/dotnet/standard/data/xml/using-the-xslcompiledtransform-class) and [Migrating From the XslTransform Class](/dotnet/standard/data/xml/migrating-from-the-xsltransform-class). - - supports the XSLT 1.0 syntax. The XSLT style sheet must include the namespace declaration `xmlns:xsl= http://www.w3.org/1999/XSL/Transform`. - - The `args` are matched with the `xsl:param` elements defined in the style sheet. The `xsl:output` element is not supported when outputting to an (`xsl:output` is ignored). See [Outputs from an XslTransform](/dotnet/standard/data/xml/outputs-from-an-xsltransform) for more information. - - Transformations apply to the document as a whole. In other words, if you pass in a node other than the document root node, this does not prevent the transformation process from accessing all nodes in the loaded document. To transform a node fragment, you must create an containing just the node fragment and pass that to the method. - - The following example performs a transformation on a node fragment. - -```csharp -XslTransform xslt = new XslTransform(); -xslt.Load("print_root.xsl"); -XmlDocument doc = new XmlDocument(); -doc.Load("library.xml"); -// Create a new document containing just the node fragment. -XmlNode testNode = doc.DocumentElement.FirstChild; -XmlDocument tmpDoc = new XmlDocument(); -tmpDoc.LoadXml(testNode.OuterXml); -// Pass the document containing the node fragment -// to the Transform method. -Console.WriteLine("Passing " + tmpDoc.OuterXml + " to print_root.xsl"); -xslt.Transform(tmpDoc, null, Console.Out, null); -``` - - The example uses the `library.xml` and `print_root.xsl` files as input and outputs the following to the console. - -``` -Passing Pride And Prejudice to print_root.xsl -Root node is book. -``` - - `library.xml` - -```xml - - - Pride And Prejudice - - - Hook - - -``` - - `print_root.xsl` - -```xml - - - - -``` - - - -## Examples - The following example transforms an XML document into an HTML document. It displays the ISBN, title, and price for each book in a table. - +> The class is obsolete in the .NET Framework version 2.0. The class is the new XSLT processor. For more information, see [Using the XslCompiledTransform Class](/dotnet/standard/data/xml/using-the-xslcompiledtransform-class) and [Migrating From the XslTransform Class](/dotnet/standard/data/xml/migrating-from-the-xsltransform-class). + + supports the XSLT 1.0 syntax. The XSLT style sheet must include the namespace declaration `xmlns:xsl= http://www.w3.org/1999/XSL/Transform`. + + The `args` are matched with the `xsl:param` elements defined in the style sheet. The `xsl:output` element is not supported when outputting to an (`xsl:output` is ignored). See [Outputs from an XslTransform](/dotnet/standard/data/xml/outputs-from-an-xsltransform) for more information. + + Transformations apply to the document as a whole. In other words, if you pass in a node other than the document root node, this does not prevent the transformation process from accessing all nodes in the loaded document. To transform a node fragment, you must create an containing just the node fragment and pass that to the method. + + The following example performs a transformation on a node fragment. + +```csharp +XslTransform xslt = new XslTransform(); +xslt.Load("print_root.xsl"); +XmlDocument doc = new XmlDocument(); +doc.Load("library.xml"); +// Create a new document containing just the node fragment. +XmlNode testNode = doc.DocumentElement.FirstChild; +XmlDocument tmpDoc = new XmlDocument(); +tmpDoc.LoadXml(testNode.OuterXml); +// Pass the document containing the node fragment +// to the Transform method. +Console.WriteLine("Passing " + tmpDoc.OuterXml + " to print_root.xsl"); +xslt.Transform(tmpDoc, null, Console.Out, null); +``` + + The example uses the `library.xml` and `print_root.xsl` files as input and outputs the following to the console. + +``` +Passing Pride And Prejudice to print_root.xsl +Root node is book. +``` + + `library.xml` + +```xml + + + Pride And Prejudice + + + Hook + + +``` + + `print_root.xsl` + +```xml + + + + +``` + + + +## Examples + The following example transforms an XML document into an HTML document. It displays the ISBN, title, and price for each book in a table. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/Classic WebData XslTransform.Transform7 Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Xml.Xsl/XslTransform/Load/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/Classic WebData XslTransform.Transform7 Example/VB/source.vb" id="Snippet1"::: - - The sample uses the following two input files. - - `books.xml` - - :::code language="xml" source="~/snippets/xml/VS_Snippets_Data/Classic WebData XslTransform.Transform7 Example/XML/books.xml" id="Snippet2"::: - - `output.xsl` - - :::code language="xml" source="~/snippets/xml/VS_Snippets_Data/Classic WebData XslTransform.Transform7 Example/XML/output.xsl" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/Classic WebData XslTransform.Transform7 Example/VB/source.vb" id="Snippet1"::: + + The sample uses the following two input files. + + `books.xml` + + :::code language="xml" source="~/snippets/xml/VS_Snippets_Data/Classic WebData XslTransform.Transform7 Example/XML/books.xml" id="Snippet2"::: + + `output.xsl` + + :::code language="xml" source="~/snippets/xml/VS_Snippets_Data/Classic WebData XslTransform.Transform7 Example/XML/output.xsl" id="Snippet3"::: + ]]> - There was an error processing the XSLT transformation. - + There was an error processing the XSLT transformation. + Note: This is a change in behavior from earlier versions. An is thrown if you are using Microsoft .NET Framework version 1.1 or earlier. @@ -2925,40 +2925,40 @@ Root node is book. An containing the data to be transformed. An containing the namespace-qualified arguments used as input to the transformation. The stream to which you want to output. - The used to resolve the XSLT document() function. If this is , the document() function is not resolved. - + The used to resolve the XSLT document() function. If this is , the document() function is not resolved. + The is not cached after the method completes. Transforms the XML data in the using the specified and outputs the result to a . - [!NOTE] -> The class is obsolete in the .NET Framework version 2.0. The class is the new XSLT processor. For more information, see [Using the XslCompiledTransform Class](/dotnet/standard/data/xml/using-the-xslcompiledtransform-class) and [Migrating From the XslTransform Class](/dotnet/standard/data/xml/migrating-from-the-xsltransform-class). - - supports the XSLT 1.0 syntax. The XSLT style sheet must include the namespace declaration `xmlns:xsl= http://www.w3.org/1999/XSL/Transform`. - - The `args` are matched with the `xsl:param` elements defined in the style sheet. The transformation selections apply to the document as a whole. In other words, if the current node is set on a node tree other than the document root node, this does not prevent the transformation process from accessing all nodes in the loaded document. After the transformation has been performed, the remains in its original state. This means that the node, which is current before the transformation process, remains the current node after the method has been called. - - See [Outputs from an XslTransform](/dotnet/standard/data/xml/outputs-from-an-xsltransform) for specifics on which `xsl:output` attributes are supported. - - - -## Examples - The following example loads a customer table into an and performs an XSLT transformation to pull the customer data into an HTML table. The example uses the Microsoft SQL Server 2000 Northwind database. - +> The class is obsolete in the .NET Framework version 2.0. The class is the new XSLT processor. For more information, see [Using the XslCompiledTransform Class](/dotnet/standard/data/xml/using-the-xslcompiledtransform-class) and [Migrating From the XslTransform Class](/dotnet/standard/data/xml/migrating-from-the-xsltransform-class). + + supports the XSLT 1.0 syntax. The XSLT style sheet must include the namespace declaration `xmlns:xsl= http://www.w3.org/1999/XSL/Transform`. + + The `args` are matched with the `xsl:param` elements defined in the style sheet. The transformation selections apply to the document as a whole. In other words, if the current node is set on a node tree other than the document root node, this does not prevent the transformation process from accessing all nodes in the loaded document. After the transformation has been performed, the remains in its original state. This means that the node, which is current before the transformation process, remains the current node after the method has been called. + + See [Outputs from an XslTransform](/dotnet/standard/data/xml/outputs-from-an-xsltransform) for specifics on which `xsl:output` attributes are supported. + + + +## Examples + The following example loads a customer table into an and performs an XSLT transformation to pull the customer data into an HTML table. The example uses the Microsoft SQL Server 2000 Northwind database. + :::code language="csharp" source="~/snippets/csharp/System.Xml.Xsl/XslTransform/Transform/dataset_trans.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XmlDataDocument.CreateNavigator/VB/dataset_trans.vb" id="Snippet1"::: - - The example uses the `customers.xsl` file as input. - - :::code language="xml" source="~/snippets/xml/VS_Snippets_Data/XmlDataDocument.CreateNavigator/XML/customers.xsl" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XmlDataDocument.CreateNavigator/VB/dataset_trans.vb" id="Snippet1"::: + + The example uses the `customers.xsl` file as input. + + :::code language="xml" source="~/snippets/xml/VS_Snippets_Data/XmlDataDocument.CreateNavigator/XML/customers.xsl" id="Snippet2"::: + ]]> - There was an error processing the XSLT transformation. - + There was an error processing the XSLT transformation. + Note: This is a change in behavior from earlier versions. An is thrown if you are using Microsoft .NET Framework version 1.1 or earlier. @@ -3025,28 +3025,28 @@ Root node is book. An containing the data to be transformed. An containing the namespace-qualified arguments used as input to the transformation. The to which you want to output. - The used to resolve the XSLT document() function. If this is , the document() function is not resolved. - + The used to resolve the XSLT document() function. If this is , the document() function is not resolved. + The is not cached after the method completes. Transforms the XML data in the using the specified and outputs the result to a . - [!NOTE] -> The class is obsolete in the .NET Framework version 2.0. The class is the new XSLT processor. For more information, see [Using the XslCompiledTransform Class](/dotnet/standard/data/xml/using-the-xslcompiledtransform-class) and [Migrating From the XslTransform Class](/dotnet/standard/data/xml/migrating-from-the-xsltransform-class). - - supports the XSLT 1.0 syntax. The XSLT style sheet must include the namespace declaration `xmlns:xsl= http://www.w3.org/1999/XSL/Transform`. - - The `args` are matched with the `xsl:param` elements defined in the style sheet. The transformation selections apply to the document as a whole. In other words, if the current node is set on a node tree other than the document root node, this does not prevent the transformation process from accessing all nodes in the loaded document. After the transformation is performed, the remains in its original state. This means that the node, which is current before the transformation process, remains the current node after the method has been called. - - The encoding attribute on an `xsl:output` element is not supported when outputting to a . See [Outputs from an XslTransform](/dotnet/standard/data/xml/outputs-from-an-xsltransform) for specifics on which `xsl:output` attributes are supported. - +> The class is obsolete in the .NET Framework version 2.0. The class is the new XSLT processor. For more information, see [Using the XslCompiledTransform Class](/dotnet/standard/data/xml/using-the-xslcompiledtransform-class) and [Migrating From the XslTransform Class](/dotnet/standard/data/xml/migrating-from-the-xsltransform-class). + + supports the XSLT 1.0 syntax. The XSLT style sheet must include the namespace declaration `xmlns:xsl= http://www.w3.org/1999/XSL/Transform`. + + The `args` are matched with the `xsl:param` elements defined in the style sheet. The transformation selections apply to the document as a whole. In other words, if the current node is set on a node tree other than the document root node, this does not prevent the transformation process from accessing all nodes in the loaded document. After the transformation is performed, the remains in its original state. This means that the node, which is current before the transformation process, remains the current node after the method has been called. + + The encoding attribute on an `xsl:output` element is not supported when outputting to a . See [Outputs from an XslTransform](/dotnet/standard/data/xml/outputs-from-an-xsltransform) for specifics on which `xsl:output` attributes are supported. + ]]> - There was an error processing the XSLT transformation. - + There was an error processing the XSLT transformation. + Note: This is a change in behavior from earlier versions. An is thrown if you are using Microsoft .NET Framework version 1.1 or earlier. @@ -3113,37 +3113,37 @@ Root node is book. An containing the data to be transformed. An containing the namespace-qualified arguments used as input to the transformation. The to which you want to output. - The used to resolve the XSLT document() function. If this is , the document() function is not resolved. - + The used to resolve the XSLT document() function. If this is , the document() function is not resolved. + The is not cached after the method completes. Transforms the XML data in the using the specified args and outputs the result to an . - [!NOTE] -> The class is obsolete in the .NET Framework version 2.0. The class is the new XSLT processor. For more information, see [Using the XslCompiledTransform Class](/dotnet/standard/data/xml/using-the-xslcompiledtransform-class) and [Migrating From the XslTransform Class](/dotnet/standard/data/xml/migrating-from-the-xsltransform-class). - - supports the XSLT 1.0 syntax. The XSLT style sheet must include the namespace declaration `xmlns:xsl= http://www.w3.org/1999/XSL/Transform`. - - The `args` are matched with the `xsl:param` elements defined in the style sheet. The transformation selections apply to the document as a whole. In other words, if the current node is set on a node tree other than the document root node, this does not prevent the transformation process from accessing all nodes in the loaded document. After the transformation is performed, the remains in its original state. This means that the node, that is current before the transformation process, remains the current node after the method has been called. - - The `xsl:output` element is not supported when outputting to an (`xsl:output` is ignored). See [Outputs from an XslTransform](/dotnet/standard/data/xml/outputs-from-an-xsltransform) for more information. - - - -## Examples - The following example loads and edits an XML document before performing an XSLT transform. - +> The class is obsolete in the .NET Framework version 2.0. The class is the new XSLT processor. For more information, see [Using the XslCompiledTransform Class](/dotnet/standard/data/xml/using-the-xslcompiledtransform-class) and [Migrating From the XslTransform Class](/dotnet/standard/data/xml/migrating-from-the-xsltransform-class). + + supports the XSLT 1.0 syntax. The XSLT style sheet must include the namespace declaration `xmlns:xsl= http://www.w3.org/1999/XSL/Transform`. + + The `args` are matched with the `xsl:param` elements defined in the style sheet. The transformation selections apply to the document as a whole. In other words, if the current node is set on a node tree other than the document root node, this does not prevent the transformation process from accessing all nodes in the loaded document. After the transformation is performed, the remains in its original state. This means that the node, that is current before the transformation process, remains the current node after the method has been called. + + The `xsl:output` element is not supported when outputting to an (`xsl:output` is ignored). See [Outputs from an XslTransform](/dotnet/standard/data/xml/outputs-from-an-xsltransform) for more information. + + + +## Examples + The following example loads and edits an XML document before performing an XSLT transform. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/XslTransform.Transform2/CPP/trans_snip.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Xml/XmlNode/CreateNavigator/trans_snip.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XslTransform.Transform2/VB/trans_snip.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XslTransform.Transform2/VB/trans_snip.vb" id="Snippet1"::: + ]]> - There was an error processing the XSLT transformation. - + There was an error processing the XSLT transformation. + Note: This is a change in behavior from earlier versions. An is thrown if you are using Microsoft .NET Framework version 1.1 or earlier. @@ -3208,24 +3208,24 @@ Root node is book. Sets the used to resolve external resources when the method is called. The to use during transformation. If set to , the XSLT document() function is not resolved. - [!NOTE] -> The class is obsolete in the .NET Framework version 2.0. The class is the new XSLT processor. For more information, see [Using the XslCompiledTransform Class](/dotnet/standard/data/xml/using-the-xslcompiledtransform-class) and [Migrating From the XslTransform Class](/dotnet/standard/data/xml/migrating-from-the-xsltransform-class). - - In version 1.1 of the .NET Framework, the trust level of the application determines the default behavior: - - `Fully trusted code:` A default with no user credentials is used to resolve the `document()` function. If authentication is required to access the external resource, use this property to specify an with the necessary credentials. - - `Semi-trusted code:` The property is set to `null`, which means the `document()` function is not resolved. Because full trust is required to specify an , this property also cannot be set. - - This resolver is used when the XSLT `document()` function is invoked. It is not used to resolve `xsl:import` and `xsl:include` elements referenced in the style sheet. To specify an to use to resolve `xsl:import` and `xsl:include` elements referenced in the style sheet, use the overload, which takes an as one of its arguments. - +> The class is obsolete in the .NET Framework version 2.0. The class is the new XSLT processor. For more information, see [Using the XslCompiledTransform Class](/dotnet/standard/data/xml/using-the-xslcompiledtransform-class) and [Migrating From the XslTransform Class](/dotnet/standard/data/xml/migrating-from-the-xsltransform-class). + + In version 1.1 of the .NET Framework, the trust level of the application determines the default behavior: + + `Fully trusted code:` A default with no user credentials is used to resolve the `document()` function. If authentication is required to access the external resource, use this property to specify an with the necessary credentials. + + `Semi-trusted code:` The property is set to `null`, which means the `document()` function is not resolved. Because full trust is required to specify an , this property also cannot be set. + + This resolver is used when the XSLT `document()` function is invoked. It is not used to resolve `xsl:import` and `xsl:include` elements referenced in the style sheet. To specify an to use to resolve `xsl:import` and `xsl:include` elements referenced in the style sheet, use the overload, which takes an as one of its arguments. + > [!NOTE] -> This property is obsolete in version 1.1 of the .NET Framework. Specifying an using the method is the recommended practice. In this case, the is not cached after the method completes. - +> This property is obsolete in version 1.1 of the .NET Framework. Specifying an using the method is the recommended practice. In this case, the is not cached after the method completes. + ]]> diff --git a/xml/System.Xml/XmlConvert.xml b/xml/System.Xml/XmlConvert.xml index 9f6fa699eac..271446b477b 100644 --- a/xml/System.Xml/XmlConvert.xml +++ b/xml/System.Xml/XmlConvert.xml @@ -444,7 +444,7 @@ System.Boolean - + The character to verify as a non-colon character. @@ -487,7 +487,7 @@ System.Boolean - + @@ -530,7 +530,7 @@ System.Boolean - + The character to validate. @@ -580,7 +580,7 @@ System.Boolean - + The character to validate. @@ -630,7 +630,7 @@ System.Boolean - + The character to validate. @@ -680,8 +680,8 @@ System.Boolean - - + + The surrogate character to validate. @@ -907,7 +907,7 @@ System.DateTime - + The string to convert. @@ -977,8 +977,8 @@ System.DateTime - - + + [System.Diagnostics.CodeAnalysis.StringSyntax("DateTimeFormat")] @@ -1038,8 +1038,8 @@ System.DateTime - - + + [System.Diagnostics.CodeAnalysis.StringSyntax("DateTimeFormat")] @@ -2045,7 +2045,7 @@ System.String - + The value to convert. @@ -2780,8 +2780,8 @@ System.String - - + + [System.Diagnostics.CodeAnalysis.StringSyntax("DateTimeFormat")] @@ -3461,7 +3461,7 @@ catch(Exception e) { - + The string value you wish to verify. diff --git a/xml/System.Xml/XmlDictionaryReader.xml b/xml/System.Xml/XmlDictionaryReader.xml index 6c781ff8e87..6638c3d17d0 100644 --- a/xml/System.Xml/XmlDictionaryReader.xml +++ b/xml/System.Xml/XmlDictionaryReader.xml @@ -54,15 +54,15 @@ An class that the Windows Communication Foundation (WCF) derives from to do serialization and deserialization. - objects. - - This class is derived from . - - Note that there is a known issue with the normalization of linefeed characters inside of CDATA sections that you may encounter. - + objects. + + This class is derived from . + + Note that there is a known issue with the normalization of linefeed characters inside of CDATA sections that you may encounter. + ]]> @@ -102,11 +102,11 @@ Creates an instance of this class. Invoked only by its derived classes. - @@ -150,11 +150,11 @@ This property always returns . Its derived classes can override to return if they support canonicalization. Returns . - @@ -167,11 +167,11 @@ Creates an instance of that can read .NET Binary XML Format. - that can read .NET Binary XML Format. - + that can read .NET Binary XML Format. + ]]> @@ -221,11 +221,11 @@ Creates an instance of that can read .NET Binary XML Format. An instance of . - properties are set to default values or `null`. - + properties are set to default values or `null`. + ]]> @@ -277,11 +277,11 @@ Creates an instance of that can read .NET Binary XML Format. An instance of . - properties are set to default values or `null`. - + properties are set to default values or `null`. + ]]> @@ -344,11 +344,11 @@ Creates an instance of that can read .NET Binary XML Format. An instance of . - properties are set to default values or `null`. - + properties are set to default values or `null`. + ]]> @@ -404,11 +404,11 @@ Creates an instance of that can read .NET Binary XML Format. An instance of . - properties are set to default values or `null`. - + properties are set to default values or `null`. + ]]> @@ -487,11 +487,11 @@ Creates an instance of that can read .NET Binary XML Format. An instance of . - properties are set to default values or `null`. - + properties are set to default values or `null`. + ]]> @@ -558,11 +558,11 @@ Creates an instance of that can read .NET Binary XML Format. An instance of . - properties are set to default values or `null`. - + properties are set to default values or `null`. + ]]> @@ -610,8 +610,8 @@ System.Xml.XmlDictionaryReader - - + + [System.Runtime.CompilerServices.Nullable(2)] @@ -619,8 +619,8 @@ - - + + [System.Runtime.CompilerServices.Nullable(2)] @@ -628,7 +628,7 @@ - + [System.Runtime.CompilerServices.Nullable(2)] @@ -649,11 +649,11 @@ Creates an instance of that can read .NET Binary XML Format. An instance of . - properties are set to default values or `null`. - + properties are set to default values or `null`. + ]]> @@ -728,11 +728,11 @@ Creates an instance of that can read .NET Binary XML Format. An instance of . - properties are set to default values or `null`. - + properties are set to default values or `null`. + ]]> @@ -780,10 +780,10 @@ System.Xml.XmlDictionaryReader - - - - + + + + [System.Runtime.CompilerServices.Nullable(2)] @@ -791,8 +791,8 @@ - - + + [System.Runtime.CompilerServices.Nullable(2)] @@ -800,7 +800,7 @@ - + [System.Runtime.CompilerServices.Nullable(2)] @@ -820,11 +820,11 @@ Creates an instance of that can read .NET Binary XML Format. An instance of . - properties are set to default values or `null`. - + properties are set to default values or `null`. + ]]> @@ -893,11 +893,11 @@ Creates an instance of that reads XML in the MTOM format. - @@ -936,9 +936,9 @@ System.Xml.XmlDictionaryReader - - - + + + The stream from which to read. @@ -947,11 +947,11 @@ Creates an instance of that reads XML in the MTOM format. An instance of . - . - + . + ]]> @@ -992,9 +992,9 @@ System.Xml.XmlDictionaryReader - - - + + + The stream from which to read. @@ -1003,11 +1003,11 @@ Creates an instance of that reads XML in the MTOM format. An instance of . - . - + . + ]]> @@ -1049,9 +1049,9 @@ System.Xml.XmlDictionaryReader - - - + + + [System.Runtime.CompilerServices.Nullable(2)] @@ -1059,7 +1059,7 @@ - + The stream from which to read. @@ -1069,11 +1069,11 @@ Creates an instance of that reads XML in the MTOM format. An instance of . - . The message is of the specified MIME type. If `contentType` is `null`, the Content-Type MIME header must be present in the message. - + . The message is of the specified MIME type. If `contentType` is `null`, the Content-Type MIME header must be present in the message. + ]]> @@ -1112,11 +1112,11 @@ System.Xml.XmlDictionaryReader - - - - - + + + + + The buffer from which to read. @@ -1127,11 +1127,11 @@ Creates an instance of that reads XML in the MTOM format. An instance of . - . - + . + ]]> @@ -1172,11 +1172,11 @@ System.Xml.XmlDictionaryReader - - - - - + + + + + The buffer from which to read. @@ -1187,11 +1187,11 @@ Creates an instance of that reads XML in the MTOM format. An instance of . - . - + . + ]]> @@ -1231,11 +1231,11 @@ System.Xml.XmlDictionaryReader - - - - - + + + + + [System.Runtime.CompilerServices.Nullable(2)] @@ -1243,7 +1243,7 @@ - + The buffer from which to read. @@ -1255,11 +1255,11 @@ Creates an instance of that reads XML in the MTOM format. An instance of . - . The message is of the specified MIME type. If `contentType` is `null`, the Content-Type MIME header must be present in the message. - + . The message is of the specified MIME type. If `contentType` is `null`, the Content-Type MIME header must be present in the message. + ]]> @@ -1299,9 +1299,9 @@ System.Xml.XmlDictionaryReader - - - + + + [System.Runtime.CompilerServices.Nullable(2)] @@ -1309,9 +1309,9 @@ - - - + + + [System.Runtime.CompilerServices.Nullable(2)] @@ -1330,11 +1330,11 @@ Creates an instance of that reads XML in the MTOM format. An instance of . - . The message is of the specified MIME type. If `contentType` is `null`, the Content-Type MIME header must be present in the message. - + . The message is of the specified MIME type. If `contentType` is `null`, the Content-Type MIME header must be present in the message. + ]]> @@ -1374,11 +1374,11 @@ System.Xml.XmlDictionaryReader - - - - - + + + + + [System.Runtime.CompilerServices.Nullable(2)] @@ -1386,9 +1386,9 @@ - - - + + + [System.Runtime.CompilerServices.Nullable(2)] @@ -1409,11 +1409,11 @@ Creates an instance of that reads XML in the MTOM format. An instance of . - . The message is of the specified MIME type. If `contentType` is `null`, the Content-Type MIME header must be present in the message. - + . The message is of the specified MIME type. If `contentType` is `null`, the Content-Type MIME header must be present in the message. + ]]> @@ -1426,11 +1426,11 @@ Creates an instance of . - . - + . + ]]> @@ -1480,11 +1480,11 @@ Creates an instance of . An instance of . - @@ -1536,11 +1536,11 @@ Creates an instance of . An instance of . - @@ -1594,11 +1594,11 @@ Creates an instance of . An instance of . - @@ -1667,11 +1667,11 @@ Creates an instance of . An instance of . - @@ -1711,10 +1711,10 @@ System.Xml.XmlDictionaryReader - - - - + + + + [System.Runtime.CompilerServices.Nullable(2)] @@ -1722,8 +1722,8 @@ - - + + [System.Runtime.CompilerServices.Nullable(2)] @@ -1742,11 +1742,11 @@ Creates an instance of . An instance of . - @@ -1874,8 +1874,8 @@ System.Void - - + + The local name. @@ -1939,11 +1939,11 @@ Gets the index of the local name of the current node within an array of names. The index of the local name of the current node within an array of names. - @@ -1999,11 +1999,11 @@ Gets the index of the local name of the current node within an array of names. The index of the local name of the current node within an array of names. - , and `namespaceUri` is an . - + , and `namespaceUri` is an . + ]]> @@ -3891,11 +3891,11 @@ Reads repeated occurrences of nodes into a typed array. A array of the nodes. - @@ -3945,11 +3945,11 @@ Reads repeated occurrences of nodes into a typed array. A array of the nodes. - @@ -4049,11 +4049,11 @@ Reads the content and returns the Base64 decoded binary bytes. A byte array that contains the Base64 decoded binary bytes. - The array size is greater than the MaxArrayLength quota for this reader. @@ -4109,11 +4109,11 @@ Reads the content and returns the decoded binary bytes. A byte array that contains the decoded binary bytes. - The array size is greater than Int32.MaxValue. @@ -4436,11 +4436,11 @@ Converts a node's content to a string. The node content in a string representation. - @@ -4488,11 +4488,11 @@ Converts a node's content to a string. Node content in string representation. - @@ -4743,11 +4743,11 @@ An entry in is . Converts a node's content to a array. The node's content represented as a array. - @@ -4854,11 +4854,11 @@ An entry in is . Converts a node's content to a array. The node's content represented as a array. - @@ -4908,11 +4908,11 @@ An entry in is . Converts a node's content to a array. The node's content represented as a array. - @@ -4972,11 +4972,11 @@ An entry in is .
Converts a node's content to a array. The node's content represented as a array. -
@@ -5026,11 +5026,11 @@ An entry in is .
Converts a node's content to a array. The node's content represented as a array. -
@@ -5075,11 +5075,11 @@ An entry in is .
Converts a node's content to a array of Base64 bytes. The node's content represented as an array of Base64 bytes. -
@@ -5124,11 +5124,11 @@ An entry in is .
Converts a node's content to an array of bytes. The node's content represented as an array of bytes. -
@@ -5511,11 +5511,11 @@ An entry in is .
Converts an element's content to a . The node's content represented as a . -
@@ -5856,11 +5856,11 @@ An entry in is .
Reads the contents of a series of nodes with the given and into an array of . An array of . -
@@ -5910,11 +5910,11 @@ An entry in is .
Reads the contents of a series of nodes with the given and into an array of . An array of . -
@@ -5974,11 +5974,11 @@ An entry in is .
Reads the contents of a series of nodes with the given and into an array of integers (). An array of integers (). -
@@ -6028,11 +6028,11 @@ An entry in is .
Reads the contents of a series of nodes with the given and into an array of integers (). An array of integers (). -
@@ -6092,11 +6092,11 @@ An entry in is .
Reads the contents of a series of nodes with the given and into an array of integers (). An array of integers (). -
@@ -6146,11 +6146,11 @@ An entry in is .
Reads the contents of a series of nodes with the given and into an array of integers (). An array of integers (). -
@@ -6210,11 +6210,11 @@ An entry in is .
Reads the contents of a series of nodes with the given and into an array of integers (). An array of integers (). -
@@ -6264,11 +6264,11 @@ An entry in is .
Reads the contents of a series of nodes with the given and into an array of integers (). An array of integers (). -
@@ -6328,11 +6328,11 @@ An entry in is .
Reads the contents of a series of nodes with the given and into an array of numbers (). An array of numbers (). -
@@ -6382,11 +6382,11 @@ An entry in is .
Reads the contents of a series of nodes with the given and into an array of numbers (). An array of numbers (). -
@@ -6523,7 +6523,7 @@ An entry in is .
System.String - + Maximum allowed string length. @@ -6589,11 +6589,11 @@ An entry in is .
Reads the contents of a series of nodes with the given and into a array. A array. - @@ -6643,11 +6643,11 @@ An entry in is .
Reads the contents of a series of nodes with the given and into a array. A array. - @@ -6756,11 +6756,11 @@ An entry in is .
The prefixes to be included. This method is not yet implemented. - Always. diff --git a/xml/System.Xml/XmlDictionaryWriter.xml b/xml/System.Xml/XmlDictionaryWriter.xml index 18f56107cb8..2941bb1f5b3 100644 --- a/xml/System.Xml/XmlDictionaryWriter.xml +++ b/xml/System.Xml/XmlDictionaryWriter.xml @@ -54,13 +54,13 @@ Represents an abstract class that Windows Communication Foundation (WCF) derives from to do serialization and deserialization. - @@ -100,11 +100,11 @@ Initializes a new instance of the class. - @@ -149,11 +149,11 @@ in all cases. - can canonicalize the XML content being written to it, according to the Exclusive XML Canonicalization rules as defined in [Exclusive XML Canonicalization Version 1.0](https://go.microsoft.com/fwlink/?LinkId=96655). - + can canonicalize the XML content being written to it, according to the Exclusive XML Canonicalization rules as defined in [Exclusive XML Canonicalization Version 1.0](https://go.microsoft.com/fwlink/?LinkId=96655). + ]]> @@ -166,25 +166,25 @@ Creates an instance of that writes WCF binary XML format. - @@ -476,11 +476,11 @@ binarywriter.WriteEndAttribute(); Creates an instance of that writes XML in the Message Transmission Optimization Mechanism (MTOM) format. - @@ -519,10 +519,10 @@ binarywriter.WriteEndAttribute(); System.Xml.XmlDictionaryWriter - - - - + + + + The stream to write to. @@ -569,11 +569,11 @@ binarywriter.WriteEndAttribute(); System.Xml.XmlDictionaryWriter - - - - - + + + + + [System.Runtime.CompilerServices.Nullable(2)] @@ -581,7 +581,7 @@ binarywriter.WriteEndAttribute(); - + [System.Runtime.CompilerServices.Nullable(2)] @@ -589,8 +589,8 @@ binarywriter.WriteEndAttribute(); - - + + The stream to write to. @@ -661,11 +661,11 @@ binarywriter.WriteEndAttribute(); Creates an instance of that writes text XML. An instance of . - @@ -715,11 +715,11 @@ binarywriter.WriteEndAttribute(); Creates an instance of that writes text XML. An instance of . - . - + . + ]]> @@ -813,11 +813,11 @@ binarywriter.WriteEndAttribute(); When implemented by a derived class, it stops the canonicalization started by the matching call. - Method is not implemented yet. @@ -878,11 +878,11 @@ binarywriter.WriteEndAttribute(); The prefixes to be included. When implemented by a derived class, it starts the canonicalization. - Method is not implemented yet. @@ -2607,9 +2607,9 @@ binarywriter.WriteEndAttribute(); System.Threading.Tasks.Task - - - + + + Byte array to encode. @@ -2618,11 +2618,11 @@ binarywriter.WriteEndAttribute(); Asynchronously encodes the specified binary bytes as Base64 and writes out the resulting text. The task that represents the asynchronous operation. - flag to `true`. - + flag to `true`. + ]]> An method was called before a previous asynchronous operation finished. In this case, is thrown with the message "An asynchronous operation is already in progress." @@ -2930,13 +2930,13 @@ An asynchronous method was calle The namespace URI of the qualified name. Writes out the namespace-qualified name. This method looks up the prefix that is in scope for the given namespace. - @@ -3293,11 +3293,11 @@ An asynchronous method was calle to indicate that the reader is positioned on an attribute value or element content; otherwise, . Writes the text node that an is currently positioned on. - @@ -3434,19 +3434,19 @@ An asynchronous method was calle System.Void - + The value to write. Writes a value from an . - . - + . + ]]> @@ -3586,18 +3586,18 @@ An asynchronous method was calle System.Threading.Tasks.Task - + The value to write. Asynchronously writes a value from an . The task that represents the asynchronous operation. - , with the same functionality. To use this method, you must set the flag to `true`. - + , with the same functionality. To use this method, you must set the flag to `true`. + 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 . ]]> @@ -3619,11 +3619,11 @@ An asynchronous method was calle Writes a standard XML attribute in the current element. - diff --git a/xml/System.Xml/XmlDocument.xml b/xml/System.Xml/XmlDocument.xml index 0e2c5fb8c02..89757ddd165 100644 --- a/xml/System.Xml/XmlDocument.xml +++ b/xml/System.Xml/XmlDocument.xml @@ -767,7 +767,7 @@ System.Xml.XmlAttribute - + [System.Runtime.CompilerServices.Nullable(2)] @@ -775,8 +775,8 @@ - - + + [System.Runtime.CompilerServices.Nullable(2)] @@ -908,7 +908,7 @@ System.Xml.XmlDocumentType - + [System.Runtime.CompilerServices.Nullable(1)] @@ -916,9 +916,9 @@ - - - + + + Name of the document type. @@ -1255,7 +1255,7 @@ elem=doc.CreateElement("xy", "item", "urn:abc"); System.Xml.XmlEntityReference - + The name of the entity reference. @@ -1418,7 +1418,7 @@ elem=doc.CreateElement("xy", "item", "urn:abc"); System.Xml.XPath.XPathNavigator - + The you want the navigator initially positioned on. @@ -2368,7 +2368,7 @@ elem=doc.CreateElement("xy", "item", "urn:abc"); System.Xml.XmlElement - + The attribute ID to match. @@ -3169,7 +3169,7 @@ elem=doc.CreateElement("xy", "item", "urn:abc"); System.Void - + URL for the file containing the XML document to load. The URL can be either a local file or an HTTP URL (a Web address). @@ -4400,7 +4400,7 @@ doc.Save(Console.Out); System.Void - + The location of the file where you want to save the document. @@ -4697,7 +4697,7 @@ doc.Save(Console.Out); System.Void - + The object that receives information about schema validation warnings and errors. @@ -4776,7 +4776,7 @@ doc.Save(Console.Out); System.Void - + [System.Runtime.CompilerServices.Nullable(2)] @@ -4784,7 +4784,7 @@ doc.Save(Console.Out); - + The object that receives information about schema validation warnings and errors. diff --git a/xml/System.Xml/XmlException.xml b/xml/System.Xml/XmlException.xml index d1aa3ba4b25..9efc7b4bba6 100644 --- a/xml/System.Xml/XmlException.xml +++ b/xml/System.Xml/XmlException.xml @@ -124,12 +124,12 @@ Initializes a new instance of the class. - end tag is misspelled: - + :::code language="csharp" source="~/snippets/csharp/System.Xml/XmlException/Program.cs"::: :::code language="vb" source="~/snippets/visualbasic/api/system.xml/xmlexception/Program.vb"::: @@ -233,8 +233,8 @@ The `XmlException` is a generic XML-related error that is thrown if problems occ - - + + The object containing all the properties of an . @@ -400,8 +400,8 @@ The `XmlException` is a generic XML-related error that is thrown if problems occ System.Void - - + + The object. diff --git a/xml/System.Xml/XmlNode.xml b/xml/System.Xml/XmlNode.xml index a69d99d0675..751e0668a18 100644 --- a/xml/System.Xml/XmlNode.xml +++ b/xml/System.Xml/XmlNode.xml @@ -85,14 +85,14 @@ Represents a single node in the XML document. - class extends `XmlNode` and represents an XML document. You can use `XmlDocument` to load and save XML data. It also includes methods for node creation. See [XML Document Object Model (DOM)](/dotnet/standard/data/xml/xml-document-object-model-dom) for more information. - + class extends `XmlNode` and represents an XML document. You can use `XmlDocument` to load and save XML data. It also includes methods for node creation. See [XML Document Object Model (DOM)](/dotnet/standard/data/xml/xml-document-object-model-dom) for more information. + > [!IMPORTANT] -> Exceptions raised as a result of using the class, such as the class may contain sensitive information that should not be exposed in untrusted scenarios. Exceptions should be properly handled so that this sensitive information is not exposed in untrusted scenarios. - +> Exceptions raised as a result of using the class, such as the class may contain sensitive information that should not be exposed in untrusted scenarios. Exceptions should be properly handled so that this sensitive information is not exposed in untrusted scenarios. + ]]> @@ -147,39 +147,39 @@ Adds the specified node to the end of the list of child nodes, of this node. The node added. - to import the node to the current document. The imported node can then be inserted into the current document. - - - -## Examples - The following example adds a new node to the XML document. - + to import the node to the current document. The imported node can then be inserted into the current document. + + + +## Examples + The following example adds a new node to the XML document. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/Classic WebData XmlNode.AppendChild Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Xml/XmlNode/AppendChild/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/Classic WebData XmlNode.AppendChild Example/VB/source.vb" id="Snippet1"::: - - **Output:** - -``` -Display the modified XML... - - - Pride And Prejudice - 19.95 -``` - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/Classic WebData XmlNode.AppendChild Example/VB/source.vb" id="Snippet1"::: + + **Output:** + +``` +Display the modified XML... + + + Pride And Prejudice + 19.95 +``` + ]]> - This node is of a type that does not allow child nodes of the type of the node. - + This node is of a type that does not allow child nodes of the type of the node. + The is an ancestor of this node. - The was created from a different document than the one that created this node. - + The was created from a different document than the one that created this node. + This node is read-only. When overriding in a derived class, in order for events to be raised correctly, you must call the method of the base class. @@ -240,19 +240,19 @@ Display the modified XML... Gets an containing the attributes of this node. - An containing the attributes of the node. - + An containing the attributes of the node. + If the node is of type XmlNodeType.Element, the attributes of the node are returned. Otherwise, this property returns . - @@ -300,68 +300,68 @@ Display the modified XML... Gets the base URI of the current node. The location from which the node was loaded or String.Empty if the node has no base URI. - object. Nodes which are child nodes of external EntityReference nodes return the location of the entity itself. For example, consider the following XML document: - -```xml - -]> -&xyz; -``` - - where the external entity `a/b.xml` contains the XML text: `123`. - - If the document is loaded from `http://server/mydata.xml`, `BaseURI` returns the following: - -|NodeType|Name|BaseURI| -|--------------|----------|-------------| -|Attribute|num|`http://server/mydata.xml`| -|Document|#document|`http://server/mydata.xml`| -|DocumentType|item|`http://server/mydata.xml`| -|Entity|xyz|`http://server/mydata.xml`| -|Element|item|`http://server/mydata.xml`| -|EntityReference|xyz|`http://server/mydata.xml`| -|Element|test|`http://server/a/b.xml`| -|Text|#text|`http://server/a/b.xml`| - - `BaseURI` looks for entity reference boundaries, so if entities are expanded this information is not preserved and this property returns the location of the `XmlDocument` object in all cases. - - As a second example, given the following XML document: - -```xml - -&xyz; -``` - - where the DTD file contains the following: - -``` -My Data - - -``` - - If the XML document is loaded from `http://localhost/mydata.xml`, `BaseURI` returns the following for each of the nodes: - -|NodeType|Name|BaseURI| -|--------------|----------|-------------| -|Document|#document|`http://localhost/mydata.xml`| -|DocumentType|Mydata|`http://localhost/mydata.xml`

The or properties can be used to identify where the DTD file was loaded from.| -|Element|baa|`http://localhost/mydata.xml`| -|Entity|xyz|`http://localhost/doctype.dtd`| -|EntityReference|xyz|`http://localhost/mydata.xml`| -|Attribute|woof|`http://localhost/mydata.xml`| - + object. Nodes which are child nodes of external EntityReference nodes return the location of the entity itself. For example, consider the following XML document: + +```xml + +]> +&xyz; +``` + + where the external entity `a/b.xml` contains the XML text: `123`. + + If the document is loaded from `http://server/mydata.xml`, `BaseURI` returns the following: + +|NodeType|Name|BaseURI| +|--------------|----------|-------------| +|Attribute|num|`http://server/mydata.xml`| +|Document|#document|`http://server/mydata.xml`| +|DocumentType|item|`http://server/mydata.xml`| +|Entity|xyz|`http://server/mydata.xml`| +|Element|item|`http://server/mydata.xml`| +|EntityReference|xyz|`http://server/mydata.xml`| +|Element|test|`http://server/a/b.xml`| +|Text|#text|`http://server/a/b.xml`| + + `BaseURI` looks for entity reference boundaries, so if entities are expanded this information is not preserved and this property returns the location of the `XmlDocument` object in all cases. + + As a second example, given the following XML document: + +```xml + +&xyz; +``` + + where the DTD file contains the following: + +``` +My Data + + +``` + + If the XML document is loaded from `http://localhost/mydata.xml`, `BaseURI` returns the following for each of the nodes: + +|NodeType|Name|BaseURI| +|--------------|----------|-------------| +|Document|#document|`http://localhost/mydata.xml`| +|DocumentType|Mydata|`http://localhost/mydata.xml`

The or properties can be used to identify where the DTD file was loaded from.| +|Element|baa|`http://localhost/mydata.xml`| +|Entity|xyz|`http://localhost/doctype.dtd`| +|EntityReference|xyz|`http://localhost/mydata.xml`| +|Attribute|woof|`http://localhost/mydata.xml`| + > [!NOTE] -> The base URI of a default attribute is the same as the base URI of the element to which they belong. - - This property is a Microsoft extension to the Document Object Model (DOM). - +> The base URI of a default attribute is the same as the base URI of the element to which they belong. + + This property is a Microsoft extension to the Document Object Model (DOM). + ]]>
@@ -407,24 +407,24 @@ Display the modified XML... Gets all the child nodes of the node. - An object that contains all the child nodes of the node. - + An object that contains all the child nodes of the node. + If there are no child nodes, this property returns an empty . - @@ -477,45 +477,45 @@ Display the modified XML... Creates a duplicate of this node. The cloned node. - copies all attributes and their values, including those generated by the XML processor to represent defaulted attributes. This method recursively clones the node and the subtree underneath it. - - `Clone` is equivalent to calling `CloneNode(true)`. - - The following table describes the specific behavior for each . - -|XmlNodeType|Clone| -|-----------------|-----------| -|Attribute|Clones the attribute node, including child nodes.| -|CData|Clones the CData node, including its data content.| -|Comment|Clones the comment node, including its text content.| -|Document|Clones the document node, including any child nodes.| -|DocumentFragment|Clones the document fragment node, including any child nodes.| -|DocumentType|Clones the document type node.| -|Element|Clones the element node, its attributes, and any child nodes.| -|Entity|Entity nodes cannot be cloned.| -|EntityReference|Clones the entity reference node. The replacement text is not included.| -|Notation|Notation nodes cannot be cloned.| -|ProcessingInstruction|Clones the processing instruction node, including its target and data.| -|SignificantWhitespace|Clones the significant white space node, including its data value.| -|Text|Clones the text node, including its data value.| -|Whitespace|Clones the white space node, including its data value.| -|XmlDeclaration|Clones the XmlDeclaration node, including its data value.| -|All other node types.|These node types cannot be cloned.| - - This method is a Microsoft extension to the Document Object Model (DOM). - - - -## Examples - The following example clones the root node of the XML document. - + copies all attributes and their values, including those generated by the XML processor to represent defaulted attributes. This method recursively clones the node and the subtree underneath it. + + `Clone` is equivalent to calling `CloneNode(true)`. + + The following table describes the specific behavior for each . + +|XmlNodeType|Clone| +|-----------------|-----------| +|Attribute|Clones the attribute node, including child nodes.| +|CData|Clones the CData node, including its data content.| +|Comment|Clones the comment node, including its text content.| +|Document|Clones the document node, including any child nodes.| +|DocumentFragment|Clones the document fragment node, including any child nodes.| +|DocumentType|Clones the document type node.| +|Element|Clones the element node, its attributes, and any child nodes.| +|Entity|Entity nodes cannot be cloned.| +|EntityReference|Clones the entity reference node. The replacement text is not included.| +|Notation|Notation nodes cannot be cloned.| +|ProcessingInstruction|Clones the processing instruction node, including its target and data.| +|SignificantWhitespace|Clones the significant white space node, including its data value.| +|Text|Clones the text node, including its data value.| +|Whitespace|Clones the white space node, including its data value.| +|XmlDeclaration|Clones the XmlDeclaration node, including its data value.| +|All other node types.|These node types cannot be cloned.| + + This method is a Microsoft extension to the Document Object Model (DOM). + + + +## Examples + The following example clones the root node of the XML document. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/Classic WebData XmlNode.Clone Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Xml/XmlNode/Clone/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/Classic WebData XmlNode.Clone Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/Classic WebData XmlNode.Clone Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -569,41 +569,41 @@ Display the modified XML... Creates a duplicate of the node, when overridden in a derived class. The cloned node. - returns `null`). - - The following table describes the specific behavior for each . - -|XmlNodeType|CloneNode(true)|CloneNode(false)| -|-----------------|-----------------------|------------------------| -|Attribute|Clones the attribute node, including child nodes.|Clones the attribute node, including child nodes.| -|CData|Clones the CData node, including its data content.|Clones the CData node, including its data content.| -|Comment|Clones the comment node, including its text content.|Clones the comment node, including its text content.| -|Document|Clones the document node, including any child nodes.|Clones the document node.| -|DocumentFragment|Clones the document fragment node, including any child nodes.|Clones the document fragment node.| -|DocumentType|Clones the document type node.|Clones the document type node.| -|Element|Clones the element node, its attributes, and any child nodes.|Clones the element node and its attributes, including any default attributes.| -|Entity|Entity nodes cannot be cloned.|Entity nodes cannot be cloned.| -|EntityReference|Clones the entity reference node. The replacement text is not included.|Clones the entity reference node. The replacement text is not included.| -|Notation|Notation nodes cannot be cloned.|Notation nodes cannot be cloned.| -|ProcessingInstruction|Clones the processing instruction node, including its target and data.|Clones the processing instruction node, including its target and data.| -|SignificantWhitespace|Clones the significant white space node, including its data value.|Clones the significant white space node, including its data value.| -|Text|Clones the text node, including its data value.|Clones the text node, including its data value.| -|Whitespace|Clones the white space node, including its data value.|Clones the white space node, including its data value.| -|XmlDeclaration|Clones the XmlDeclaration node, including its data value.|Clones the XmlDeclaration node, including its data value.| -|All other node types.|These node types cannot be cloned.|These node types cannot be cloned.| - - - -## Examples - The following example shows the difference between a deep and shallow clone. - + returns `null`). + + The following table describes the specific behavior for each . + +|XmlNodeType|CloneNode(true)|CloneNode(false)| +|-----------------|-----------------------|------------------------| +|Attribute|Clones the attribute node, including child nodes.|Clones the attribute node, including child nodes.| +|CData|Clones the CData node, including its data content.|Clones the CData node, including its data content.| +|Comment|Clones the comment node, including its text content.|Clones the comment node, including its text content.| +|Document|Clones the document node, including any child nodes.|Clones the document node.| +|DocumentFragment|Clones the document fragment node, including any child nodes.|Clones the document fragment node.| +|DocumentType|Clones the document type node.|Clones the document type node.| +|Element|Clones the element node, its attributes, and any child nodes.|Clones the element node and its attributes, including any default attributes.| +|Entity|Entity nodes cannot be cloned.|Entity nodes cannot be cloned.| +|EntityReference|Clones the entity reference node. The replacement text is not included.|Clones the entity reference node. The replacement text is not included.| +|Notation|Notation nodes cannot be cloned.|Notation nodes cannot be cloned.| +|ProcessingInstruction|Clones the processing instruction node, including its target and data.|Clones the processing instruction node, including its target and data.| +|SignificantWhitespace|Clones the significant white space node, including its data value.|Clones the significant white space node, including its data value.| +|Text|Clones the text node, including its data value.|Clones the text node, including its data value.| +|Whitespace|Clones the white space node, including its data value.|Clones the white space node, including its data value.| +|XmlDeclaration|Clones the XmlDeclaration node, including its data value.|Clones the XmlDeclaration node, including its data value.| +|All other node types.|These node types cannot be cloned.|These node types cannot be cloned.| + + + +## Examples + The following example shows the difference between a deep and shallow clone. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/Classic WebData XmlNode.CloneNode Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Xml/XmlNode/CloneNode/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/Classic WebData XmlNode.CloneNode Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/Classic WebData XmlNode.CloneNode Example/VB/source.vb" id="Snippet1"::: + ]]> Calling this method on a node type that cannot be cloned. @@ -663,22 +663,22 @@ Display the modified XML... Creates an for navigating this object. An object used to navigate the node. The is positioned on the node from which the method was called. It is not positioned on the root of the document. - method. - - This method is a Microsoft extension to the Document Object Model (DOM). - - - -## Examples - The following example loads and edits an XML document before performing an XSLT transform. - + method. + + This method is a Microsoft extension to the Document Object Model (DOM). + + + +## Examples + The following example loads and edits an XML document before performing an XSLT transform. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/XslTransform.Transform2/CPP/trans_snip.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Xml/XmlNode/CreateNavigator/trans_snip.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XslTransform.Transform2/VB/trans_snip.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XslTransform.Transform2/VB/trans_snip.vb" id="Snippet1"::: + ]]> @@ -742,20 +742,20 @@ Display the modified XML... Gets the first child of the node. The first child of the node. If there is no such node, is returned. -
@@ -804,26 +804,26 @@ Display the modified XML... Gets an enumerator that iterates through the child nodes in the current node. An object that can be used to iterate through the child nodes in the current node. -
@@ -875,20 +875,20 @@ Display the modified XML... Looks up the closest **xmlns** declaration for the given prefix that is in scope for the current node and returns the namespace URI in the declaration. The namespace URI of the specified prefix. -
@@ -940,20 +940,20 @@ Display the modified XML... Looks up the closest **xmlns** declaration for the given namespace URI that is in scope for the current node and returns the prefix defined in that declaration. The prefix for the specified namespace URI. -
@@ -1002,20 +1002,20 @@ Display the modified XML... if the node has child nodes; otherwise, . -
@@ -1063,36 +1063,36 @@ Display the modified XML... Gets or sets the concatenated values of the node and all its child nodes. The concatenated values of the node and all its child nodes. - property. - - This property is a Microsoft extension to the Document Object Model (DOM). - - - -## Examples - The following example compares the `InnerText` and properties. - + property. + + This property is a Microsoft extension to the Document Object Model (DOM). + + + +## Examples + The following example compares the `InnerText` and properties. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/Classic WebData XmlNode.InnerText Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Xml/XmlNode/InnerText/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/Classic WebData XmlNode.InnerText Example/VB/source.vb" id="Snippet1"::: - - **Output:** - -``` -Display the InnerText of the element... -some textmore text -Display the InnerXml of the element... -some textmore text -Text containing <markup/> will have char(<) and char(>) escape -d. -Text containing . -``` - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/Classic WebData XmlNode.InnerText Example/VB/source.vb" id="Snippet1"::: + + **Output:** + +``` +Display the InnerText of the element... +some textmore text +Display the InnerXml of the element... +some textmore text +Text containing <markup/> will have char(<) and char(>) escape +d. +Text containing . +``` + ]]> @@ -1140,23 +1140,23 @@ d. Gets or sets the markup representing only the child nodes of this node. The markup of the child nodes of this node, not including default attributes. - [!NOTE] > `InnerXml` is not an efficient way to modify the DOM. There may be performance issues when replacing complex nodes. It is more efficient to construct nodes and use methods such as `InsertBefore`, `InsertAfter`, `AppendChild`, and `RemoveChild` to modify the Xml document. - -## Examples - The following example compares the and `InnerXml` properties. - + +## Examples + The following example compares the and `InnerXml` properties. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/Classic WebData XmlNode.InnerText Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Xml/XmlNode/InnerText/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/Classic WebData XmlNode.InnerText Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/Classic WebData XmlNode.InnerText Example/VB/source.vb" id="Snippet1"::: + ]]> Setting this property on a node that cannot have child nodes. @@ -1226,33 +1226,33 @@ d. Inserts the specified node immediately after the specified reference node. The node being inserted. - to import the node to the current document. The imported node can then be inserted into the current document. - - This method is a Microsoft extension to the Document Object Model (DOM). - - - -## Examples - The following example adds a new node to the XML document. - + to import the node to the current document. The imported node can then be inserted into the current document. + + This method is a Microsoft extension to the Document Object Model (DOM). + + + +## Examples + The following example adds a new node to the XML document. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/Classic WebData XmlNode.InsertAfter Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Xml/XmlNode/InsertAfter/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/Classic WebData XmlNode.InsertAfter Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/Classic WebData XmlNode.InsertAfter Example/VB/source.vb" id="Snippet1"::: + ]]> - This node is of a type that does not allow child nodes of the type of the node. - + This node is of a type that does not allow child nodes of the type of the node. + The is an ancestor of this node. - The was created from a different document than the one that created this node. - - The is not a child of this node. - + The was created from a different document than the one that created this node. + + The is not a child of this node. + This node is read-only. When overriding in a derived class, in order for events to be raised correctly, you must call the method of the base class. @@ -1324,31 +1324,31 @@ d. Inserts the specified node immediately before the specified reference node. The node being inserted. - to import the node to the current document. The imported node can then be inserted into the current document. - - - -## Examples - The following example adds a new node to the XML document. - + to import the node to the current document. The imported node can then be inserted into the current document. + + + +## Examples + The following example adds a new node to the XML document. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/Classic WebData XmlNode.InsertBefore Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Xml/XmlNode/InsertBefore/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/Classic WebData XmlNode.InsertBefore Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/Classic WebData XmlNode.InsertBefore Example/VB/source.vb" id="Snippet1"::: + ]]> - The current node is of a type that does not allow child nodes of the type of the node. - + The current node is of a type that does not allow child nodes of the type of the node. + The is an ancestor of this node. - The was created from a different document than the one that created this node. - - The is not a child of this node. - + The was created from a different document than the one that created this node. + + The is not a child of this node. + This node is read-only. When overriding in a derived class, in order for events to be raised correctly, you must call the method of the base class. @@ -1407,13 +1407,13 @@ d. if the node is read-only; otherwise, . - @@ -1481,20 +1481,20 @@ d. Gets the first child element with the specified . The first that matches the specified name. It returns a null reference ( in Visual Basic) if there is no match. - @@ -1555,11 +1555,11 @@ d. Gets the first child element with the specified and . The first with the matching and . It returns a null reference ( in Visual Basic) if there is no match. - @@ -1622,15 +1622,15 @@ d. Gets the last child of the node. The last child of the node. If there is no such node, is returned. - @@ -1676,81 +1676,81 @@ d. Gets the local name of the node, when overridden in a derived class. - The name of the node with the prefix removed. For example, is book for the element <bk:book>. - - The name returned is dependent on the of the node: - - Type - - Name - - Attribute - - The local name of the attribute. - - CDATA - - #cdata-section - - Comment - - #comment - - Document - - #document - - DocumentFragment - - #document-fragment - - DocumentType - - The document type name. - - Element - - The local name of the element. - - Entity - - The name of the entity. - - EntityReference - - The name of the entity referenced. - - Notation - - The notation name. - - ProcessingInstruction - - The target of the processing instruction. - - Text - - #text - - Whitespace - - #whitespace - - SignificantWhitespace - - #significant-whitespace - - XmlDeclaration - - #xml-declaration - + The name of the node with the prefix removed. For example, is book for the element <bk:book>. + + The name returned is dependent on the of the node: + + Type + + Name + + Attribute + + The local name of the attribute. + + CDATA + + #cdata-section + + Comment + + #comment + + Document + + #document + + DocumentFragment + + #document-fragment + + DocumentType + + The document type name. + + Element + + The local name of the element. + + Entity + + The name of the entity. + + EntityReference + + The name of the entity referenced. + + Notation + + The notation name. + + ProcessingInstruction + + The target of the processing instruction. + + Text + + #text + + Whitespace + + #whitespace + + SignificantWhitespace + + #significant-whitespace + + XmlDeclaration + + #xml-declaration + - . - + . + ]]> @@ -1798,72 +1798,72 @@ d. Gets the qualified name of the node, when overridden in a derived class. - The qualified name of the node. The name returned is dependent on the of the node: - - Type - - Name - - Attribute - - The qualified name of the attribute. - - CDATA - - #cdata-section - - Comment - - #comment - - Document - - #document - - DocumentFragment - - #document-fragment - - DocumentType - - The document type name. - - Element - - The qualified name of the element. - - Entity - - The name of the entity. - - EntityReference - - The name of the entity referenced. - - Notation - - The notation name. - - ProcessingInstruction - - The target of the processing instruction. - - Text - - #text - - Whitespace - - #whitespace - - SignificantWhitespace - - #significant-whitespace - - XmlDeclaration - - #xml-declaration - + The qualified name of the node. The name returned is dependent on the of the node: + + Type + + Name + + Attribute + + The qualified name of the attribute. + + CDATA + + #cdata-section + + Comment + + #comment + + Document + + #document + + DocumentFragment + + #document-fragment + + DocumentType + + The document type name. + + Element + + The qualified name of the element. + + Entity + + The name of the entity. + + EntityReference + + The name of the entity referenced. + + Notation + + The notation name. + + ProcessingInstruction + + The target of the processing instruction. + + Text + + #text + + Whitespace + + #whitespace + + SignificantWhitespace + + #significant-whitespace + + XmlDeclaration + + #xml-declaration + To be added. @@ -1917,13 +1917,13 @@ d. Gets the namespace URI of this node. The namespace URI of this node. If there is no namespace URI, this property returns String.Empty. - - - An attribute does not inherit its namespace from the element it is attached to. If an attribute is not explicitly given a namespace, it simply has no namespace. - + + + An attribute does not inherit its namespace from the element it is attached to. If an attribute is not explicitly given a namespace, it simply has no namespace. + ]]> @@ -1982,15 +1982,15 @@ d. Gets the node immediately following this node. The next . If there is no next node, is returned. - @@ -2038,11 +2038,11 @@ d. Gets the type of the current node, when overridden in a derived class. One of the values. - @@ -2090,11 +2090,11 @@ d. Puts all XmlText nodes in the full depth of the sub-tree underneath this XmlNode into a "normal" form where only markup (that is, tags, comments, processing instructions, CDATA sections, and entity references) separates XmlText nodes, that is, there are no adjacent XmlText nodes. - @@ -2142,18 +2142,18 @@ d. Gets the markup containing this node and all its child nodes. The markup containing this node and all its child nodes, not including default attributes. - and `OuterXml` properties. - + +## Examples + The following example compares output from the and `OuterXml` properties. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/Classic WebData XmlNode.OuterXml Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Xml/XmlNode/OuterXml/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/Classic WebData XmlNode.OuterXml Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/Classic WebData XmlNode.OuterXml Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -2210,20 +2210,20 @@ d. Gets the to which this node belongs. - The to which this node belongs. - + The to which this node belongs. + If the node is an (NodeType equals XmlNodeType.Document), this property returns . - returned by the property to create the node. - - - -## Examples - See (in the XmlElement class) for an example using this property. - + returned by the property to create the node. + + + +## Examples + See (in the XmlElement class) for an example using this property. + ]]> @@ -2280,51 +2280,51 @@ d. Gets the parent of this node (for nodes that can have parents). - The that is the parent of the current node. If a node has just been created and not yet added to the tree, or if it has been removed from the tree, the parent is . For all other nodes, the value returned depends on the of the node. The following table describes the possible return values for the property. - - NodeType - - Return Value of ParentNode - - Attribute, Document, DocumentFragment, Entity, Notation - - Returns ; these nodes do not have parents. - - CDATA - - Returns the element or entity reference containing the CDATA section. - - Comment - - Returns the element, entity reference, document type, or document containing the comment. - - DocumentType - - Returns the document node. - - Element - - Returns the parent node of the element. If the element is the root node in the tree, the parent is the document node. - - EntityReference - - Returns the element, attribute, or entity reference containing the entity reference. - - ProcessingInstruction - - Returns the document, element, document type, or entity reference containing the processing instruction. - - Text - - Returns the parent element, attribute, or entity reference containing the text node. - + The that is the parent of the current node. If a node has just been created and not yet added to the tree, or if it has been removed from the tree, the parent is . For all other nodes, the value returned depends on the of the node. The following table describes the possible return values for the property. + + NodeType + + Return Value of ParentNode + + Attribute, Document, DocumentFragment, Entity, Notation + + Returns ; these nodes do not have parents. + + CDATA + + Returns the element or entity reference containing the CDATA section. + + Comment + + Returns the element, entity reference, document type, or document containing the comment. + + DocumentType + + Returns the document node. + + Element + + Returns the parent node of the element. If the element is the root node in the tree, the parent is the document node. + + EntityReference + + Returns the element, attribute, or entity reference containing the entity reference. + + ProcessingInstruction + + Returns the document, element, document type, or entity reference containing the processing instruction. + + Text + + Returns the parent element, attribute, or entity reference containing the text node. + - @@ -2378,22 +2378,22 @@ d. Gets or sets the namespace prefix of this node. The namespace prefix of this node. For example, is bk for the element <bk:book>. If there is no prefix, this property returns String.Empty. - property, which holds the qualified name, on Element and Attribute nodes. Setting this property on node types that cannot have a prefix (such as Text, Comment, EntityReference, CDATA, ProcessingInstruction, Document, and DocumentFragment) has no effect. Changing the prefix of an attribute that is known to have a default value, does not make a new attribute with the default value and the original prefix appear, since the namespace URI and local name do not change. - + property, which holds the qualified name, on Element and Attribute nodes. Setting this property on node types that cannot have a prefix (such as Text, Comment, EntityReference, CDATA, ProcessingInstruction, Document, and DocumentFragment) has no effect. Changing the prefix of an attribute that is known to have a default value, does not make a new attribute with the default value and the original prefix appear, since the namespace URI and local name do not change. + ]]> This node is read-only. - The specified prefix contains an invalid character. - - The specified prefix is malformed. - - The specified prefix is "xml" and the namespaceURI of this node is different from "http://www.w3.org/XML/1998/namespace". - - This node is an attribute and the specified prefix is "xmlns" and the namespaceURI of this node is different from "http://www.w3.org/2000/xmlns/ ". - + The specified prefix contains an invalid character. + + The specified prefix is malformed. + + The specified prefix is "xml" and the namespaceURI of this node is different from "http://www.w3.org/XML/1998/namespace". + + This node is an attribute and the specified prefix is "xmlns" and the namespaceURI of this node is different from "http://www.w3.org/2000/xmlns/ ". + This node is an attribute and the qualifiedName of this node is "xmlns". When overriding in a derived class, this property cannot be set. @@ -2448,31 +2448,31 @@ d. Adds the specified node to the beginning of the list of child nodes for this node. The node added. - to import the node to the current document. The imported node can then be inserted into the current document. - - This method is a Microsoft extension to the Document Object Model (DOM). - - - -## Examples - The following example adds a new node to the XML document. - + to import the node to the current document. The imported node can then be inserted into the current document. + + This method is a Microsoft extension to the Document Object Model (DOM). + + + +## Examples + The following example adds a new node to the XML document. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/Classic WebData XmlNode.PrependChild Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Xml/XmlNode/PrependChild/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/Classic WebData XmlNode.PrependChild Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/Classic WebData XmlNode.PrependChild Example/VB/source.vb" id="Snippet1"::: + ]]> - This node is of a type that does not allow child nodes of the type of the node. - + This node is of a type that does not allow child nodes of the type of the node. + The is an ancestor of this node. - The was created from a different document than the one that created this node. - + The was created from a different document than the one that created this node. + This node is read-only. When overriding in a derived class, in order for events to be raised correctly, you must call the method of the base class. @@ -2535,15 +2535,15 @@ d. Gets the node immediately preceding this node. The preceding . If there is no preceding node, is returned. - @@ -2600,11 +2600,11 @@ d. Gets the text node that immediately precedes this node. Returns . - property but you can use it only to get a node of type . To get any other type of node that precedes this node, use the property. - + property but you can use it only to get a node of type . To get any other type of node that precedes this node, use the property. + ]]> @@ -2658,22 +2658,22 @@ d. Removes all the child nodes and/or attributes of the current node. - @@ -2728,15 +2728,15 @@ d. Removes specified child node. The node removed. - The is not a child of this node. Or this node is read-only. @@ -2794,31 +2794,31 @@ d. Replaces the child node with node. The node replaced. - to import the node to the current document. The imported node can then be passed to the `ReplaceChild` method. - - - -## Examples - The following example replaces the title element in the XML document. - + to import the node to the current document. The imported node can then be passed to the `ReplaceChild` method. + + + +## Examples + The following example replaces the title element in the XML document. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/Classic WebData XmlNode.ReplaceChild Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Xml/XmlNode/ReplaceChild/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/Classic WebData XmlNode.ReplaceChild Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/Classic WebData XmlNode.ReplaceChild Example/VB/source.vb" id="Snippet1"::: + ]]> - This node is of a type that does not allow child nodes of the type of the node. - + This node is of a type that does not allow child nodes of the type of the node. + The is an ancestor of this node. - The was created from a different document than the one that created this node. - - This node is read-only. - + The was created from a different document than the one that created this node. + + This node is read-only. + The is not a child of this node. When overriding in a derived class, in order for events to be raised correctly, you must call the method of the base class. @@ -2872,11 +2872,11 @@ d. Gets the post schema validation infoset that has been assigned to this node as a result of schema validation. An object containing the post schema validation infoset of this node. - property is set when this node is validated. - + property is set when this node is validated. + ]]> @@ -2890,16 +2890,16 @@ d. Selects a list of nodes matching the XPath expression. - [!NOTE] -> If the XPath expression does not include a prefix, it is assumed that the namespace URI is the empty namespace. If your XML includes a default namespace, you must still add a prefix and namespace URI to the `XmlNamespaceManager`; otherwise, you will not get any nodes selected. - - For more information, see [Select Nodes Using XPath Navigation](/dotnet/standard/data/xml/select-nodes-using-xpath-navigation). For code examples, choose an overload from the overload list in the previous section. - +> If the XPath expression does not include a prefix, it is assumed that the namespace URI is the empty namespace. If your XML includes a default namespace, you must still add a prefix and namespace URI to the `XmlNamespaceManager`; otherwise, you will not get any nodes selected. + + For more information, see [Select Nodes Using XPath Navigation](/dotnet/standard/data/xml/select-nodes-using-xpath-navigation). For code examples, choose an overload from the overload list in the previous section. + ]]> XPath Selections and Custom Functions, and More @@ -2945,57 +2945,57 @@ d. System.Xml.XmlNodeList - + The XPath expression. Selects a list of nodes matching the XPath expression. An containing a collection of nodes matching the XPath query. - as its argument. The `XmlNamespaceManager` is used to resolve namespaces. - + as its argument. The `XmlNamespaceManager` is used to resolve namespaces. + > [!NOTE] -> If the XPath expression does not include a prefix, it is assumed that the namespace URI is the empty namespace. If your XML includes a default namespace, you must still use the `XmlNamespaceManager` and add a prefix and namespace URI to it; otherwise, you will not get any nodes selected. For more information, see [Select Nodes Using XPath Navigation](/dotnet/standard/data/xml/select-nodes-using-xpath-navigation). - +> If the XPath expression does not include a prefix, it is assumed that the namespace URI is the empty namespace. If your XML includes a default namespace, you must still use the `XmlNamespaceManager` and add a prefix and namespace URI to it; otherwise, you will not get any nodes selected. For more information, see [Select Nodes Using XPath Navigation](/dotnet/standard/data/xml/select-nodes-using-xpath-navigation). + > [!NOTE] -> A common issue when formulating XPath expressions is how to include a single quote (') or double quote (") in the expression. If you have to search for a value that includes a single quote, you must enclose the string in double quotes. If you need to search for a value that includes a double quote, you must enclose the string in single quotes. - - For example, suppose you have the following XML: - -```xml - - - 'Emma' - - -``` - - The following Visual Basic code selects an element that contains single quotes: - -```csharp -nodeList = root.SelectNodes("//book[contains(title,""'Emma'"")]") -``` - - This method is a Microsoft extension to the Document Object Model (DOM). - - The object returned by this method will be valid while the underlying document remains unchanged. If the underlying document changes, unexpected results may be returned (no exception will be thrown). - - - -## Examples - The following example selects all books where the author's last name is Austen, and then changes the price of those books. - +> A common issue when formulating XPath expressions is how to include a single quote (') or double quote (") in the expression. If you have to search for a value that includes a single quote, you must enclose the string in double quotes. If you need to search for a value that includes a double quote, you must enclose the string in single quotes. + + For example, suppose you have the following XML: + +```xml + + + 'Emma' + + +``` + + The following Visual Basic code selects an element that contains single quotes: + +```csharp +nodeList = root.SelectNodes("//book[contains(title,""'Emma'"")]") +``` + + This method is a Microsoft extension to the Document Object Model (DOM). + + The object returned by this method will be valid while the underlying document remains unchanged. If the underlying document changes, unexpected results may be returned (no exception will be thrown). + + + +## Examples + The following example selects all books where the author's last name is Austen, and then changes the price of those books. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/Classic WebData XmlNode.SelectNodes Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Xml/XmlDocument/Overview/source6.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/Classic WebData XmlNode.SelectNodes Example/VB/source.vb" id="Snippet1"::: - - This example uses the following XML: - - :::code language="xml" source="~/snippets/xml/VS_Snippets_Data/Classic WebData XmlNode.SelectNodes Example/XML/source.xml" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/Classic WebData XmlNode.SelectNodes Example/VB/source.vb" id="Snippet1"::: + + This example uses the following XML: + + :::code language="xml" source="~/snippets/xml/VS_Snippets_Data/Classic WebData XmlNode.SelectNodes Example/XML/source.xml" id="Snippet2"::: + ]]> The XPath expression contains a prefix. See [XPath Examples](https://docs.microsoft.com/previous-versions/dotnet/netframework-4.0/ms256086(v=vs.100)). @@ -3043,8 +3043,8 @@ nodeList = root.SelectNodes("//book[contains(title,""'Emma'"")]") System.Xml.XmlNodeList - - + + The XPath expression. See [XPath Examples](https://docs.microsoft.com/previous-versions/dotnet/netframework-4.0/ms256086(v=vs.100)). @@ -3052,70 +3052,70 @@ nodeList = root.SelectNodes("//book[contains(title,""'Emma'"")]") Selects a list of nodes matching the XPath expression. Any prefixes found in the XPath expression are resolved using the supplied . An containing a collection of nodes matching the XPath query. - [!NOTE] -> If the XPath expression does not include a prefix, it is assumed that the namespace URI is the empty namespace. If your XML includes a default namespace, you must still add a prefix and namespace URI to the `XmlNamespaceManager`; otherwise, you will not get any nodes selected. For more information, see [Select Nodes Using XPath Navigation](/dotnet/standard/data/xml/select-nodes-using-xpath-navigation). - - For example, if you had the following XML: - -```xml - - - Pride And Prejudice - - -``` - - The following C# code selects all book nodes: - -```csharp -XmlNamespaceManager nsmgr = new XmlNamespaceManager(doc.NameTable); -nsmgr.AddNamespace("ab", "http://www.lucernepublishing.com"); -XmlNodeList nodelist = doc.SelectNodes("//ab:book", nsmgr); -``` - +> If the XPath expression does not include a prefix, it is assumed that the namespace URI is the empty namespace. If your XML includes a default namespace, you must still add a prefix and namespace URI to the `XmlNamespaceManager`; otherwise, you will not get any nodes selected. For more information, see [Select Nodes Using XPath Navigation](/dotnet/standard/data/xml/select-nodes-using-xpath-navigation). + + For example, if you had the following XML: + +```xml + + + Pride And Prejudice + + +``` + + The following C# code selects all book nodes: + +```csharp +XmlNamespaceManager nsmgr = new XmlNamespaceManager(doc.NameTable); +nsmgr.AddNamespace("ab", "http://www.lucernepublishing.com"); +XmlNodeList nodelist = doc.SelectNodes("//ab:book", nsmgr); +``` + > [!NOTE] -> A common issue when formulating XPath expressions is how to include a single quote (') or double quote (") in the expression. If you have to search for a value that includes a single quote, you must enclose the string in double quotes. If you need to search for a value that includes a double quote, you must enclose the string in single quotes. - - For example, suppose you have the following XML: - -```xml - - - 'Emma' - - -``` - - The following Visual Basic code selects an element that contains single quotes: - -```vb -Dim nsmgr As XmlNamespaceManager = New XmlNamespaceManager(doc.NameTable) -nsmgr.AddNamespace("ab", "http://www.lucernepublishing.com") -nodeList = root.SelectNodes("//ab:book[contains(ab:title,""'Emma'"")]", nsmgr) -``` - - This method is a Microsoft extension to the Document Object Model (DOM). - - The object returned by this method will be valid while the underlying document remains unchanged. If the underlying document changes, unexpected results may be returned (no exception will be thrown). - - - -## Examples - The following example displays the values of each of the ISBN attributes. This example uses an object, which inherits from the class. - +> A common issue when formulating XPath expressions is how to include a single quote (') or double quote (") in the expression. If you have to search for a value that includes a single quote, you must enclose the string in double quotes. If you need to search for a value that includes a double quote, you must enclose the string in single quotes. + + For example, suppose you have the following XML: + +```xml + + + 'Emma' + + +``` + + The following Visual Basic code selects an element that contains single quotes: + +```vb +Dim nsmgr As XmlNamespaceManager = New XmlNamespaceManager(doc.NameTable) +nsmgr.AddNamespace("ab", "http://www.lucernepublishing.com") +nodeList = root.SelectNodes("//ab:book[contains(ab:title,""'Emma'"")]", nsmgr) +``` + + This method is a Microsoft extension to the Document Object Model (DOM). + + The object returned by this method will be valid while the underlying document remains unchanged. If the underlying document changes, unexpected results may be returned (no exception will be thrown). + + + +## Examples + The following example displays the values of each of the ISBN attributes. This example uses an object, which inherits from the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/XmlNode.SelectNodes1/CPP/selectnodes1.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Xml/XmlNode/SelectNodes/selectnodes1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XmlNode.SelectNodes1/VB/selectnodes1.vb" id="Snippet1"::: - - The example uses the file, `booksort.xml`, as input. - - :::code language="xml" source="~/snippets/xml/VS_Snippets_Data/Classic WebData XmlNode.SelectNodes Example/XML/source.xml" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XmlNode.SelectNodes1/VB/selectnodes1.vb" id="Snippet1"::: + + The example uses the file, `booksort.xml`, as input. + + :::code language="xml" source="~/snippets/xml/VS_Snippets_Data/Classic WebData XmlNode.SelectNodes Example/XML/source.xml" id="Snippet2"::: + ]]> The XPath expression contains a prefix which is not defined in the . @@ -3132,27 +3132,27 @@ nodeList = root.SelectNodes("//ab:book[contains(ab:title,""'Emma'"")]", nsmgr) Selects the first that matches the XPath expression. - [!NOTE] -> If the XPath expression does not include a prefix, it is assumed that the namespace URI is the empty namespace. If your XML includes a default namespace, you must still add a prefix and namespace URI to the `XmlNamespaceManager`; otherwise, you will not get any nodes selected. For more information, see [Select Nodes Using XPath Navigation](/dotnet/standard/data/xml/select-nodes-using-xpath-navigation). - - - -## Examples - The following example returns the first book with the matching author name. The `XmlNamespaceManager` resolves the default namespace in the XPath expression. - +> If the XPath expression does not include a prefix, it is assumed that the namespace URI is the empty namespace. If your XML includes a default namespace, you must still add a prefix and namespace URI to the `XmlNamespaceManager`; otherwise, you will not get any nodes selected. For more information, see [Select Nodes Using XPath Navigation](/dotnet/standard/data/xml/select-nodes-using-xpath-navigation). + + + +## Examples + The following example returns the first book with the matching author name. The `XmlNamespaceManager` resolves the default namespace in the XPath expression. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/XmlNode.SelectSingleNode2/CPP/XmlNode.SelectSingleNode2.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Xml/XmlNode/SelectSingleNode/selectsingnode2.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XmlNode.SelectSingleNode2/VB/selectsingnode2.vb" id="Snippet1"::: - - The example uses the file, `newbooks.xml`, as input. - - :::code language="xml" source="~/snippets/xml/VS_Snippets_Data/XmlNode.SelectSingleNode2/XML/newbooks.xml" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XmlNode.SelectSingleNode2/VB/selectsingnode2.vb" id="Snippet1"::: + + The example uses the file, `newbooks.xml`, as input. + + :::code language="xml" source="~/snippets/xml/VS_Snippets_Data/XmlNode.SelectSingleNode2/XML/newbooks.xml" id="Snippet2"::: + ]]> XPath Selections and Custom Functions, and More @@ -3198,55 +3198,55 @@ nodeList = root.SelectNodes("//ab:book[contains(ab:title,""'Emma'"")]", nsmgr) System.Xml.XmlNode - + The XPath expression. See [XPath Examples](https://docs.microsoft.com/previous-versions/dotnet/netframework-4.0/ms256086(v=vs.100)). Selects the first that matches the XPath expression. The first that matches the XPath query or if no matching node is found. - as its argument. The `XmlNamespaceManager` is used to resolve namespaces. - + as its argument. The `XmlNamespaceManager` is used to resolve namespaces. + > [!NOTE] -> If the XPath expression does not include a prefix, it is assumed that the namespace URI is the empty namespace. If your XML includes a default namespace, you must still use the `XmlNamespaceManager` and add a prefix and namespace URI to it; otherwise, you will not get a selected node. For more information, see [Select Nodes Using XPath Navigation](/dotnet/standard/data/xml/select-nodes-using-xpath-navigation). - +> If the XPath expression does not include a prefix, it is assumed that the namespace URI is the empty namespace. If your XML includes a default namespace, you must still use the `XmlNamespaceManager` and add a prefix and namespace URI to it; otherwise, you will not get a selected node. For more information, see [Select Nodes Using XPath Navigation](/dotnet/standard/data/xml/select-nodes-using-xpath-navigation). + > [!NOTE] -> A common issue when formulating XPath expressions is how to include a single quote (') or double quote (") in the expression. If you have to search for a value that includes a single quote, you must enclose the string in double quotes. If you need to search for a value that includes a double quote, you must enclose the string in single quotes. - - For example, suppose you have the following XML: - -```xml - - - 'Emma' - - -``` - - The following Visual Basic code selects an element that contains single quotes: - -``` -book = root.SelectSingleNode("descendant::book[title=""'Emma'""]") -``` - - This method is a Microsoft extension to the Document Object Model (DOM). - - - -## Examples - The following example changes the price of the first Jane Austen book. - +> A common issue when formulating XPath expressions is how to include a single quote (') or double quote (") in the expression. If you have to search for a value that includes a single quote, you must enclose the string in double quotes. If you need to search for a value that includes a double quote, you must enclose the string in single quotes. + + For example, suppose you have the following XML: + +```xml + + + 'Emma' + + +``` + + The following Visual Basic code selects an element that contains single quotes: + +``` +book = root.SelectSingleNode("descendant::book[title=""'Emma'""]") +``` + + This method is a Microsoft extension to the Document Object Model (DOM). + + + +## Examples + The following example changes the price of the first Jane Austen book. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/Classic WebData XmlNode.SelectSingleNode Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Xml/XmlNode/SelectSingleNode/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/Classic WebData XmlNode.SelectSingleNode Example/VB/source.vb" id="Snippet1"::: - - The example uses the file, `booksort.xml`, as input. - - :::code language="xml" source="~/snippets/xml/VS_Snippets_Data/Classic WebData XmlNode.SelectSingleNode Example/XML/source.xml" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/Classic WebData XmlNode.SelectSingleNode Example/VB/source.vb" id="Snippet1"::: + + The example uses the file, `booksort.xml`, as input. + + :::code language="xml" source="~/snippets/xml/VS_Snippets_Data/Classic WebData XmlNode.SelectSingleNode Example/XML/source.xml" id="Snippet2"::: + ]]> The XPath expression contains a prefix. @@ -3294,8 +3294,8 @@ book = root.SelectSingleNode("descendant::book[title=""'Emma'""]") System.Xml.XmlNode - - + + The XPath expression. See [XPath Examples](https://docs.microsoft.com/previous-versions/dotnet/netframework-4.0/ms256086(v=vs.100)). @@ -3303,68 +3303,68 @@ book = root.SelectSingleNode("descendant::book[title=""'Emma'""]") Selects the first that matches the XPath expression. Any prefixes found in the XPath expression are resolved using the supplied . The first that matches the XPath query or if no matching node is found. - [!NOTE] -> If the XPath expression does not include a prefix, it is assumed that the namespace URI is the empty namespace. If your XML includes a default namespace, you must still add a prefix and namespace URI to the `XmlNamespaceManager`; otherwise, you will not get a node selected. For more information, see [Select Nodes Using XPath Navigation](/dotnet/standard/data/xml/select-nodes-using-xpath-navigation). - - For example, if you had the following XML: - -```xml - - - Pride And Prejudice - - -``` - - The following C# code selects the first book node: - -```csharp -XmlNamespaceManager nsmgr = new XmlNamespaceManager(doc.NameTable); -nsmgr.AddNamespace("ab", "http://www.lucernepublishing.com"); -XmlNode book = doc.SelectSingleNode("//ab:book", nsmgr); -``` - +> If the XPath expression does not include a prefix, it is assumed that the namespace URI is the empty namespace. If your XML includes a default namespace, you must still add a prefix and namespace URI to the `XmlNamespaceManager`; otherwise, you will not get a node selected. For more information, see [Select Nodes Using XPath Navigation](/dotnet/standard/data/xml/select-nodes-using-xpath-navigation). + + For example, if you had the following XML: + +```xml + + + Pride And Prejudice + + +``` + + The following C# code selects the first book node: + +```csharp +XmlNamespaceManager nsmgr = new XmlNamespaceManager(doc.NameTable); +nsmgr.AddNamespace("ab", "http://www.lucernepublishing.com"); +XmlNode book = doc.SelectSingleNode("//ab:book", nsmgr); +``` + > [!NOTE] -> A common issue when formulating XPath expressions is how to include a single quote (') or double quote (") in the expression. If you have to search for a value that includes a single quote, you must enclose the string in double quotes. If you need to search for a value that includes a double quote, you must enclose the string in single quotes. - - For example, suppose you have the following XML: - -```xml - - - 'Emma' - - -``` - - The following Visual Basic code selects an element that contains single quotes: - -```vb -Dim nsmgr As XmlNamespaceManager = New XmlNamespaceManager(doc.NameTable) -nsmgr.AddNamespace("ab", "http://www.lucernepublishing.com") -book = root.SelectSingleNode("descendant::ab:book[ab:title=""'Emma'""]", nsmgr) -``` - - This method is a Microsoft extension to the Document Object Model (DOM). - - - -## Examples - The following example selects the book with the matching ISBN value. - +> A common issue when formulating XPath expressions is how to include a single quote (') or double quote (") in the expression. If you have to search for a value that includes a single quote, you must enclose the string in double quotes. If you need to search for a value that includes a double quote, you must enclose the string in single quotes. + + For example, suppose you have the following XML: + +```xml + + + 'Emma' + + +``` + + The following Visual Basic code selects an element that contains single quotes: + +```vb +Dim nsmgr As XmlNamespaceManager = New XmlNamespaceManager(doc.NameTable) +nsmgr.AddNamespace("ab", "http://www.lucernepublishing.com") +book = root.SelectSingleNode("descendant::ab:book[ab:title=""'Emma'""]", nsmgr) +``` + + This method is a Microsoft extension to the Document Object Model (DOM). + + + +## Examples + The following example selects the book with the matching ISBN value. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/XmlNode.SelectSingleNode1/CPP/selectsingnode.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Xml/XmlNode/SelectSingleNode/selectsingnode.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XmlNode.SelectSingleNode1/VB/selectsingnode.vb" id="Snippet1"::: - - The example uses the file, `booksort.xml`, as input. - - :::code language="xml" source="~/snippets/xml/VS_Snippets_Data/Classic WebData XmlNode.SelectNodes Example/XML/source.xml" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/XmlNode.SelectSingleNode1/VB/selectsingnode.vb" id="Snippet1"::: + + The example uses the file, `booksort.xml`, as input. + + :::code language="xml" source="~/snippets/xml/VS_Snippets_Data/Classic WebData XmlNode.SelectNodes Example/XML/source.xml" id="Snippet2"::: + ]]> The XPath expression contains a prefix which is not defined in the . @@ -3420,20 +3420,20 @@ book = root.SelectSingleNode("descendant::ab:book[ab:title=""'Emma'""]", nsmgr) The version number of the package name to test. If the version is not specified (null), supporting any version of the feature causes the method to return true. Tests if the DOM implementation implements a specific feature. - if the feature is implemented in the specified version; otherwise, . The following table describes the combinations that return . - - Feature - - Version - - XML - - 1.0 - - XML - - 2.0 - + if the feature is implemented in the specified version; otherwise, . The following table describes the combinations that return . + + Feature + + Version + + XML + + 1.0 + + XML + + 2.0 + To be added. @@ -3485,11 +3485,11 @@ book = root.SelectSingleNode("descendant::ab:book[ab:title=""'Emma'""]", nsmgr) For a description of this member, see . An enumerator for the collection. - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -3545,11 +3545,11 @@ book = root.SelectSingleNode("descendant::ab:book[ab:title=""'Emma'""]", nsmgr) For a description of this member, see . A copy of the node from which it is called. - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -3610,83 +3610,83 @@ book = root.SelectSingleNode("descendant::ab:book[ab:title=""'Emma'""]", nsmgr) Gets or sets the value of the node. - The value returned depends on the of the node: - - Type - - Value - - Attribute - - The value of the attribute. - - CDATASection - - The content of the CDATA Section. - - Comment - - The content of the comment. - - Document - - . - - DocumentFragment - - . - - DocumentType - - . - - Element - - . You can use the or properties to access the value of the element node. - - Entity - - . - - EntityReference - - . - - Notation - - . - - ProcessingInstruction - - The entire content excluding the target. - - Text - - The content of the text node. - - SignificantWhitespace - - The white space characters. White space can consist of one or more space characters, carriage returns, line feeds, or tabs. - - Whitespace - - The white space characters. White space can consist of one or more space characters, carriage returns, line feeds, or tabs. - - XmlDeclaration - - The content of the declaration (that is, everything between <?xml and ?>). - + The value returned depends on the of the node: + + Type + + Value + + Attribute + + The value of the attribute. + + CDATASection + + The content of the CDATA Section. + + Comment + + The content of the comment. + + Document + + . + + DocumentFragment + + . + + DocumentType + + . + + Element + + . You can use the or properties to access the value of the element node. + + Entity + + . + + EntityReference + + . + + Notation + + . + + ProcessingInstruction + + The entire content excluding the target. + + Text + + The content of the text node. + + SignificantWhitespace + + The white space characters. White space can consist of one or more space characters, carriage returns, line feeds, or tabs. + + Whitespace + + The white space characters. White space can consist of one or more space characters, carriage returns, line feeds, or tabs. + + XmlDeclaration + + The content of the declaration (that is, everything between <?xml and ?>). + - property of the new attribute. - + property of the new attribute. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/Classic WebData XmlNode.GetNamespaceOfPrefix Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Xml/XmlNode/Attributes/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/Classic WebData XmlNode.GetNamespaceOfPrefix Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/Classic WebData XmlNode.GetNamespaceOfPrefix Example/VB/source.vb" id="Snippet1"::: + ]]> Setting the value of a node that is read-only. @@ -3739,20 +3739,20 @@ book = root.SelectSingleNode("descendant::ab:book[ab:title=""'Emma'""]", nsmgr) The to which you want to save. Saves all the child nodes of the node to the specified , when overridden in a derived class. - property. - - - -## Examples - The following example displays the contents of the root node to the console. - + property. + + + +## Examples + The following example displays the contents of the root node to the console. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/Classic WebData XmlNode.WriteContentTo Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Xml/XmlNode/WriteContentTo/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/Classic WebData XmlNode.WriteContentTo Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/Classic WebData XmlNode.WriteContentTo Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -3804,20 +3804,20 @@ book = root.SelectSingleNode("descendant::ab:book[ab:title=""'Emma'""]", nsmgr) The to which you want to save. Saves the current node to the specified , when overridden in a derived class. - property. - - - -## Examples - The following example displays the root node to the console. - + property. + + + +## Examples + The following example displays the root node to the console. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Data/Classic WebData XmlNode.WriteTo Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Xml/XmlNode/WriteTo/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/Classic WebData XmlNode.WriteTo Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Data/Classic WebData XmlNode.WriteTo Example/VB/source.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.Xml/XmlReader.xml b/xml/System.Xml/XmlReader.xml index b966872729c..4cfac10c3c8 100644 --- a/xml/System.Xml/XmlReader.xml +++ b/xml/System.Xml/XmlReader.xml @@ -1081,8 +1081,8 @@ Note: In .NET for Win System.Xml.XmlReader - - + + [System.Runtime.CompilerServices.Nullable(2)] @@ -1090,7 +1090,7 @@ Note: In .NET for Win - + [System.Runtime.CompilerServices.Nullable(2)] @@ -1264,8 +1264,8 @@ Note: In .NET for Win System.Xml.XmlReader - - + + [System.Runtime.CompilerServices.Nullable(2)] @@ -1273,7 +1273,7 @@ Note: In .NET for Win - + [System.Runtime.CompilerServices.Nullable(2)] @@ -1452,8 +1452,8 @@ Note: In .NET for Win System.Xml.XmlReader - - + + [System.Runtime.CompilerServices.Nullable(2)] @@ -1461,7 +1461,7 @@ Note: In .NET for Win - + [System.Runtime.CompilerServices.Nullable(2)] @@ -6180,8 +6180,8 @@ An method was called before a previous asy System.DateTime - - + + The local name of the element. @@ -7566,7 +7566,7 @@ An method was called before a previous asy System.String - + The name to check. @@ -7625,8 +7625,8 @@ An method was called before a previous asy System.String - - + + The local name to check. diff --git a/xml/System.Xml/XmlReaderSettings.xml b/xml/System.Xml/XmlReaderSettings.xml index 0f579af6ded..11e24461636 100644 --- a/xml/System.Xml/XmlReaderSettings.xml +++ b/xml/System.Xml/XmlReaderSettings.xml @@ -183,7 +183,7 @@ The following example creates an that uses an - + The XML resolver. diff --git a/xml/System.Xml/XmlSecureResolver.xml b/xml/System.Xml/XmlSecureResolver.xml index 7a69fef52f1..75d4da8a59d 100644 --- a/xml/System.Xml/XmlSecureResolver.xml +++ b/xml/System.Xml/XmlSecureResolver.xml @@ -115,8 +115,8 @@ See the constructor reference topics for examples of these types of restrictions - - + + The XML resolver that is wrapped by the . @@ -161,8 +161,8 @@ See the constructor reference topics for examples of these types of restrictions netstandard - - + + The XML resolver that is wrapped by the . @@ -287,7 +287,7 @@ See the constructor reference topics for examples of these types of restrictions System.Security.Policy.Evidence - + The URL used to create the evidence. diff --git a/xml/System.Xml/XmlWriter.xml b/xml/System.Xml/XmlWriter.xml index 588d6868d42..07c7707e9d2 100644 --- a/xml/System.Xml/XmlWriter.xml +++ b/xml/System.Xml/XmlWriter.xml @@ -474,7 +474,7 @@ An method was called before a previous asy System.Xml.XmlWriter - + The file to which you want to write. The creates a file at the specified path and writes to it in XML 1.0 text syntax. The must be a file system path. @@ -853,8 +853,8 @@ An method was called before a previous asy System.Xml.XmlWriter - - + + [System.Runtime.CompilerServices.Nullable(2)] @@ -4399,8 +4399,8 @@ while (!reader.EOF){ System.Void - - + + The to copy from. @@ -4571,8 +4571,8 @@ An asynchronous method was called without System.Threading.Tasks.Task - - + + The to copy from. @@ -6664,7 +6664,7 @@ An asynchronous method was called without System.Void - + The value to write. diff --git a/xml/System/Activator.xml b/xml/System/Activator.xml index b41dfcd7929..38fc88ba17c 100644 --- a/xml/System/Activator.xml +++ b/xml/System/Activator.xml @@ -78,35 +78,35 @@ Contains methods to create types of objects locally or remotely, or obtain references to existing remote objects. This class cannot be inherited. - method creates an instance of a type defined in an assembly by invoking the constructor that best matches the specified arguments. If no arguments are specified, the constructor that takes no parameters, that is, the parameterless constructor, is invoked. - - You must have sufficient permission to search for and call a constructor; otherwise, an exception is thrown. By default, only public constructors are considered during the search for a constructor. If no constructor or parameterless constructor can be found, an exception is thrown. - - A binder parameter specifies an object that searches an assembly for a suitable constructor. You can specify your own binder and search criteria. If no binder is specified, a default binder is used. For more information, see the and classes. - - An evidence parameter affects the security policy and permissions for the constructor. For more information, see the class. - - An instance of a type can be created at a local or remote site. If the type is created remotely, an activation attribute parameter specifies the URI of the remote site. The call to create the instance might pass through intermediary sites before it reaches the remote site. Other activation attributes can modify the environment, or context, in which the call operates at the remote and intermediary sites. - - If the instance is created locally, a reference to that object is returned. If the instance is created remotely, a reference to a proxy is returned. The remote object is manipulated through the proxy as if it were a local object. - - The method creates a proxy to a currently running remote object, server-activated well-known object, or XML Web service. You can specify the connection medium, that is, the channel. For more information, see the class. - - Assemblies contain type definitions. The method creates an instance of a type from a currently running assembly. The method creates an instance from a file that contains an assembly. The method creates an instance of a COM object from a file that contains an assembly. - - - -## Examples - The following example shows how to use the class to dynamically construct objects at run time. - + method creates an instance of a type defined in an assembly by invoking the constructor that best matches the specified arguments. If no arguments are specified, the constructor that takes no parameters, that is, the parameterless constructor, is invoked. + + You must have sufficient permission to search for and call a constructor; otherwise, an exception is thrown. By default, only public constructors are considered during the search for a constructor. If no constructor or parameterless constructor can be found, an exception is thrown. + + A binder parameter specifies an object that searches an assembly for a suitable constructor. You can specify your own binder and search criteria. If no binder is specified, a default binder is used. For more information, see the and classes. + + An evidence parameter affects the security policy and permissions for the constructor. For more information, see the class. + + An instance of a type can be created at a local or remote site. If the type is created remotely, an activation attribute parameter specifies the URI of the remote site. The call to create the instance might pass through intermediary sites before it reaches the remote site. Other activation attributes can modify the environment, or context, in which the call operates at the remote and intermediary sites. + + If the instance is created locally, a reference to that object is returned. If the instance is created remotely, a reference to a proxy is returned. The remote object is manipulated through the proxy as if it were a local object. + + The method creates a proxy to a currently running remote object, server-activated well-known object, or XML Web service. You can specify the connection medium, that is, the channel. For more information, see the class. + + Assemblies contain type definitions. The method creates an instance of a type from a currently running assembly. The method creates an instance from a file that contains an assembly. The method creates an instance of a COM object from a file that contains an assembly. + + + +## Examples + The following example shows how to use the class to dynamically construct objects at run time. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/ActivatorX/cpp/ActivatorX.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System/Activator/Overview/ActivatorX.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR/ActivatorX/fs/ActivatorX.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ActivatorX/VB/ActivatorX.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ActivatorX/VB/ActivatorX.vb" id="Snippet1"::: + ]]> @@ -151,8 +151,8 @@ System.Runtime.Remoting.ObjectHandle - - + + The name of a file that contains an assembly where the type named is sought. @@ -160,34 +160,34 @@ Creates an instance of the COM object whose name is specified, using the named assembly file and the parameterless constructor. A handle that must be unwrapped to access the newly created object, or for instances. - method to unwrap the return value. - - A attribute with a value of `true` must be applied either explicitly or by default to the COM type so the method can create an instance of that type; otherwise, is thrown. - - For information about other exceptions that can be thrown by invoked methods, see the Exceptions section of the and methods. - + method to unwrap the return value. + + A attribute with a value of `true` must be applied either explicitly or by default to the COM type so the method can create an instance of that type; otherwise, is thrown. + + For information about other exceptions that can be thrown by invoked methods, see the Exceptions section of the and methods. + > [!NOTE] -> Starting with .NET Framework 2.0, this method can be used to create nonpublic types if the caller has been granted with the flag and if the grant set of the assembly that contains the nonpublic types is restricted to the caller's grant set or to a subset thereof. (See [Security Considerations for Reflection](/dotnet/framework/reflection-and-codedom/security-considerations-for-reflection).) To use this functionality, your application should target .NET Framework 3.5 or later. - +> Starting with .NET Framework 2.0, this method can be used to create nonpublic types if the caller has been granted with the flag and if the grant set of the assembly that contains the nonpublic types is restricted to the caller's grant set or to a subset thereof. (See [Security Considerations for Reflection](/dotnet/framework/reflection-and-codedom/security-considerations-for-reflection).) To use this functionality, your application should target .NET Framework 3.5 or later. + ]]> or is . - An instance cannot be created through COM. - - -or- - + An instance cannot be created through COM. + + -or- + was not found in . No matching constructor was found. is not found, or the module you are trying to load does not specify a file name extension. - Cannot create an instance of an abstract class. - - -or- - + Cannot create an instance of an abstract class. + + -or- + This member was invoked with a late-binding mechanism. The caller cannot provide activation attributes for an object that does not inherit from . @@ -224,10 +224,10 @@ System.Runtime.Remoting.ObjectHandle - - - - + + + + The name of a file that contains an assembly where the type named is sought. @@ -237,18 +237,18 @@ Creates an instance of the COM object whose name is specified, using the named assembly file and the parameterless constructor. A handle that must be unwrapped to access the newly created object, or for instances. - method to unwrap the return value. - - A attribute with a value of `true` must be applied either explicitly or by default to the COM type so the method can create an instance of that type; otherwise, is thrown. - - For information about other exceptions that can be thrown by invoked methods, see the Exceptions section of the and methods. - + method to unwrap the return value. + + A attribute with a value of `true` must be applied either explicitly or by default to the COM type so the method can create an instance of that type; otherwise, is thrown. + + For information about other exceptions that can be thrown by invoked methods, see the Exceptions section of the and methods. + > [!NOTE] -> Starting with .NET Framework 2.0, this method can be used to create nonpublic types if the caller has been granted with the flag and if the grant set of the assembly that contains the nonpublic types is restricted to the caller's grant set or to a subset thereof. (See [Security Considerations for Reflection](/dotnet/framework/reflection-and-codedom/security-considerations-for-reflection).) To use this functionality, your application should target .NET Framework 3.5 or later. - +> Starting with .NET Framework 2.0, this method can be used to create nonpublic types if the caller has been granted with the flag and if the grant set of the assembly that contains the nonpublic types is restricted to the caller's grant set or to a subset thereof. (See [Security Considerations for Reflection](/dotnet/framework/reflection-and-codedom/security-considerations-for-reflection).) To use this functionality, your application should target .NET Framework 3.5 or later. + ]]> @@ -256,9 +256,9 @@ is the empty string (""). An assembly or module was loaded twice with two different evidences. - - -or- - + + -or- + is longer than the system-defined maximum length. is not found, or the module you are trying to load does not specify a file name extension. @@ -267,16 +267,16 @@ is not a valid assembly. A code base that does not start with "file://" was specified without the required . - An instance cannot be created through COM. - - -or- - + An instance cannot be created through COM. + + -or- + was not found in . No matching constructor was found. - An instance of an abstract class cannot be created. - - -or- - + An instance of an abstract class cannot be created. + + -or- + This member was invoked with a late-binding mechanism. The caller cannot provide activation attributes for an object that does not inherit from . @@ -320,20 +320,20 @@ System.Runtime.Remoting.ObjectHandle - + An activation context object that specifies the object to create. Creates an instance of the type designated by the specified object. A handle that must be unwrapped to access the newly created object, or for instances. - method to unwrap the return value. - - The activation context is used during manifest-based activation to set up the domain policy and to provide an application-based security model. The class contains an object that provides access to the application manifest. For more information, see the class. - + Use the method to unwrap the return value. + + The activation context is used during manifest-based activation to set up the domain policy and to provide an application-based security model. The class contains an object that provides access to the application manifest. For more information, see the class. + ]]> @@ -401,43 +401,43 @@ Creates an instance of the specified type using that type's parameterless constructor. A reference to the newly created object, or for instances. - [!NOTE] -> Starting with .NET Framework 2.0, this method can be used to access nonpublic types if the caller has been granted with the flag and if the grant set of the assembly that contains the nonpublic types is restricted to the caller's grant set or to a subset thereof. (See [Security Considerations for Reflection](/dotnet/framework/reflection-and-codedom/security-considerations-for-reflection).) To use this functionality, your application should target .NET Framework 3.5 or later. - - - -## Examples - The following code example demonstrates how to call the method. Instances of several different types are created and their default values are displayed. - +> Starting with .NET Framework 2.0, this method can be used to access nonpublic types if the caller has been granted with the flag and if the grant set of the assembly that contains the nonpublic types is restricted to the caller's grant set or to a subset thereof. (See [Security Considerations for Reflection](/dotnet/framework/reflection-and-codedom/security-considerations-for-reflection).) To use this functionality, your application should target .NET Framework 3.5 or later. + + + +## Examples + The following code example demonstrates how to call the method. Instances of several different types are created and their default values are displayed. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/ActivatorX/cpp/source2.cpp" id="Snippet4"::: :::code language="csharp" source="~/snippets/csharp/System/Activator/Overview/source2.cs" interactive="try-dotnet" id="Snippet4"::: :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR/ActivatorX/fs/source2.fs" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ActivatorX/VB/source2.vb" id="Snippet4"::: - + ]]> is . - is not a . - - -or- - + is not a . + + -or- + is an open generic type (that is, the property returns ). - cannot be a . - - -or- - - Creation of , , , and types, or arrays of those types, is not supported. - - -or- - + cannot be a . + + -or- + + Creation of , , , and types, or arrays of those types, is not supported. + + -or- + The assembly that contains is a dynamic assembly that was created with . The constructor being called throws an exception. The caller does not have permission to call this constructor. @@ -485,8 +485,8 @@ Note: In .NET for Win System.Runtime.Remoting.ObjectHandle - - + + An activation context object that specifies the object to create. @@ -494,13 +494,13 @@ Note: In .NET for Win Creates an instance of the type that is designated by the specified object and activated with the specified custom activation data. A handle that must be unwrapped to access the newly created object, or for instances. - method to unwrap the return value. - - The activation context is used during manifest-based activation to set up the domain policy and to provide an application-based security model. The class contains an object that provides access to the application manifest. For more information, see the class. - + method to unwrap the return value. + + The activation context is used during manifest-based activation to set up the domain policy and to provide an application-based security model. The class contains an object that provides access to the application manifest. For more information, see the class. + ]]> @@ -551,8 +551,8 @@ Note: In .NET for Win System.Runtime.Remoting.ObjectHandle - - + + The name of the assembly where the type named is sought. If is , the executing assembly is searched. @@ -560,43 +560,43 @@ Note: In .NET for Win Creates an instance of the type whose name is specified, using the named assembly and parameterless constructor. A handle that must be unwrapped to access the newly created object, or for instances. - to unwrap the return value. - - `assemblyName` can be either of the following: - -- The simple name of an assembly, without its path or file extension. For example, you would specify `TypeExtensions` for an assembly whose path and name are .\bin\TypeExtensions.dll. - -- The full name of a signed assembly, which consists of its simple name, version, culture, and public key token; for example, "TypeExtensions, Version=1.0.0.0, Culture=neutral, PublicKeyToken=181869f2f7435b51". - - For more information on how the common language runtime identifies and loads assemblies, see [How the Runtime Locates Assemblies](/dotnet/framework/deployment/how-the-runtime-locates-assemblies). For information on using the application configuration file to define assembly locations, see [Specifying an Assembly's Location](/dotnet/framework/configure-apps/specify-assembly-location). If `assemblyName` is found, it is loaded in the default context. - + Use to unwrap the return value. + + `assemblyName` can be either of the following: + +- The simple name of an assembly, without its path or file extension. For example, you would specify `TypeExtensions` for an assembly whose path and name are .\bin\TypeExtensions.dll. + +- The full name of a signed assembly, which consists of its simple name, version, culture, and public key token; for example, "TypeExtensions, Version=1.0.0.0, Culture=neutral, PublicKeyToken=181869f2f7435b51". + + For more information on how the common language runtime identifies and loads assemblies, see [How the Runtime Locates Assemblies](/dotnet/framework/deployment/how-the-runtime-locates-assemblies). For information on using the application configuration file to define assembly locations, see [Specifying an Assembly's Location](/dotnet/framework/configure-apps/specify-assembly-location). If `assemblyName` is found, it is loaded in the default context. + > [!NOTE] -> Starting with .NET Framework 2.0, this method can be used to create nonpublic types if the caller has been granted with the flag and if the grant set of the assembly that contains the nonpublic types is restricted to the caller's grant set or to a subset thereof. (See [Security Considerations for Reflection](/dotnet/framework/reflection-and-codedom/security-considerations-for-reflection).) To use this functionality, your application should target .NET Framework 3.5 or later. - - - -## Examples - The following example defines a class named `Person` in an assembly named `PersonInfo`. Note that the `Person` class has two constructors, one of which is parameterless. - +> Starting with .NET Framework 2.0, this method can be used to create nonpublic types if the caller has been granted with the flag and if the grant set of the assembly that contains the nonpublic types is restricted to the caller's grant set or to a subset thereof. (See [Security Considerations for Reflection](/dotnet/framework/reflection-and-codedom/security-considerations-for-reflection).) To use this functionality, your application should target .NET Framework 3.5 or later. + + + +## Examples + The following example defines a class named `Person` in an assembly named `PersonInfo`. Note that the `Person` class has two constructors, one of which is parameterless. + :::code language="csharp" source="~/snippets/csharp/System/Activator/CreateInstance/personinfo.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.activator.createinstance/fs/personinfo.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.activator.createinstance/vb/personinfo.vb" id="Snippet1"::: - - The following example calls the method to instantiate the `Person` class. It requires a reference to PersonInfo.dll to be added to the project. Because the method calls the `Person` class parameterless constructor, the example assigns a value to its `Name` property. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.activator.createinstance/vb/personinfo.vb" id="Snippet1"::: + + The following example calls the method to instantiate the `Person` class. It requires a reference to PersonInfo.dll to be added to the project. Because the method calls the `Person` class parameterless constructor, the example assigns a value to its `Name` property. + :::code language="csharp" source="~/snippets/csharp/System/Activator/CreateInstance/createinstanceex1.cs" id="Snippet2"::: :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.activator.createinstance/fs/createinstanceex1.fs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.activator.createinstance/vb/createinstanceex1.vb" id="Snippet2"::: - - However, is frequently called to instantiate a type that crosses machine boundaries or that is not known at design time. In this case, you cannot include a reference to the assembly in the project and cannot make early-bound calls to the type's members. To work around this limitation, the following example uses the method along with reflection to assign a value to the `Person` object's `Name` property and to display its value. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.activator.createinstance/vb/createinstanceex1.vb" id="Snippet2"::: + + However, is frequently called to instantiate a type that crosses machine boundaries or that is not known at design time. In this case, you cannot include a reference to the assembly in the project and cannot make early-bound calls to the type's members. To work around this limitation, the following example uses the method along with reflection to assign a value to the `Person` object's `Name` property and to display its value. + :::code language="csharp" source="~/snippets/csharp/System/Activator/CreateInstance/createinstanceex1a.cs" id="Snippet3"::: :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.activator.createinstance/fs/createinstanceex1a.fs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.activator.createinstance/vb/createinstanceex1a.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.activator.createinstance/vb/createinstanceex1a.vb" id="Snippet3"::: + ]]> @@ -612,15 +612,15 @@ Note: In .NET for Win The COM type was not obtained through or . Creation of , , , and types, or arrays of those types, is not supported. - is not a valid assembly. - - -or- - + is not a valid assembly. + + -or- + The common language runtime (CLR) version 2.0 or later is currently loaded, and was compiled for a version of the CLR that is later than the currently loaded version. Note that the .NET Framework versions 2.0, 3.0, and 3.5 all use CLR version 2.0. - An assembly or module was loaded twice with two different evidences. - - -or- - + An assembly or module was loaded twice with two different evidences. + + -or- + The assembly name or code base is invalid. @@ -661,7 +661,7 @@ Note: In .NET for Win System.Object - + [System.Diagnostics.CodeAnalysis.DynamicallyAccessedMembers(System.Diagnostics.CodeAnalysis.DynamicallyAccessedMemberTypes.NonPublicConstructors | System.Diagnostics.CodeAnalysis.DynamicallyAccessedMemberTypes.PublicConstructors)] @@ -669,7 +669,7 @@ Note: In .NET for Win - + The type of object to create. @@ -678,32 +678,32 @@ Note: In .NET for Win Creates an instance of the specified type using that type's parameterless constructor. A reference to the newly created object, or for instances. - [!NOTE] -> Starting with .NET Framework 2.0, this method can be used to access nonpublic types and members if the caller has been granted with the flag and if the grant set of the assembly that contains the nonpublic types and members is restricted to the caller's grant set or to a subset thereof. (See [Security Considerations for Reflection](/dotnet/framework/reflection-and-codedom/security-considerations-for-reflection).) To use this functionality, your application should target .NET Framework 3.5 or later. - +> Starting with .NET Framework 2.0, this method can be used to access nonpublic types and members if the caller has been granted with the flag and if the grant set of the assembly that contains the nonpublic types and members is restricted to the caller's grant set or to a subset thereof. (See [Security Considerations for Reflection](/dotnet/framework/reflection-and-codedom/security-considerations-for-reflection).) To use this functionality, your application should target .NET Framework 3.5 or later. + ]]> is . - is not a . - - -or- - + is not a . + + -or- + is an open generic type (that is, the property returns ). - cannot be a . - - -or- - - Creation of , , , and types, or arrays of those types, is not supported. - - -or- - + cannot be a . + + -or- + + Creation of , , , and types, or arrays of those types, is not supported. + + -or- + The assembly that contains is a dynamic assembly that was created with . The constructor being called throws an exception. The caller does not have permission to call this constructor. @@ -796,52 +796,52 @@ Note: In .NET for Win Creates an instance of the specified type using the constructor that best matches the specified parameters. A reference to the newly created object, or for instances with no value. - [!NOTE] -> Starting with .NET Framework 2.0, this method can be used to access nonpublic types if the caller has been granted with the flag and if the grant set of the assembly that contains the nonpublic types is restricted to the caller's grant set or to a subset thereof. (See [Security Considerations for Reflection](/dotnet/framework/reflection-and-codedom/security-considerations-for-reflection).) To use this functionality, your application should target .NET Framework 3.5 or later. - - - -## Examples - The following example calls the method to create a object. It calls the constructor to instantiate a string that contains ten elements from a character array starting at the fourteenth position. - +> Starting with .NET Framework 2.0, this method can be used to access nonpublic types if the caller has been granted with the flag and if the grant set of the assembly that contains the nonpublic types is restricted to the caller's grant set or to a subset thereof. (See [Security Considerations for Reflection](/dotnet/framework/reflection-and-codedom/security-considerations-for-reflection).) To use this functionality, your application should target .NET Framework 3.5 or later. + + + +## Examples + The following example calls the method to create a object. It calls the constructor to instantiate a string that contains ten elements from a character array starting at the fourteenth position. + :::code language="csharp" source="~/snippets/csharp/System/Activator/CreateInstance/CreateInstance5.cs" interactive="try-dotnet" id="Snippet5"::: :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.activator.createinstance/fs/CreateInstance5.fs" id="Snippet5"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.activator.createinstance/vb/CreateInstance5.vb" id="Snippet5"::: - - The following example creates a jagged array whose elements are arguments to be passed to a constructor. The example then passes each array to the method to invoke the appropriate string constructor. - + + The following example creates a jagged array whose elements are arguments to be passed to a constructor. The example then passes each array to the method to invoke the appropriate string constructor. + :::code language="csharp" source="~/snippets/csharp/System/Activator/CreateInstance/createinstance2.cs" interactive="try-dotnet" id="Snippet4"::: :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.activator.createinstance/fs/createinstance2.fs" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.activator.createinstance/vb/createinstance2.vb" id="Snippet4"::: - + ]]> is . - is not a . - - -or- - + is not a . + + -or- + is an open generic type (that is, the property returns ). - cannot be a . - - -or- - - Creation of , , , and types, or arrays of those types, is not supported. - - -or- - - The assembly that contains is a dynamic assembly that was created with . - - -or- - + cannot be a . + + -or- + + Creation of , , , and types, or arrays of those types, is not supported. + + -or- + + The assembly that contains is a dynamic assembly that was created with . + + -or- + The constructor that best matches has arguments. The constructor being called throws an exception. The caller does not have permission to call this constructor. @@ -889,9 +889,9 @@ Note: In .NET for Win System.Runtime.Remoting.ObjectHandle - - - + + + The remote domain where the type named is created. @@ -900,13 +900,13 @@ Note: In .NET for Win Creates an instance of the type whose name is specified in the specified remote domain, using the named assembly and parameterless constructor. A handle that must be unwrapped to access the newly created object, or for instances. - when a host needs to execute code in an application domain that has restricted security permissions. - + Use when a host needs to execute code in an application domain that has restricted security permissions. + Use to unwrap the return value. - + ]]> @@ -917,24 +917,24 @@ Note: In .NET for Win was not found. The caller does not have permission to call this constructor. - Cannot create an instance of an abstract type. - - -or- - + Cannot create an instance of an abstract type. + + -or- + This member was invoked with a late-binding mechanism. The constructor, which was invoked through reflection, threw an exception. The COM type was not obtained through or . Creation of , , , and types, or arrays of those types, is not supported. - is not a valid assembly. - - -or- - + is not a valid assembly. + + -or- + The common language runtime (CLR) version 2.0 or later is currently loaded, and was compiled for a version of the CLR that is later than the currently loaded version. Note that the .NET Framework versions 2.0, 3.0, and 3.5 all use CLR version 2.0. - An assembly or module was loaded twice with two different evidences. - - -or- - + An assembly or module was loaded twice with two different evidences. + + -or- + The assembly name or code base is invalid. @@ -981,9 +981,9 @@ Note: In .NET for Win System.Runtime.Remoting.ObjectHandle - - - + + + [System.Runtime.CompilerServices.Nullable(2)] @@ -995,20 +995,20 @@ Note: In .NET for Win The name of the assembly where the type named is sought. If is , the executing assembly is searched. The fully qualified name of the type to create an instance of. - An array of one or more attributes that can participate in activation. This is typically an array that contains a single object that specifies the URL that is required to activate a remote object. - + An array of one or more attributes that can participate in activation. This is typically an array that contains a single object that specifies the URL that is required to activate a remote object. + This parameter is related to client-activated objects. Client activation is a legacy technology that is retained for backward compatibility but is not recommended for new development. Distributed applications should instead use Windows Communication Foundation. Creates an instance of the type whose name is specified, using the named assembly and parameterless constructor. A handle that must be unwrapped to access the newly created object, or for instances. - to unwrap the return value. - + Use to unwrap the return value. + > [!NOTE] -> Starting with .NET Framework 2.0, this method can be used to create nonpublic types if the caller has been granted with the flag and if the grant set of the nonpublic types is restricted to the caller's grant set or to a subset thereof. (See [Security Considerations for Reflection](/dotnet/framework/reflection-and-codedom/security-considerations-for-reflection).) To use this functionality, your application should target .NET Framework 3.5 or later. - +> Starting with .NET Framework 2.0, this method can be used to create nonpublic types if the caller has been granted with the flag and if the grant set of the nonpublic types is restricted to the caller's grant set or to a subset thereof. (See [Security Considerations for Reflection](/dotnet/framework/reflection-and-codedom/security-considerations-for-reflection).) To use this functionality, your application should target .NET Framework 3.5 or later. + ]]> @@ -1021,27 +1021,27 @@ Note: In .NET for Win The caller does not have permission to call this constructor. Cannot create an instance of an abstract class, or this member was invoked with a late-binding mechanism. The COM type was not obtained through or . - Creation of , , , and types, or arrays of those types, is not supported. - - -or- - - is not an empty array, and the type being created does not derive from . - - -or- - - is not a - + Creation of , , , and types, or arrays of those types, is not supported. + + -or- + + is not an empty array, and the type being created does not derive from . + + -or- + + is not a + array. - is not a valid assembly. - - -or- - + is not a valid assembly. + + -or- + The common language runtime (CLR) version 2.0 or later is currently loaded, and was compiled for a version of the CLR that is later than the currently loaded version. Note that the .NET Framework versions 2.0, 3.0, and 3.5 all use CLR version 2.0. - An assembly or module was loaded twice with two different evidences. - - -or- - + An assembly or module was loaded twice with two different evidences. + + -or- + The assembly name or code base is invalid. The invoked constructor throws an exception. @@ -1096,7 +1096,7 @@ An error occurred when attempting remote activation in a target specified in System.Object - + [System.Diagnostics.CodeAnalysis.DynamicallyAccessedMembers(System.Diagnostics.CodeAnalysis.DynamicallyAccessedMemberTypes.PublicConstructors)] @@ -1108,53 +1108,53 @@ An error occurred when attempting remote activation in a target specified in - - + + The type of object to create. An array of arguments that match in number, order, and type the parameters of the constructor to invoke. If is an empty array or , the constructor that takes no parameters (the parameterless constructor) is invoked. - An array of one or more attributes that can participate in activation. This is typically an array that contains a single object that specifies the URL that is required to activate a remote object. - + An array of one or more attributes that can participate in activation. This is typically an array that contains a single object that specifies the URL that is required to activate a remote object. + This parameter is related to client-activated objects. Client activation is a legacy technology that is retained for backward compatibility but is not recommended for new development. Distributed applications should instead use Windows Communication Foundation. Creates an instance of the specified type using the constructor that best matches the specified parameters. A reference to the newly created object, or for instances with no value. - [!NOTE] -> Starting with .NET Framework 2.0, this method can be used to access nonpublic types if the caller has been granted with the flag and if the grant set of the assembly that contains the nonpublic types is restricted to the caller's grant set or to a subset thereof. (See [Security Considerations for Reflection](/dotnet/framework/reflection-and-codedom/security-considerations-for-reflection).) To use this functionality, your application should target .NET Framework 3.5 or later. - +> Starting with .NET Framework 2.0, this method can be used to access nonpublic types if the caller has been granted with the flag and if the grant set of the assembly that contains the nonpublic types is restricted to the caller's grant set or to a subset thereof. (See [Security Considerations for Reflection](/dotnet/framework/reflection-and-codedom/security-considerations-for-reflection).) To use this functionality, your application should target .NET Framework 3.5 or later. + ]]> is . - is not a . - - -or- - + is not a . + + -or- + is an open generic type (that is, the property returns ). - cannot be a . - - -or- - - Creation of , , , and types, or arrays of those types, is not supported. - - -or- - - is not an empty array, and the type being created does not derive from . - - -or- - - The assembly that contains is a dynamic assembly that was created with . - - -or- - + cannot be a . + + -or- + + Creation of , , , and types, or arrays of those types, is not supported. + + -or- + + is not an empty array, and the type being created does not derive from . + + -or- + + The assembly that contains is a dynamic assembly that was created with . + + -or- + The constructor that best matches has arguments. The constructor being called throws an exception. The caller does not have permission to call this constructor. @@ -1213,7 +1213,7 @@ An error occurred when attempting remote activation in a target specified in System.Object - + [System.Diagnostics.CodeAnalysis.DynamicallyAccessedMembers(System.Diagnostics.CodeAnalysis.DynamicallyAccessedMemberTypes.NonPublicConstructors | System.Diagnostics.CodeAnalysis.DynamicallyAccessedMemberTypes.PublicConstructors)] @@ -1225,10 +1225,10 @@ An error occurred when attempting remote activation in a target specified in - - - - + + + + The type of object to create. @@ -1239,37 +1239,37 @@ An error occurred when attempting remote activation in a target specified in Creates an instance of the specified type using the constructor that best matches the specified parameters. A reference to the newly created object, or for instances with no value. - [!NOTE] -> Starting with .NET Framework 2.0, this method can be used to access nonpublic types and members if the caller has been granted with the flag and if the grant set of the assembly that contains the nonpublic types and members is restricted to the caller's grant set or to a subset thereof. (See [Security Considerations for Reflection](/dotnet/framework/reflection-and-codedom/security-considerations-for-reflection).) To use this functionality, your application should target .NET Framework 3.5 or later. - +> Starting with .NET Framework 2.0, this method can be used to access nonpublic types and members if the caller has been granted with the flag and if the grant set of the assembly that contains the nonpublic types and members is restricted to the caller's grant set or to a subset thereof. (See [Security Considerations for Reflection](/dotnet/framework/reflection-and-codedom/security-considerations-for-reflection).) To use this functionality, your application should target .NET Framework 3.5 or later. + ]]> is . - is not a . - - -or- - + is not a . + + -or- + is an open generic type (that is, the property returns ). - cannot be a . - - -or- - - Creation of , , , and types, or arrays of those types, is not supported. - - -or- - - The assembly that contains is a dynamic assembly that was created with . - - -or- - + cannot be a . + + -or- + + Creation of , , , and types, or arrays of those types, is not supported. + + -or- + + The assembly that contains is a dynamic assembly that was created with . + + -or- + The constructor that best matches has arguments. The constructor being called throws an exception. The caller does not have permission to call this constructor. @@ -1328,7 +1328,7 @@ An error occurred when attempting remote activation in a target specified in System.Object - + [System.Diagnostics.CodeAnalysis.DynamicallyAccessedMembers(System.Diagnostics.CodeAnalysis.DynamicallyAccessedMemberTypes.NonPublicConstructors | System.Diagnostics.CodeAnalysis.DynamicallyAccessedMemberTypes.PublicConstructors)] @@ -1340,11 +1340,11 @@ An error occurred when attempting remote activation in a target specified in - - - - - + + + + + The type of object to create. @@ -1352,47 +1352,47 @@ An error occurred when attempting remote activation in a target specified in An object that uses and to seek and identify the constructor. If is , the default binder is used. An array of arguments that match in number, order, and type the parameters of the constructor to invoke. If is an empty array or , the constructor that takes no parameters (the parameterless constructor) is invoked. Culture-specific information that governs the coercion of to the formal types declared for the constructor. If is , the for the current thread is used. - An array of one or more attributes that can participate in activation. This is typically an array that contains a single object that specifies the URL that is required to activate a remote object. - + An array of one or more attributes that can participate in activation. This is typically an array that contains a single object that specifies the URL that is required to activate a remote object. + This parameter is related to client-activated objects. Client activation is a legacy technology that is retained for backward compatibility but is not recommended for new development. Distributed applications should instead use Windows Communication Foundation. Creates an instance of the specified type using the constructor that best matches the specified parameters. A reference to the newly created object, or for instances with no value. - [!NOTE] -> Starting with .NET Framework 2.0, this method can be used to access nonpublic types and members if the caller has been granted with the flag and if the grant set of the nonpublic types and members is restricted to the caller's grant set or to a subset thereof. (See [Security Considerations for Reflection](/dotnet/framework/reflection-and-codedom/security-considerations-for-reflection).) To use this functionality, your application should target .NET Framework 3.5 or later. - +> Starting with .NET Framework 2.0, this method can be used to access nonpublic types and members if the caller has been granted with the flag and if the grant set of the nonpublic types and members is restricted to the caller's grant set or to a subset thereof. (See [Security Considerations for Reflection](/dotnet/framework/reflection-and-codedom/security-considerations-for-reflection).) To use this functionality, your application should target .NET Framework 3.5 or later. + ]]> is . - is not a . - - -or- - + is not a . + + -or- + is an open generic type (that is, the property returns ). - cannot be a . - - -or- - - Creation of , , , and types, or arrays of those types, is not supported. - - -or- - - is not an empty array, and the type being created does not derive from . - - -or- - - The assembly that contains is a dynamic assembly that was created with . - - -or- - + cannot be a . + + -or- + + Creation of , , , and types, or arrays of those types, is not supported. + + -or- + + is not an empty array, and the type being created does not derive from . + + -or- + + The assembly that contains is a dynamic assembly that was created with . + + -or- + The constructor that best matches has arguments. The constructor being called throws an exception. The caller does not have permission to call this constructor. @@ -1450,7 +1450,7 @@ An error occurred when attempting remote activation in a target specified in System.Runtime.Remoting.ObjectHandle - + [System.Runtime.CompilerServices.Nullable(1)] @@ -1458,7 +1458,7 @@ An error occurred when attempting remote activation in a target specified in - + [System.Runtime.CompilerServices.Nullable(1)] @@ -1466,12 +1466,12 @@ An error occurred when attempting remote activation in a target specified in - - - - - - + + + + + + The name of the assembly where the type named is sought. If is , the executing assembly is searched. @@ -1482,20 +1482,20 @@ An error occurred when attempting remote activation in a target specified in An object that uses and to seek and identify the constructor. If is , the default binder is used. An array of arguments that match in number, order, and type the parameters of the constructor to invoke. If is an empty array or , the constructor that takes no parameters (the parameterless constructor) is invoked. Culture-specific information that governs the coercion of to the formal types declared for the constructor. If is , the for the current thread is used. - An array of one or more attributes that can participate in activation. This is typically an array that contains a single object that specifies the URL that is required to activate a remote object. - + An array of one or more attributes that can participate in activation. This is typically an array that contains a single object that specifies the URL that is required to activate a remote object. + This parameter is related to client-activated objects. Client activation is a legacy technology that is retained for backward compatibility but is not recommended for new development. Distributed applications should instead use Windows Communication Foundation. Creates an instance of the type whose name is specified, using the named assembly and the constructor that best matches the specified parameters. A handle that must be unwrapped to access the newly created instance, or for instances with no value. - to unwrap the return value. + Use to unwrap the return value. > [!NOTE] -> Starting with .NET Framework 2.0, this method can be used to create nonpublic types and members if the caller has been granted with the flag and if the grant set of the assembly that contains the nonpublic types and members is restricted to the caller's grant set or to a subset thereof. (See [Security Considerations for Reflection](/dotnet/framework/reflection-and-codedom/security-considerations-for-reflection).) To use this functionality, your application should target .NET Framework 3.5 or later. - +> Starting with .NET Framework 2.0, this method can be used to create nonpublic types and members if the caller has been granted with the flag and if the grant set of the assembly that contains the nonpublic types and members is restricted to the caller's grant set or to a subset thereof. (See [Security Considerations for Reflection](/dotnet/framework/reflection-and-codedom/security-considerations-for-reflection).) To use this functionality, your application should target .NET Framework 3.5 or later. + ]]> @@ -1509,25 +1509,25 @@ An error occurred when attempting remote activation in a target specified in Cannot create an instance of an abstract class, or this member was invoked with a late-binding mechanism. The constructor, which was invoked through reflection, threw an exception. The COM type was not obtained through or . - Creation of , , , and types, or arrays of those types, is not supported. - - -or- - - is not an empty array, and the type being created does not derive from . - - -or- - + Creation of , , , and types, or arrays of those types, is not supported. + + -or- + + is not an empty array, and the type being created does not derive from . + + -or- + The constructor that best matches has arguments. - is not a valid assembly. - - -or- - + is not a valid assembly. + + -or- + The common language runtime (CLR) version 2.0 or later is currently loaded, and was compiled for a version of the CLR that is later than the currently loaded version. Note that the .NET Framework versions 2.0, 3.0, and 3.5 all use CLR version 2.0. - An assembly or module was loaded twice with two different evidences. - - -or- - + An assembly or module was loaded twice with two different evidences. + + -or- + The assembly name or code base is invalid. @@ -1559,15 +1559,15 @@ An error occurred when attempting remote activation in a target specified in System.Runtime.Remoting.ObjectHandle - - - - - - - - - + + + + + + + + + The domain where the type named is created. @@ -1579,19 +1579,19 @@ An error occurred when attempting remote activation in a target specified in An object that uses and to seek and identify the constructor. If is , the default binder is used. An array of arguments that match in number, order, and type the parameters of the constructor to invoke. If is an empty array or , the constructor that takes no parameters (the parameterless constructor) is invoked. Culture-specific information that governs the coercion of to the formal types declared for the constructor. If is , the for the current thread is used. - An array of one or more attributes that can participate in activation. This is typically an array that contains a single object that specifies the URL that is required to activate a remote object. - + An array of one or more attributes that can participate in activation. This is typically an array that contains a single object that specifies the URL that is required to activate a remote object. + This parameter is related to client-activated objects. Client activation is a legacy technology that is retained for backward compatibility but is not recommended for new development. Distributed applications should instead use Windows Communication Foundation. Creates an instance of the type whose name is specified in the specified remote domain, using the named assembly and the constructor that best matches the specified parameters. A handle that must be unwrapped to access the newly created object, or for instances with no value. - when a host needs to execute code in an application domain that has restricted security permissions. - + Use when a host needs to execute code in an application domain that has restricted security permissions. + Use to unwrap the return value. - + ]]> @@ -1605,25 +1605,25 @@ An error occurred when attempting remote activation in a target specified in Cannot create an instance of an abstract class, or this member was invoked with a late-binding mechanism. The constructor, which was invoked through reflection, threw an exception. The COM type was not obtained through or . - Creation of , , , and types, or arrays of those types, is not supported. - - -or- - - is not an empty array, and the type being created does not derive from . - - -or- - + Creation of , , , and types, or arrays of those types, is not supported. + + -or- + + is not an empty array, and the type being created does not derive from . + + -or- + The constructor that best matches has arguments. - is not a valid assembly. - - -or- - + is not a valid assembly. + + -or- + The common language runtime (CLR) version 2.0 or later is currently loaded, and was compiled for a version of the CLR that is later than the currently loaded version. Note that the .NET Framework versions 2.0, 3.0, and 3.5 all use CLR version 2.0. - An assembly or module was loaded twice with two different evidences. - - -or- - + An assembly or module was loaded twice with two different evidences. + + -or- + The assembly name or code base is invalid. @@ -1661,15 +1661,15 @@ An error occurred when attempting remote activation in a target specified in System.Runtime.Remoting.ObjectHandle - - - - - - - - - + + + + + + + + + The name of the assembly where the type named is sought. If is , the executing assembly is searched. @@ -1680,21 +1680,21 @@ An error occurred when attempting remote activation in a target specified in An object that uses and to seek and identify the constructor. If is , the default binder is used. An array of arguments that match in number, order, and type the parameters of the constructor to invoke. If is an empty array or , the constructor that takes no parameters (the parameterless constructor) is invoked. Culture-specific information that governs the coercion of to the formal types declared for the constructor. If is , the for the current thread is used. - An array of one or more attributes that can participate in activation. This is typically an array that contains a single object that specifies the URL that is required to activate a remote object. - + An array of one or more attributes that can participate in activation. This is typically an array that contains a single object that specifies the URL that is required to activate a remote object. + This parameter is related to client-activated objects. Client activation is a legacy technology that is retained for backward compatibility but is not recommended for new development. Distributed applications should instead use Windows Communication Foundation. Information used to make security policy decisions and grant code permissions. Creates an instance of the type whose name is specified, using the named assembly and the constructor that best matches the specified parameters. A handle that must be unwrapped to access the newly created object, or for instances with no value. - to unwrap the return value. - + Use to unwrap the return value. + > [!NOTE] -> Starting with .NET Framework 2.0, this method can be used to create nonpublic types and members if the caller has been granted with the flag and if the grant set of the assembly that contains the nonpublic types and members is restricted to the caller's grant set or to a subset thereof. (See [Security Considerations for Reflection](/dotnet/framework/reflection-and-codedom/security-considerations-for-reflection).) To use this functionality, your application should target .NET Framework 3.5 or later. - +> Starting with .NET Framework 2.0, this method can be used to create nonpublic types and members if the caller has been granted with the flag and if the grant set of the assembly that contains the nonpublic types and members is restricted to the caller's grant set or to a subset thereof. (See [Security Considerations for Reflection](/dotnet/framework/reflection-and-codedom/security-considerations-for-reflection).) To use this functionality, your application should target .NET Framework 3.5 or later. + ]]> @@ -1708,25 +1708,25 @@ An error occurred when attempting remote activation in a target specified in Cannot create an instance of an abstract class, or this member was invoked with a late-binding mechanism. The constructor, which was invoked through reflection, threw an exception. The COM type was not obtained through or . - Creation of , , , and types, or arrays of those types, is not supported. - - -or- - - is not an empty array, and the type being created does not derive from . - - -or- - + Creation of , , , and types, or arrays of those types, is not supported. + + -or- + + is not an empty array, and the type being created does not derive from . + + -or- + The constructor that best matches has arguments. - is not a valid assembly. - - -or- - + is not a valid assembly. + + -or- + The common language runtime (CLR) version 2.0 or later is currently loaded, and was compiled for a version of the CLR that is later than the currently loaded version. Note that the .NET Framework versions 2.0, 3.0, and 3.5 all use CLR version 2.0. - An assembly or module was loaded twice with two different evidences. - - -or- - + An assembly or module was loaded twice with two different evidences. + + -or- + The assembly name or code base is invalid. @@ -1763,16 +1763,16 @@ An error occurred when attempting remote activation in a target specified in System.Runtime.Remoting.ObjectHandle - - - - - - - - - - + + + + + + + + + + The domain where the type named is created. @@ -1789,13 +1789,13 @@ An error occurred when attempting remote activation in a target specified in Creates an instance of the type whose name is specified in the specified remote domain, using the named assembly and the constructor that best matches the specified parameters. A handle that must be unwrapped to access the newly created object, or for instances with no value. - when a host needs to execute code in an application domain that has restricted security permissions. - + Use when a host needs to execute code in an application domain that has restricted security permissions. + Use to unwrap the return value. - + ]]> @@ -1809,25 +1809,25 @@ An error occurred when attempting remote activation in a target specified in Cannot create an instance of an abstract class, or this member was invoked with a late-binding mechanism. The constructor, which was invoked through reflection, threw an exception. The COM type was not obtained through or . - Creation of , , , and types, or arrays of those types, is not supported. - - -or- - - is not an empty array, and the type being created does not derive from . - - -or- - + Creation of , , , and types, or arrays of those types, is not supported. + + -or- + + is not an empty array, and the type being created does not derive from . + + -or- + The constructor that best matches has arguments. - is not a valid assembly. - - -or- - + is not a valid assembly. + + -or- + The common language runtime (CLR) version 2.0 or later is currently loaded, and was compiled for a version of the CLR that is later than the currently loaded version. Note that the .NET Framework versions 2.0, 3.0, and 3.5 all use CLR version 2.0. - An assembly or module was loaded twice with two different evidences. - - -or- - + An assembly or module was loaded twice with two different evidences. + + -or- + The assembly name or code base is invalid. @@ -1894,20 +1894,20 @@ An error occurred when attempting remote activation in a target specified in Creates an instance of the type designated by the specified generic type parameter, using the parameterless constructor. A reference to the newly created object, or for instances. - generic method is used by compilers to implement the instantiation of types specified by type parameters. For example, in the following generic method, the implementation of `new T()` (`gcnew T()` in C++) uses the generic method. - + generic method is used by compilers to implement the instantiation of types specified by type parameters. For example, in the following generic method, the implementation of `new T()` (`gcnew T()` in C++) uses the generic method. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.activation.createinstance~~1/cpp/remarks.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System/Activator/CreateInstanceT/remarks.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.activation.createinstance~~1/fs/remarks.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.activation.createinstance~~1/vb/remarks.vb" id="Snippet1"::: - - In general, there is no use for the generic method in application code, because the type must be known at compile time. If the type is known at compile time, normal instantiation syntax can be used (`new` operator in C#, `New` in Visual Basic, `gcnew` in C++). If the type is not known at compile time, you can call a non-generic overload of . - - There are no overloads of the generic method that take argument lists, because the non-generic overloads of already provide late-bound constructor resolution. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.activation.createinstance~~1/vb/remarks.vb" id="Snippet1"::: + + In general, there is no use for the generic method in application code, because the type must be known at compile time. If the type is known at compile time, normal instantiation syntax can be used (`new` operator in C#, `New` in Visual Basic, `gcnew` in C++). If the type is not known at compile time, you can call a non-generic overload of . + + There are no overloads of the generic method that take argument lists, because the non-generic overloads of already provide late-bound constructor resolution. + ]]> Cannot create an instance of an abstract class, or the type that is specified for does not have a parameterless constructor. @@ -1969,8 +1969,8 @@ Note: In .NET for Win System.Runtime.Remoting.ObjectHandle - - + + The name of a file that contains an assembly where the type named is sought. @@ -1978,23 +1978,23 @@ Note: In .NET for Win Creates an instance of the type whose name is specified, using the named assembly file and parameterless constructor. A handle that must be unwrapped to access the newly created object, or for instances. - method to unwrap the return value. - - For information about other exceptions that can be thrown by invoked methods, see the Exceptions section of the and methods. - - - -## Examples - The following code example demonstrates how to call the method. This code example is part of a larger example provided for the class. - + method to unwrap the return value. + + For information about other exceptions that can be thrown by invoked methods, see the Exceptions section of the and methods. + + + +## Examples + The following code example demonstrates how to call the method. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/ActivatorX/cpp/ActivatorX.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System/Activator/Overview/ActivatorX.cs" id="Snippet3"::: :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR/ActivatorX/fs/ActivatorX.fs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ActivatorX/VB/ActivatorX.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ActivatorX/VB/ActivatorX.vb" id="Snippet3"::: + ]]> @@ -2009,10 +2009,10 @@ Note: In .NET for Win The constructor, which was invoked through reflection, threw an exception. The caller does have the required . - is not a valid assembly. - - -or- - + is not a valid assembly. + + -or- + The common language runtime (CLR) version 2.0 or later is currently loaded, and was compiled for a version of the CLR that is later than the currently loaded version. Note that the .NET Framework versions 2.0, 3.0, and 3.5 all use CLR version 2.0. @@ -2045,9 +2045,9 @@ Note: In .NET for Win System.Runtime.Remoting.ObjectHandle - - - + + + The remote domain where the type named is created. @@ -2056,15 +2056,15 @@ Note: In .NET for Win Creates an instance of the type whose name is specified in the specified remote domain, using the named assembly file and parameterless constructor. A handle that must be unwrapped to access the newly created object, or for instances. - when a host needs to execute code in an application domain that has restricted security permissions. - + when a host needs to execute code in an application domain that has restricted security permissions. + Use the method to unwrap the return value. - - For information about other exceptions that can be thrown by invoked methods, see the Exceptions section of the and methods. - + + For information about other exceptions that can be thrown by invoked methods, see the Exceptions section of the and methods. + ]]> @@ -2079,10 +2079,10 @@ Note: In .NET for Win The constructor, which was invoked through reflection, threw an exception. The caller does have the required . - is not a valid assembly. - - -or- - + is not a valid assembly. + + -or- + The common language runtime (CLR) version 2.0 or later is currently loaded, and was compiled for a version of the CLR that is later than the currently loaded version. Note that the .NET Framework versions 2.0, 3.0, and 3.5 all use CLR version 2.0. @@ -2129,9 +2129,9 @@ Note: In .NET for Win System.Runtime.Remoting.ObjectHandle - - - + + + [System.Runtime.CompilerServices.Nullable(2)] @@ -2143,19 +2143,19 @@ Note: In .NET for Win The name of a file that contains an assembly where the type named is sought. The name of the type to create an instance of. - An array of one or more attributes that can participate in activation. This is typically an array that contains a single object that specifies the URL that is required to activate a remote object. - + An array of one or more attributes that can participate in activation. This is typically an array that contains a single object that specifies the URL that is required to activate a remote object. + This parameter is related to client-activated objects. Client activation is a legacy technology that is retained for backward compatibility but is not recommended for new development. Distributed applications should instead use Windows Communication Foundation. Creates an instance of the type whose name is specified, using the named assembly file and parameterless constructor. A handle that must be unwrapped to access the newly created object, or for instances. - method to unwrap the return value. - - For information about other exceptions that can be thrown by invoked methods, see the Exceptions section of the and methods. - + method to unwrap the return value. + + For information about other exceptions that can be thrown by invoked methods, see the Exceptions section of the and methods. + ]]> @@ -2172,10 +2172,10 @@ Note: In .NET for Win is not an empty array, and the type being created does not derive from . The caller does have the required . - is not a valid assembly. - - -or- - + is not a valid assembly. + + -or- + The common language runtime (CLR) version 2.0 or later is currently loaded, and was compiled for a version of the CLR that is later than the currently loaded version. Note that the .NET Framework versions 2.0, 3.0, and 3.5 all use CLR version 2.0. @@ -2220,7 +2220,7 @@ Note: In .NET for Win System.Runtime.Remoting.ObjectHandle - + [System.Runtime.CompilerServices.Nullable(1)] @@ -2228,7 +2228,7 @@ Note: In .NET for Win - + [System.Runtime.CompilerServices.Nullable(1)] @@ -2236,12 +2236,12 @@ Note: In .NET for Win - - - - - - + + + + + + The name of a file that contains an assembly where the type named is sought. @@ -2252,19 +2252,19 @@ Note: In .NET for Win An object that uses and to seek and identify the constructor. If is , the default binder is used. An array of arguments that match in number, order, and type the parameters of the constructor to invoke. If is an empty array or , the constructor that takes no parameters (the parameterless constructor) is invoked. Culture-specific information that governs the coercion of to the formal types declared for the constructor. If is , the for the current thread is used. - An array of one or more attributes that can participate in activation. This is typically an array that contains a single object that specifies the URL that is required to activate a remote object. - + An array of one or more attributes that can participate in activation. This is typically an array that contains a single object that specifies the URL that is required to activate a remote object. + This parameter is related to client-activated objects. Client activation is a legacy technology that is retained for backward compatibility but is not recommended for new development. Distributed applications should instead use Windows Communication Foundation. Creates an instance of the type whose name is specified, using the named assembly file and the constructor that best matches the specified parameters. A handle that must be unwrapped to access the newly created object, or for instances. - method to unwrap the return value. - - For information about other exceptions that can be thrown by invoked methods, see the Exceptions section of the and methods. - + method to unwrap the return value. + + For information about other exceptions that can be thrown by invoked methods, see the Exceptions section of the and methods. + ]]> @@ -2281,10 +2281,10 @@ Note: In .NET for Win is not an empty array, and the type being created does not derive from . - is not a valid assembly. - - -or- - + is not a valid assembly. + + -or- + The common language runtime (CLR) version 2.0 or later is currently loaded, and was compiled for a version of the CLR that is later than the currently loaded version. Note that the .NET Framework versions 2.0, 3.0, and 3.5 all use CLR version 2.0. @@ -2316,15 +2316,15 @@ Note: In .NET for Win System.Runtime.Remoting.ObjectHandle - - - - - - - - - + + + + + + + + + The remote domain where the type named is created. @@ -2336,21 +2336,21 @@ Note: In .NET for Win An object that uses and to seek and identify the constructor. If is , the default binder is used. An array of arguments that match in number, order, and type the parameters of the constructor to invoke. If is an empty array or , the constructor that takes no parameters (the parameterless constructor) is invoked. Culture-specific information that governs the coercion of to the formal types declared for the constructor. If is , the for the current thread is used. - An array of one or more attributes that can participate in activation. This is typically an array that contains a single object that specifies the URL that is required to activate a remote object. - + An array of one or more attributes that can participate in activation. This is typically an array that contains a single object that specifies the URL that is required to activate a remote object. + This parameter is related to client-activated objects. Client activation is a legacy technology that is retained for backward compatibility but is not recommended for new development. Distributed applications should instead use Windows Communication Foundation. Creates an instance of the type whose name is specified in the specified remote domain, using the named assembly file and the constructor that best matches the specified parameters. A handle that must be unwrapped to access the newly created object, or for instances. - when a host needs to execute code in an application domain that has restricted security permissions. - - Use the method to unwrap the return value. - - For information about other exceptions that can be thrown by invoked methods, see the Exceptions sections of the and methods. - + when a host needs to execute code in an application domain that has restricted security permissions. + + Use the method to unwrap the return value. + + For information about other exceptions that can be thrown by invoked methods, see the Exceptions sections of the and methods. + ]]> @@ -2367,10 +2367,10 @@ Note: In .NET for Win is not an empty array, and the type being created does not derive from . - is not a valid assembly. - - -or- - + is not a valid assembly. + + -or- + was compiled for a version of the common language runtime that is later than the version that is currently loaded. @@ -2404,15 +2404,15 @@ Note: In .NET for Win System.Runtime.Remoting.ObjectHandle - - - - - - - - - + + + + + + + + + The name of a file that contains an assembly where the type named is sought. @@ -2423,20 +2423,20 @@ Note: In .NET for Win An object that uses and to seek and identify the constructor. If is , the default binder is used. An array of arguments that match in number, order, and type the parameters of the constructor to invoke. If is an empty array or , the constructor that takes no parameters (the parameterless constructor) is invoked. Culture-specific information that governs the coercion of to the formal types declared for the constructor. If is , the for the current thread is used. - An array of one or more attributes that can participate in activation. This is typically an array that contains a single object that specifies the URL that is required to activate a remote object. - + An array of one or more attributes that can participate in activation. This is typically an array that contains a single object that specifies the URL that is required to activate a remote object. + This parameter is related to client-activated objects. Client activation is a legacy technology that is retained for backward compatibility but is not recommended for new development. Distributed applications should instead use Windows Communication Foundation. Information used to make security policy decisions and grant code permissions. Creates an instance of the type whose name is specified, using the named assembly file and the constructor that best matches the specified parameters. A handle that must be unwrapped to access the newly created object, or for instances. - method to unwrap the return value. - - For information about other exceptions that can be thrown by invoked methods, see the Exceptions section of the and methods. - + method to unwrap the return value. + + For information about other exceptions that can be thrown by invoked methods, see the Exceptions section of the and methods. + ]]> @@ -2453,10 +2453,10 @@ Note: In .NET for Win is not an empty array, and the type being created does not derive from . - is not a valid assembly. - - -or- - + is not a valid assembly. + + -or- + The common language runtime (CLR) version 2.0 or later is currently loaded, and was compiled for a version of the CLR that is later than the currently loaded version. Note that the .NET Framework versions 2.0, 3.0, and 3.5 all use CLR version 2.0. @@ -2493,16 +2493,16 @@ Note: In .NET for Win System.Runtime.Remoting.ObjectHandle - - - - - - - - - - + + + + + + + + + + The remote domain where the type named is created. @@ -2514,22 +2514,22 @@ Note: In .NET for Win An object that uses and to seek and identify the constructor. If is , the default binder is used. An array of arguments that match in number, order, and type the parameters of the constructor to invoke. If is an empty array or , the constructor that takes no parameters (the parameterless constructor) is invoked. Culture-specific information that governs the coercion of to the formal types declared for the constructor. If is , the for the current thread is used. - An array of one or more attributes that can participate in activation. This is typically an array that contains a single object that specifies the URL that is required to activate a remote object. - + An array of one or more attributes that can participate in activation. This is typically an array that contains a single object that specifies the URL that is required to activate a remote object. + This parameter is related to client-activated objects. Client activation is a legacy technology that is retained for backward compatibility but is not recommended for new development. Distributed applications should instead use Windows Communication Foundation. Information used to make security policy decisions and grant code permissions. Creates an instance of the type whose name is specified in the specified remote domain, using the named assembly file and the constructor that best matches the specified parameters. A handle that must be unwrapped to access the newly created object, or for instances. - when a host needs to execute code in an application domain that has restricted security permissions. - + when a host needs to execute code in an application domain that has restricted security permissions. + Use the method to unwrap the return value. - - For information about other exceptions that can be thrown by invoked methods, see the Exceptions section of the and methods. - + + For information about other exceptions that can be thrown by invoked methods, see the Exceptions section of the and methods. + ]]> @@ -2546,10 +2546,10 @@ Note: In .NET for Win is not an empty array, and the type being created does not derive from . - is not a valid assembly. - - -or- - + is not a valid assembly. + + -or- + The common language runtime (CLR) version 2.0 or later is currently loaded, and was compiled for a version of the CLR that is later than the currently loaded version. Note that the .NET Framework versions 2.0, 3.0, and 3.5 all use CLR version 2.0. @@ -2593,8 +2593,8 @@ Note: In .NET for Win System.Object - - + + The type of the well-known object to which you want to connect. @@ -2602,11 +2602,11 @@ Note: In .NET for Win Creates a proxy for the well-known object indicated by the specified type and URL. A proxy that points to an endpoint served by the requested well-known object. - @@ -2648,9 +2648,9 @@ Note: In .NET for Win System.Object - - - + + + The type of the well-known object to which you want to connect. @@ -2659,13 +2659,13 @@ Note: In .NET for Win Creates a proxy for the well-known object indicated by the specified type, URL, and channel data. A proxy that points to an endpoint served by the requested well-known object. - method. - + method. + ]]> @@ -2704,11 +2704,11 @@ Note: In .NET for Win System.Void - - - - - + + + + + Reserved for future use. Must be IID_NULL. @@ -2718,11 +2718,11 @@ Note: In .NET for Win The caller-allocated array that receives the IDs corresponding to the names. Maps a set of names to a corresponding set of dispatch identifiers. - Late-bound access using the COM IDispatch interface is not supported. @@ -2755,9 +2755,9 @@ Note: In .NET for Win System.Void - - - + + + The type information to return. @@ -2765,11 +2765,11 @@ Note: In .NET for Win An object that receives a pointer to the requested type information object. Retrieves the type information for an object, which can then be used to get the type information for an interface. - Late-bound access using the COM IDispatch interface is not supported. @@ -2802,17 +2802,17 @@ Note: In .NET for Win System.Void - + When this method returns, contains a pointer to a location that receives the number of type information interfaces provided by the object. This parameter is passed uninitialized. Retrieves the number of type information interfaces that an object provides (either 0 or 1). - Late-bound access using the COM IDispatch interface is not supported. @@ -2845,14 +2845,14 @@ Note: In .NET for Win System.Void - - - - - - - - + + + + + + + + A dispatch identifier that identifies the member. @@ -2865,11 +2865,11 @@ Note: In .NET for Win The index of the first argument that has an error. Provides access to properties and methods exposed by an object. - Late-bound access using the COM IDispatch interface is not supported. diff --git a/xml/System/AggregateException.xml b/xml/System/AggregateException.xml index f47386113d8..8a33abb6be7 100644 --- a/xml/System/AggregateException.xml +++ b/xml/System/AggregateException.xml @@ -77,20 +77,20 @@ Represents one or more errors that occur during application execution. - is used to consolidate multiple failures into a single, throwable exception object. It is used extensively in the [Task Parallel Library (TPL)](/dotnet/standard/parallel-programming/task-parallel-library-tpl) and [Parallel LINQ (PLINQ)](/dotnet/standard/parallel-programming/parallel-linq-plinq). For more information, see [Exception Handling](/dotnet/standard/parallel-programming/exception-handling-task-parallel-library) and [How to: Handle Exceptions in a PLINQ Query](/dotnet/standard/parallel-programming/how-to-handle-exceptions-in-a-plinq-query). For additional information, see the [Aggregating Exceptions](https://docs.microsoft.com/archive/msdn-magazine/2009/brownfield/aggregating-exceptions) entry in the .NET Matters blog. - - - -## Examples - The following example catches the exception and calls the method to handle each exception it contains. Compiling and running the example with the first `task1` variable should result in an object that contains an exception. Commenting out that line, uncommenting the second `task1` variable, and compiling and running the example produces an object that contains an exception. - + is used to consolidate multiple failures into a single, throwable exception object. It is used extensively in the [Task Parallel Library (TPL)](/dotnet/standard/parallel-programming/task-parallel-library-tpl) and [Parallel LINQ (PLINQ)](/dotnet/standard/parallel-programming/parallel-linq-plinq). For more information, see [Exception Handling](/dotnet/standard/parallel-programming/exception-handling-task-parallel-library) and [How to: Handle Exceptions in a PLINQ Query](/dotnet/standard/parallel-programming/how-to-handle-exceptions-in-a-plinq-query). For additional information, see the [Aggregating Exceptions](https://docs.microsoft.com/archive/msdn-magazine/2009/brownfield/aggregating-exceptions) entry in the .NET Matters blog. + + + +## Examples + The following example catches the exception and calls the method to handle each exception it contains. Compiling and running the example with the first `task1` variable should result in an object that contains an exception. Commenting out that line, uncommenting the second `task1` variable, and compiling and running the example produces an object that contains an exception. + :::code language="csharp" source="~/snippets/csharp/System/AggregateException/Overview/exception1.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.aggregateexception.class/fs/exception1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.aggregateexception.class/vb/exception1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.aggregateexception.class/vb/exception1.vb" id="Snippet1"::: + ]]> All public and protected members of are thread-safe and may be used concurrently from multiple threads. @@ -143,18 +143,18 @@ Initializes a new instance of the class with a system-supplied message that describes the error. - property of the new instance to a system-supplied message that describes the error, such as "System.AggregateException: One or more errors occurred." This message takes into account the current system culture. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||`null`.| -||The localized error message string.| - + property of the new instance to a system-supplied message that describes the error, such as "System.AggregateException: One or more errors occurred." This message takes into account the current system culture. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||`null`.| +||The localized error message string.| + ]]> Handling and Throwing Exceptions @@ -305,16 +305,16 @@ The message that describes the exception. The caller of this constructor is required to ensure that this string has been localized for the current system culture. Initializes a new instance of the class with a specified message that describes the error. - . - -|Property|Value| -|--------------|-----------| -||`null`.| -||The error message string specified in `message`.| - + . + +|Property|Value| +|--------------|-----------| +||`null`.| +||The error message string specified in `message`.| + ]]> Handling and Throwing Exceptions @@ -367,19 +367,19 @@ - - + + The object that holds the serialized object data. The contextual information about the source or destination. Initializes a new instance of the class with serialized data. - The argument is null. @@ -493,18 +493,18 @@ The exception that is the cause of the current exception. If the parameter is not , the current exception is raised in a block that handles the inner exception. Initializes a new instance of the class with a specified error message and a reference to the inner exception that is the cause of this exception. - property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||`null`.| -||The error message string specified in `message`.| - + property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||`null`.| +||The error message string specified in `message`.| + ]]> The argument is null. @@ -615,28 +615,28 @@ Flattens an instances into a single, new instance. A new, flattened . - exception before it is propagated to the parent task, which wraps that exception in its own exception before it propagates it back to the calling thread. In such cases, the property of the exception that is caught by the , , or method contains one or more instances, not the original exceptions that caused the fault. To avoid having to iterate over nested exceptions, you can use the method to remove all the nested exceptions, so that the property of the returned object contains the original exceptions. - - This method recursively flattens all instances of exceptions that are inner exceptions of the current instance. The inner exceptions returned in the new are the union of all the inner exceptions from exception tree rooted at the current instance. - - - -## Examples - In the following example, nested instances are flattened and handled in just one loop. - + exception before it is propagated to the parent task, which wraps that exception in its own exception before it propagates it back to the calling thread. In such cases, the property of the exception that is caught by the , , or method contains one or more instances, not the original exceptions that caused the fault. To avoid having to iterate over nested exceptions, you can use the method to remove all the nested exceptions, so that the property of the returned object contains the original exceptions. + + This method recursively flattens all instances of exceptions that are inner exceptions of the current instance. The inner exceptions returned in the new are the union of all the inner exceptions from exception tree rooted at the current instance. + + + +## Examples + In the following example, nested instances are flattened and handled in just one loop. + :::code language="csharp" source="~/snippets/csharp/System/AggregateException/Flatten/flatten2.cs" id="Snippet22"::: :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_Misc/tpl_exceptions/fs/flatten2.fs" id="Snippet22"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/tpl_exceptions/vb/flatten2.vb" id="Snippet22"::: - - You can also use the method to rethrow the inner exceptions from multiple instances thrown by multiple tasks in a single instance, as the following example shows. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/tpl_exceptions/vb/flatten2.vb" id="Snippet22"::: + + You can also use the method to rethrow the inner exceptions from multiple instances thrown by multiple tasks in a single instance, as the following example shows. + :::code language="csharp" source="~/snippets/csharp/System/AggregateException/Flatten/taskexceptions2.cs" id="Snippet13"::: :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_Misc/tpl_exceptions/fs/taskexceptions2.fs" id="Snippet13"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/tpl_exceptions/vb/taskexceptions2.vb" id="Snippet13"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/tpl_exceptions/vb/taskexceptions2.vb" id="Snippet13"::: + ]]> Exception Handling (Task Parallel Library) @@ -737,19 +737,19 @@ System.Void - - + + The object that holds the serialized object data. The contextual information about the source or destination. Initializes a new instance of the class with serialized data. - The argument is null. @@ -800,24 +800,24 @@ The predicate to execute for each exception. The predicate accepts as an argument the to be processed and returns a Boolean to indicate whether the exception was handled. Invokes a handler on each contained by this . - was handled. After all invocations, if any exceptions went unhandled, all unhandled exceptions will be put into a new which will be thrown. Otherwise, the method simply returns. If any invocations of the `predicate` throws an exception, it will halt the processing of any more exceptions and immediately propagate the thrown exception as-is. - -## Examples - Ordinarily, an exception handler that catches an exception uses a `foreach` loop (in C#) or `For Each` loop (in Visual Basic) to handle each exception in its collection. Instead, the following example uses the method to handle each exception, and only rethrows exceptions that are not `CustomException` instances. - + +## Examples + Ordinarily, an exception handler that catches an exception uses a `foreach` loop (in C#) or `For Each` loop (in Visual Basic) to handle each exception in its collection. Instead, the following example uses the method to handle each exception, and only rethrows exceptions that are not `CustomException` instances. + :::code language="csharp" source="~/snippets/csharp/System/AggregateException/Handle/handlemethod2.cs" id="Snippet16"::: :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_Misc/tpl_exceptions/fs/handlemethod2.fs" id="Snippet16"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/tpl_exceptions/vb/handlemethod2.vb" id="Snippet16"::: - - The following is a more complete example that uses the method to provide special handling for an when enumerating files. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/tpl_exceptions/vb/handlemethod2.vb" id="Snippet16"::: + + The following is a more complete example that uses the method to provide special handling for an when enumerating files. + :::code language="csharp" source="~/snippets/csharp/System/AggregateException/Handle/taskexceptions.cs" id="Snippet12"::: :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_Misc/tpl_exceptions/fs/taskexceptions.fs" id="Snippet12"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/tpl_exceptions/vb/taskexceptions.vb" id="Snippet12"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/tpl_exceptions/vb/taskexceptions.vb" id="Snippet12"::: + ]]> The argument is null. diff --git a/xml/System/AppContext.xml b/xml/System/AppContext.xml index ae7632845c2..e69ec9befe7 100644 --- a/xml/System/AppContext.xml +++ b/xml/System/AppContext.xml @@ -165,7 +165,7 @@ In .NET 5 and later versions, for bundled assemblies, the value returned is the System.Object - + The name of the data element. diff --git a/xml/System/AppDomain.xml b/xml/System/AppDomain.xml index 5a0749abecd..8ee5b0ef44e 100644 --- a/xml/System/AppDomain.xml +++ b/xml/System/AppDomain.xml @@ -867,8 +867,8 @@ Application domains, which are represented by objects, h System.Runtime.Remoting.ObjectHandle - - + + The name of a file containing an assembly that defines the requested type. @@ -953,10 +953,10 @@ Application domains, which are represented by objects, h System.Runtime.Remoting.ObjectHandle - - - - + + + + The name of a file containing an assembly that defines the requested type. @@ -1123,8 +1123,8 @@ This method overload uses the information from the System.AppDomain - - + + The friendly name of the domain. This friendly name can be displayed in user interfaces to identify the domain. For more information, see . @@ -1191,9 +1191,9 @@ This method overload uses the information from the System.AppDomain - - - + + + The friendly name of the domain. This friendly name can be displayed in user interfaces to identify the domain. For more information, see . @@ -1260,11 +1260,11 @@ This method overload uses the information from the System.AppDomain - - - - - + + + + + [System.ParamArray] @@ -1335,11 +1335,11 @@ This method overload uses the information from the System.AppDomain - - - - - + + + + + The friendly name of the domain. This friendly name can be displayed in user interfaces to identify the domain. For more information, see . @@ -1408,13 +1408,13 @@ This method overload uses the information from the System.AppDomain - - - - - - - + + + + + + + The friendly name of the domain. This friendly name can be displayed in user interfaces to identify the domain. For more information, see . @@ -1798,15 +1798,15 @@ This method overload uses the information from the System.Runtime.Remoting.ObjectHandle - - - - - - - - - + + + + + + + + + The display name of the assembly. See . @@ -2181,7 +2181,7 @@ This method overload uses the information from the The caller cannot provide activation attributes for an object that does not inherit from . The operation is attempted on an unloaded application domain. - is not a valid assembly for the currently loaded runtime. + is not a valid assembly for the currently loaded runtime. An assembly or module was loaded twice with two different evidences. @@ -2224,15 +2224,15 @@ This method overload uses the information from the System.Object - - - - - - - - - + + + + + + + + + The display name of the assembly. See . @@ -2685,15 +2685,15 @@ This method overload uses the information from the System.Runtime.Remoting.ObjectHandle - - - - - - - - - + + + + + + + + + The name, including the path, of a file that contains an assembly that defines the requested type. The assembly is loaded using the method. @@ -3106,15 +3106,15 @@ This method overload uses the information from the System.Object - - - - - - - - - + + + + + + + + + The file name and path of the assembly that defines the requested type. @@ -3262,8 +3262,8 @@ This method overload uses the information from the System.Reflection.Emit.AssemblyBuilder - - + + The unique identity of the dynamic assembly. @@ -3335,9 +3335,9 @@ This method overload uses the information from the System.Reflection.Emit.AssemblyBuilder - - - + + + The unique identity of the dynamic assembly. @@ -3424,9 +3424,9 @@ This method overload uses the information from the System.Reflection.Emit.AssemblyBuilder - - - + + + The unique identity of the dynamic assembly. @@ -3509,9 +3509,9 @@ This method overload uses the information from the System.Reflection.Emit.AssemblyBuilder - - - + + + The unique identity of the dynamic assembly. @@ -3583,10 +3583,10 @@ This method overload uses the information from the System.Reflection.Emit.AssemblyBuilder - - - - + + + + The unique identity of the dynamic assembly. @@ -3656,10 +3656,10 @@ This method overload uses the information from the System.Reflection.Emit.AssemblyBuilder - - - - + + + + The unique identity of the dynamic assembly. @@ -3745,11 +3745,11 @@ This method overload uses the information from the System.Reflection.Emit.AssemblyBuilder - - - - - + + + + + The unique identity of the dynamic assembly. @@ -3825,11 +3825,11 @@ This method overload uses the information from the System.Reflection.Emit.AssemblyBuilder - - - - - + + + + + The unique identity of the dynamic assembly. @@ -3901,12 +3901,12 @@ This method overload uses the information from the System.Reflection.Emit.AssemblyBuilder - - - - - - + + + + + + The unique identity of the dynamic assembly. @@ -3996,12 +3996,12 @@ This method overload uses the information from the System.Reflection.Emit.AssemblyBuilder - - - - - - + + + + + + The unique identity of the dynamic assembly. @@ -4087,13 +4087,13 @@ This method overload uses the information from the System.Reflection.Emit.AssemblyBuilder - - - - - - - + + + + + + + The unique identity of the dynamic assembly. @@ -4184,14 +4184,14 @@ This method overload uses the information from the System.Reflection.Emit.AssemblyBuilder - - - - - - - - + + + + + + + + The unique identity of the dynamic assembly. @@ -4280,15 +4280,15 @@ This method overload uses the information from the System.Reflection.Emit.AssemblyBuilder - - - - - - - - - + + + + + + + + + The unique identity of the dynamic assembly. @@ -4365,7 +4365,7 @@ This method overload uses the information from the System.Void - + A delegate that specifies a method to call. @@ -4816,8 +4816,8 @@ This method overload uses the information from the System.Int32 - - + + The name of the file that contains the assembly to execute. @@ -4994,9 +4994,9 @@ This method overload uses the information from the System.Int32 - - - + + + The name of the file that contains the assembly to execute. @@ -5188,11 +5188,11 @@ This method overload uses the information from the System.Int32 - - - - - + + + + + The name of the file that contains the assembly to execute. @@ -5439,8 +5439,8 @@ This method overload uses the information from the System.Int32 - - + + The display name of the assembly. See . @@ -5591,9 +5591,9 @@ This method overload uses the information from the System.Int32 - - - + + + [System.ParamArray] @@ -5669,9 +5669,9 @@ This method overload uses the information from the System.Int32 - - - + + + [System.ParamArray] @@ -6991,8 +6991,8 @@ This method overload uses the information from the System.Reflection.Assembly - - + + An object that describes the assembly to load. @@ -7058,8 +7058,8 @@ This method overload uses the information from the System.Reflection.Assembly - - + + The display name of the assembly. See . @@ -7125,9 +7125,9 @@ This method overload uses the information from the System.Reflection.Assembly - - - + + + An array of type that is a COFF-based image containing an emitted assembly. @@ -7941,7 +7941,7 @@ This method overload uses the information from the System.Void - + The security policy level. @@ -8190,9 +8190,9 @@ This method overload uses the information from the System.Void - - - + + + The name of a user-defined application domain property to create or change. @@ -8763,11 +8763,11 @@ This method overload uses the information from the System.Void - - - - - + + + + + Reserved for future use. Must be IID_NULL. @@ -8817,9 +8817,9 @@ This method overload uses the information from the System.Void - - - + + + The type information to return. @@ -8867,7 +8867,7 @@ This method overload uses the information from the System.Void - + When this method returns, points to a location that receives the number of type information interfaces provided by the object. @@ -8913,14 +8913,14 @@ This method overload uses the information from the System.Void - - - - - - - - + + + + + + + + Identifies the member. diff --git a/xml/System/AppDomainSetup.xml b/xml/System/AppDomainSetup.xml index d8d1e7d0fba..29d8c62f572 100644 --- a/xml/System/AppDomainSetup.xml +++ b/xml/System/AppDomainSetup.xml @@ -70,16 +70,16 @@ Represents assembly binding information that can be added to an instance of . - instance does not affect any existing . It can affect only the creation of a new , when the method is called with the instance as a parameter. - - This class implements the interface. - + instance does not affect any existing . It can affect only the creation of a new , when the method is called with the instance as a parameter. + + This class implements the interface. + > [!CAUTION] -> The default value for the property is false. This setting is unsafe for services. To help prevent services from downloading partially trusted code, set this property to true - +> The default value for the property is false. This setting is unsafe for services. To help prevent services from downloading partially trusted code, set this property to true + ]]> How To: Configure an Application Domain @@ -96,11 +96,11 @@ - - - - - + + + + + Constructor mscorlib @@ -147,17 +147,17 @@ - + The activation context to be used for an application domain. Initializes a new instance of the class with the specified activation context to use for manifest-based activation of an application domain. - object specified for `activationContext` is used to generate an object containing information required to activate a new application domain. This object can be accessed by using the property. - + object specified for `activationContext` is used to generate an object containing information required to activate a new application domain. This object can be accessed by using the property. + ]]> @@ -193,17 +193,17 @@ - + An object that specifies information required for the manifest-based activation of a new application domain. Initializes a new instance of the class with the specified activation arguments required for manifest-based activation of an application domain. - property. - + property. + ]]> @@ -242,13 +242,13 @@ Gets or sets data about the activation of an application domain. An object that contains data about the activation of an application domain. - object supports manifest-based activation. - + object supports manifest-based activation. + ]]> The property is set to an object whose application identity does not match the application identity of the object returned by the property. No exception is thrown if the property is . @@ -280,23 +280,23 @@ Gets or sets the delegate, which represents a callback method that is invoked when the application domain is initialized. A delegate that represents a callback method that is invoked when the application domain is initialized. - property. The array is passed to the callback method each time an is initialized. - - The callback method is executed in the context of the newly created application domain. - - - -## Examples - The following example creates a child application domain named `ChildDomain`, using an object and evidence from the default application domain. The property is set to the callback method `AppDomainInit`, which is invoked when the child domain is initialized. The arguments for the callback method are placed in an array of strings, which is assigned to the property. When the child domain is created, the callback method simply prints the strings. - + property. The array is passed to the callback method each time an is initialized. + + The callback method is executed in the context of the newly created application domain. + + + +## Examples + The following example creates a child application domain named `ChildDomain`, using an object and evidence from the default application domain. The property is set to the callback method `AppDomainInit`, which is invoked when the child domain is initialized. The arguments for the callback method are placed in an array of strings, which is assigned to the property. When the child domain is created, the callback method simply prints the strings. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/AppDomainInitializer/cpp/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System/AppDomainSetup/AppDomainInitializer/source.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System/AppDomainSetup/AppDomainInitializer/source.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/AppDomainInitializer/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/AppDomainInitializer/VB/source.vb" id="Snippet1"::: + ]]> @@ -329,23 +329,23 @@ Gets or sets the arguments passed to the callback method represented by the delegate. The callback method is invoked when the application domain is initialized. An array of strings that is passed to the callback method represented by the delegate, when the callback method is invoked during initialization. - property to specify a callback method that is invoked during initialization. If the property is not set, the array assigned to this property is not used. - - The callback method is executed in the context of the newly created application domain. - - - -## Examples - The following code example creates a child application domain named `ChildDomain`, using an object and evidence from the default application domain. The property is set to the callback method `AppDomainInit`, which is invoked when the child domain is initialized. The arguments for the callback method are placed in an array of strings, which is assigned to the property. When the child domain is created, the callback method simply prints the strings. - + property to specify a callback method that is invoked during initialization. If the property is not set, the array assigned to this property is not used. + + The callback method is executed in the context of the newly created application domain. + + + +## Examples + The following code example creates a child application domain named `ChildDomain`, using an object and evidence from the default application domain. The property is set to the callback method `AppDomainInit`, which is invoked when the child domain is initialized. The arguments for the callback method are placed in an array of strings, which is assigned to the property. When the child domain is created, the callback method simply prints the strings. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/AppDomainInitializer/cpp/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System/AppDomainSetup/AppDomainInitializer/source.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System/AppDomainSetup/AppDomainInitializer/source.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/AppDomainInitializer/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/AppDomainInitializer/VB/source.vb" id="Snippet1"::: + ]]> @@ -377,21 +377,21 @@ Gets or sets the display name of the assembly that provides the type of the application domain manager for application domains created using this object. The display name of the assembly that provides the of the application domain manager. - property. If either of these properties is not set, the other is ignored. - - If no type is provided, the application domain manager is created from the same type as the parent application domain (that is, the application domain from which the method is called). - - When the application domain is loaded, is thrown if the assembly does not exist, or if the assembly does not contain the type specified by the property. is thrown if the assembly is found but the version information does not match. - - To set the application domain manager for the default application domain, use the [\](/dotnet/framework/configure-apps/file-schema/runtime/appdomainmanagerassembly-element) and [\](/dotnet/framework/configure-apps/file-schema/runtime/appdomainmanagertype-element) elements in the [\](/dotnet/framework/configure-apps/file-schema/runtime/runtime-element) section of the application configuration file, or use the environment variables described in . - - This feature requires the application to have full trust. (For example, an application running on the desktop has full trust.) If the application does not have full trust, a is thrown. - - The format of the assembly display name is given by the property. - + property. If either of these properties is not set, the other is ignored. + + If no type is provided, the application domain manager is created from the same type as the parent application domain (that is, the application domain from which the method is called). + + When the application domain is loaded, is thrown if the assembly does not exist, or if the assembly does not contain the type specified by the property. is thrown if the assembly is found but the version information does not match. + + To set the application domain manager for the default application domain, use the [\](/dotnet/framework/configure-apps/file-schema/runtime/appdomainmanagerassembly-element) and [\](/dotnet/framework/configure-apps/file-schema/runtime/appdomainmanagertype-element) elements in the [\](/dotnet/framework/configure-apps/file-schema/runtime/runtime-element) section of the application configuration file, or use the environment variables described in . + + This feature requires the application to have full trust. (For example, an application running on the desktop has full trust.) If the application does not have full trust, a is thrown. + + The format of the assembly display name is given by the property. + ]]> @@ -421,21 +421,21 @@ Gets or sets the full name of the type that provides the application domain manager for application domains created using this object. The full name of the type, including the namespace. - property. If either of these properties is not set, the other is ignored. - - If no type is provided, the application domain manager is created from the same type as the parent application domain (that is, the application domain from which the method is called). - - When the application domain is loaded, is thrown if the assembly specified by the property does not contain the type specified by this property. - - To set the application domain manager for the default application domain, use the [\](/dotnet/framework/configure-apps/file-schema/runtime/appdomainmanagerassembly-element) and [\](/dotnet/framework/configure-apps/file-schema/runtime/appdomainmanagertype-element) elements in the [\](/dotnet/framework/configure-apps/file-schema/runtime/runtime-element) section of the application configuration file, or use the environment variables described in . - - This feature requires the application to have full trust. (For example, an application running on the desktop has full trust.) If the application does not have full trust, a is thrown. - - The format of the full name of a type is given by the property. - + property. If either of these properties is not set, the other is ignored. + + If no type is provided, the application domain manager is created from the same type as the parent application domain (that is, the application domain from which the method is called). + + When the application domain is loaded, is thrown if the assembly specified by the property does not contain the type specified by this property. + + To set the application domain manager for the default application domain, use the [\](/dotnet/framework/configure-apps/file-schema/runtime/appdomainmanagerassembly-element) and [\](/dotnet/framework/configure-apps/file-schema/runtime/appdomainmanagertype-element) elements in the [\](/dotnet/framework/configure-apps/file-schema/runtime/runtime-element) section of the application configuration file, or use the environment variables described in . + + This feature requires the application to have full trust. (For example, an application running on the desktop has full trust.) If the application does not have full trust, a is thrown. + + The format of the full name of a type is given by the property. + ]]> @@ -488,26 +488,26 @@ Gets the name of the directory containing the application. The name of the application base directory. - property can influence which permissions are granted to an application domain. For example, an application domain originating from the local computer normally receives full trust based on its location of origin. However, if the property of that is set to the full name of an intranet directory, the setting restricts the permissions granted to the application domain to a LocalIntranet grant even though the application domain actually originates from the local computer. - - - -## Examples - The following example demonstrates how to use the property to set the location where the assembly loader begins probing for assemblies to load into a new application domain. - + property can influence which permissions are granted to an application domain. For example, an application domain originating from the local computer normally receives full trust based on its location of origin. However, if the property of that is set to the full name of an intranet directory, the setting restricts the permissions granted to the application domain to a LocalIntranet grant even though the application domain actually originates from the local computer. + + + +## Examples + The following example demonstrates how to use the property to set the location where the assembly loader begins probing for assemblies to load into a new application domain. + > [!NOTE] -> You must ensure that the folder you specify exists. - +> You must ensure that the folder you specify exists. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/ADApplicationBase/CPP/adapplicationbase.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System/AppDomain/CurrentDomain/adapplicationbase.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System/AppDomain/CurrentDomain/adapplicationbase.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ADApplicationBase/VB/adapplicationbase.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ADApplicationBase/VB/adapplicationbase.vb" id="Snippet1"::: + ]]> @@ -542,22 +542,22 @@ Gets or sets the name of the application. The name of the application. - property when you create a new application domain. - - The example creates a new application domain, and then calls the method to load the example assembly into the new application domain and create an instance of the `Worker` class. The `Worker` class inherits , so the example can use the proxy returned by to call the `TestLoad` method. - - The `TestLoad` method loads an assembly that you specify. You must either specify a valid, fully qualified assembly name, or comment out the method. The `TestLoad` method lists the assemblies that are loaded into the new application domain, showing that your specified assembly and the example assembly are loaded. - - The example uses the attribute to tell the assembly loader how the application will share code across application domains. - + property when you create a new application domain. + + The example creates a new application domain, and then calls the method to load the example assembly into the new application domain and create an instance of the `Worker` class. The `Worker` class inherits , so the example can use the proxy returned by to call the `TestLoad` method. + + The `TestLoad` method loads an assembly that you specify. You must either specify a valid, fully qualified assembly name, or comment out the method. The `TestLoad` method lists the assemblies that are loaded into the new application domain, showing that your specified assembly and the example assembly are loaded. + + The example uses the attribute to tell the assembly loader how the application will share code across application domains. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/ADMultiDomain/CPP/admultidomain.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System/AppDomainSetup/ApplicationName/admultidomain.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System/AppDomainSetup/ApplicationName/admultidomain.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ADMultiDomain/VB/admultidomain.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ADMultiDomain/VB/admultidomain.vb" id="Snippet1"::: + ]]> @@ -598,11 +598,11 @@ Gets or sets an object containing security and trust information. An object that contains security and trust information. - is created. Once changed, it cannot be reset to a null reference. - + is created. Once changed, it cannot be reset to a null reference. + ]]> The property is set to an object whose application identity does not match the application identity of the object returned by the property. No exception is thrown if the property is . @@ -645,13 +645,13 @@ Gets or sets the name of an area specific to the application where files are shadow copied. The fully qualified name of the directory path and file name where files are shadow copied. - property must also be set. If the property is not set, the property is ignored and the shadow copy cache location defaults to the download cache. - - For more information on shadow copying, see [Shadow Copying Assemblies](/dotnet/framework/app-domains/shadow-copy-assemblies). - + property must also be set. If the property is not set, the property is ignored and the shadow copy cache location defaults to the download cache. + + For more information on shadow copying, see [Shadow Copying Assemblies](/dotnet/framework/app-domains/shadow-copy-assemblies). + ]]> @@ -695,13 +695,13 @@ Gets or sets the name of the configuration file for an application domain. The name of the configuration file. - Runtime Settings Schema @@ -734,13 +734,13 @@ if probing is not allowed; otherwise, . The default is . - property is `true`, the value of the property is ignored. That is, no assemblies are probed for in the directories specified by the property. In addition, the values of the property and the property are ignored. No assemblies are probed for in the directories specified by the property. - - The property provides an additional layer of control over the loading process. In the normal assembly loading sequence, the application base is probed before the event is raised. However, some applications might need to load assemblies from an OLE compound file within a document, or from a unique known location that is neither in the global assembly cache nor in the directories specified by the and properties. Such applications can use the property to avoid the delay caused by normal probing, and to avoid loading copies of the necessary assembly that might be located in the normal probing paths. - + property is `true`, the value of the property is ignored. That is, no assemblies are probed for in the directories specified by the property. In addition, the values of the property and the property are ignored. No assemblies are probed for in the directories specified by the property. + + The property provides an additional layer of control over the loading process. In the normal assembly loading sequence, the application base is probed before the event is raised. However, some applications might need to load assemblies from an OLE compound file within a document, or from a unique known location that is neither in the global assembly cache nor in the directories specified by the and properties. Such applications can use the property to avoid the delay caused by normal probing, and to avoid loading copies of the necessary assembly that might be located in the normal probing paths. + ]]> @@ -773,13 +773,13 @@ if redirection of assemblies is not allowed; if it is allowed. - property is designed to be used by services and server applications where assembly binding redirection is not part of the application scenario. - + property is designed to be used by services and server applications where assembly binding redirection is not part of the application scenario. + The value of this property is only considered when loading strong-named assemblies. Assemblies that do not have a strong-name will always have binding redirects applied. - + ]]> @@ -812,14 +812,14 @@ if HTTP download of assemblies is not allowed; if it is allowed. - property is designed to be used by services and server applications where downloading code from an intranet or the Internet is not part of the application scenario. - + property is designed to be used by services and server applications where downloading code from an intranet or the Internet is not part of the application scenario. + > [!CAUTION] -> The default value for the property is `false`. This setting is unsafe for services. To help prevent services from downloading partially trusted code, set this property to `true`. - +> The default value for the property is `false`. This setting is unsafe for services. To help prevent services from downloading partially trusted code, set this property to `true`. + ]]> @@ -852,13 +852,13 @@ if the section of the configuration file for an application domain is ignored; if the declared publisher policy is honored. - property specifically applies to a Web application that is loaded locally. Use this property to help prevent a malicious attempt to execute an unsafe Web application in safe mode. - - For more information about bypassing publisher policy, see the [Redirecting Assembly Versions](/dotnet/framework/configure-apps/redirect-assembly-versions) topic. For more information about safe mode, see the "Examining the Configuration Files" section of the [How the Runtime Locates Assemblies](/dotnet/framework/deployment/how-the-runtime-locates-assemblies) topic. - + property specifically applies to a Web application that is loaded locally. Use this property to help prevent a malicious attempt to execute an unsafe Web application in safe mode. + + For more information about bypassing publisher policy, see the [Redirecting Assembly Versions](/dotnet/framework/configure-apps/redirect-assembly-versions) topic. For more information about safe mode, see the "Examining the Configuration Files" section of the [How the Runtime Locates Assemblies](/dotnet/framework/deployment/how-the-runtime-locates-assemblies) topic. + ]]> @@ -903,39 +903,39 @@ Gets or sets the base directory where the directory for dynamically generated files is located. The directory where the is located. Note: The return value of this property is different from the value assigned. - property. Dynamic assemblies that will be loaded and executed by the new application domain can be placed there. + + When you assign a path to the property, an additional subdirectory is added; the name of this subdirectory is the hash code of the value assigned to the property. Thus, the base directory subsequently returned by this property is always different from the value assigned. -## Remarks - Use this property to set the base directory where the dynamic directory for the new application domain will be located. When code in the new application domain loads an assembly, assembly resolution looks first in the normal probing paths. If it does not find the assembly, it looks in the dynamic directory, which is returned by the property. Dynamic assemblies that will be loaded and executed by the new application domain can be placed there. - - When you assign a path to the property, an additional subdirectory is added; the name of this subdirectory is the hash code of the value assigned to the property. Thus, the base directory subsequently returned by this property is always different from the value assigned. - > [!IMPORTANT] -> Assigning a value to this property does not create any directories. The directories must be created or verified by the code that uses them. - +> Assigning a value to this property does not create any directories. The directories must be created or verified by the code that uses them. + The dynamic directory is a subdirectory of . Its simple name is the value returned by the property, so its format is *original path*\\*hash code*\\*application name*. - -## Examples - The following example demonstrates how to use the property to set the path an application domain probes when loading dynamic assemblies. - - The example creates an object and sets its property to "Example" and its property to "C:\DynamicAssemblyDir". The example then displays the property, to show that the hash code of the application name has been appended as a subdirectory of the path that was originally assigned. - + +## Examples + The following example demonstrates how to use the property to set the path an application domain probes when loading dynamic assemblies. + + The example creates an object and sets its property to "Example" and its property to "C:\DynamicAssemblyDir". The example then displays the property, to show that the hash code of the application name has been appended as a subdirectory of the path that was originally assigned. + > [!NOTE] -> The base directory in this example is intended to be outside the probing path for the example application. Be sure to compile the example in a different location. Delete the base directory and all its subdirectories each time you run the example. - - The example creates a new application domain using the object. The example then creates the dynamic directory if it does not already exist. Although the example uses the application domain's property to get the name of the dynamic directory, it could just as easily create the directory beforehand by concatenating the original path, the hash code of the application name, and the application name. - - The example has a `GenerateDynamicAssembly` method that emits an assembly named `DynamicHelloWorld.dll` and stores it in the new application domain's dynamic directory. The dynamic assembly contains one type, `HelloWorld`, that has a static method (`Shared` method in Visual Basic) named `HelloFromAD`. Calling this method displays the name of the application domain. - - The `Example` class derives from , so the example can create an instance of the class in the new application domain and call its `Test` method. The `Test` method loads the dynamic assembly by its display name and calls the static `HelloFromAD` method. - - You can show that the dynamic directory is searched after the normal probing paths by writing code for an assembly named `DynamicHelloWorld.dll` and compiling it in the same directory as this example. The assembly must have a class named `HelloWorld` with a static method named `HelloFromAD`. This method does not have to have the same functionality as the one in the example; it can simply display a string to the console. The assembly must also have an attribute that sets its version to 1.0.0.0. When you run the example, the assembly you compiled in the current directory is found before the dynamic directory is searched. - +> The base directory in this example is intended to be outside the probing path for the example application. Be sure to compile the example in a different location. Delete the base directory and all its subdirectories each time you run the example. + + The example creates a new application domain using the object. The example then creates the dynamic directory if it does not already exist. Although the example uses the application domain's property to get the name of the dynamic directory, it could just as easily create the directory beforehand by concatenating the original path, the hash code of the application name, and the application name. + + The example has a `GenerateDynamicAssembly` method that emits an assembly named `DynamicHelloWorld.dll` and stores it in the new application domain's dynamic directory. The dynamic assembly contains one type, `HelloWorld`, that has a static method (`Shared` method in Visual Basic) named `HelloFromAD`. Calling this method displays the name of the application domain. + + The `Example` class derives from , so the example can create an instance of the class in the new application domain and call its `Test` method. The `Test` method loads the dynamic assembly by its display name and calls the static `HelloFromAD` method. + + You can show that the dynamic directory is searched after the normal probing paths by writing code for an assembly named `DynamicHelloWorld.dll` and compiling it in the same directory as this example. The assembly must have a class named `HelloWorld` with a static method named `HelloFromAD`. This method does not have to have the same functionality as the one in the example; it can simply display a string to the console. The assembly must also have an attribute that sets its version to 1.0.0.0. When you run the example, the assembly you compiled in the current directory is found before the dynamic directory is searched. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/ADDynamicBase/CPP/addynamicbase.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System/AppDomain/DynamicDirectory/addynamicbase.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System/AppDomain/DynamicDirectory/addynamicbase.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ADDynamicBase/VB/addynamicbase.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ADDynamicBase/VB/addynamicbase.vb" id="Snippet1"::: + ]]> This property cannot be set because the application name on the application domain is . @@ -968,18 +968,18 @@ Returns the XML configuration information set by the method, which overrides the application's XML configuration information. An array that contains the XML configuration information that was set by the method, or if the method has not been called. - method provides a way to override the configuration information of an application that creates a new application domain. The configuration file information in `value` overrides the configuration file information for the application. For example, when the Example.exe application creates a new application domain, it can override the configuration information originally obtained from Example.exe.config file. - + method provides a way to override the configuration information of an application that creates a new application domain. The configuration file information in `value` overrides the configuration file information for the application. For example, when the Example.exe application creates a new application domain, it can override the configuration information originally obtained from Example.exe.config file. + > [!IMPORTANT] -> Some consumers of configuration file information do not use the information stored by the method. The runtime does not enforce this. To ensure that all configuration file information is overridden in a new application domain, use the property to specify a configuration file. The method does affect assembly binding. - - The XML in `value` is the same as the XML in a normal configuration file, except that it is stored as a array. - - To access the configuration bytes for an application domain, use the property to get the object for the application domain, then use the method. - +> Some consumers of configuration file information do not use the information stored by the method. The runtime does not enforce this. To ensure that all configuration file information is overridden in a new application domain, use the property to specify a configuration file. The method does affect assembly binding. + + The XML in `value` is the same as the XML in a normal configuration file, except that it is stored as a array. + + To access the configuration bytes for an application domain, use the property to get the object for the application domain, then use the method. + ]]> @@ -1049,16 +1049,16 @@ Specifies the optimization policy used to load an executable. An enumerated constant that is used with the . - property to set the optimization policy used to load the assembly into an application domain. - + property to set the optimization policy used to load the assembly into an application domain. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/ADDyno/CPP/addyno.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System/AppDomain/CreateInstanceAndUnwrap/addyno.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System/AppDomain/CreateInstanceAndUnwrap/addyno.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ADDyno/VB/addyno.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ADDyno/VB/addyno.vb" id="Snippet1"::: + ]]> @@ -1088,19 +1088,19 @@ Gets or sets a list of assemblies marked with the flag that are made visible to partial-trust code running in a sandboxed application domain. An array of partial assembly names, where each partial name consists of the simple assembly name and the public key. - (APTCA) attribute can be made conditional by setting its property to . An APTCA assembly that is marked with cannot be used by partially trusted code unless the host application allows it. - - The host of a sandboxed application domain allows code in the application domain to use assemblies with conditional APTCA attributes by creating an array that contains the simple name and public key of each assembly, and assigning the array to this property. For example, an element of the array might look like the following: "MyAssembly, PublicKey=0024000004800000940000000602000000240000525341310004000001000100db2ad5e5fedc67ea526ff72ad426ef68e08e241d296c499eedfec6648dcc62b1a12f72be5833a45bbec481b68415b08a5fbc9f9ef247b523dd72bbea65bb532784ddc5c704544bd2f1c2d46fdbe41e4f949e76f9947357b2d5cf8ca9f970701bbd6e8ab64ad31b20ad0be9b56dae4f6b83332b92a2a3b8ea2804c40efbc0b6b9". - + (APTCA) attribute can be made conditional by setting its property to . An APTCA assembly that is marked with cannot be used by partially trusted code unless the host application allows it. + + The host of a sandboxed application domain allows code in the application domain to use assemblies with conditional APTCA attributes by creating an array that contains the simple name and public key of each assembly, and assigning the array to this property. For example, an element of the array might look like the following: "MyAssembly, PublicKey=0024000004800000940000000602000000240000525341310004000001000100db2ad5e5fedc67ea526ff72ad426ef68e08e241d296c499eedfec6648dcc62b1a12f72be5833a45bbec481b68415b08a5fbc9f9ef247b523dd72bbea65bb532784ddc5c704544bd2f1c2d46fdbe41e4f949e76f9947357b2d5cf8ca9f970701bbd6e8ab64ad31b20ad0be9b56dae4f6b83332b92a2a3b8ea2804c40efbc0b6b9". + > [!IMPORTANT] -> If you are using a subclass of , and the assembly that defines it depends on assemblies that are marked with the conditional APTCA attribute, you must include those assemblies in the list that you pass to the property of the you use to create application domains. Otherwise the assemblies that are marked with the conditional APTCA attribute will be disabled. - +> If you are using a subclass of , and the assembly that defines it depends on assemblies that are marked with the conditional APTCA attribute, you must include those assemblies in the list that you pass to the property of the you use to create application domains. Otherwise the assemblies that are marked with the conditional APTCA attribute will be disabled. + > [!NOTE] -> When you are debugging an application that is running in a sandboxed application domain, some messages can be misleading. For example, a message might state that one of your fully trusted assemblies has only limited permissions, when the real cause of the problem is that a security demand that exceeds the grant set of the sandboxed application domain has propagated to the boundary of the sandboxed application domain and failed. - +> When you are debugging an application that is running in a sandboxed application domain, some messages can be misleading. For example, a message might state that one of your fully trusted assemblies has only limited permissions, when the real cause of the problem is that a security demand that exceeds the grant set of the sandboxed application domain has propagated to the boundary of the sandboxed application domain and failed. + ]]> @@ -1144,11 +1144,11 @@ Gets or sets the list of directories under the application base directory that are probed for private assemblies. A list of directory names separated by semicolons. - are not under , they are ignored. - + are not under , they are ignored. + ]]> @@ -1183,11 +1183,11 @@ Gets or sets a string value that includes or excludes from the search path for the application, and searches only . A null reference ( in Visual Basic) to include the application base path when searching for assemblies; any non-null string value to exclude the path. The default value is . - (""), to exclude the application directory path - that is, - from the search path for the application, and to search for assemblies only in . - + (""), to exclude the application directory path - that is, - from the search path for the application, and to search for assemblies only in . + ]]> @@ -1219,13 +1219,13 @@ if interface caching is disabled for interop calls in application domains created with the current object; otherwise, . - @@ -1252,31 +1252,31 @@ System.Void - + An enumerable set of string values that specify compatibility switches, or to erase the existing compatibility switches. Sets the specified switches, making the application domain compatible with previous versions of the .NET Framework for the specified issues. - method to specify that one or more of these breaking changes should be rolled back for the application domain, to make the behavior compatible with the previous version of the .NET Framework. - - Each time you call this method, it replaces the existing switch settings. To erase the settings, specify `null` for the `switches` parameter. - - The set of string values you provide for `switches` can be a simple string array, because arrays implement the interface. - - The following table provides examples of compatibility switches that can be set to restore the behavior of earlier versions of the .NET Framework. - -|Switch|Meaning| -|------------|-------------| -|"NetFx40_LegacySecurityPolicy"|Code access security (CAS) for the .NET Framework 3.5 is enabled in this application domain. See [<NetFx40_LegacySecurityPolicy> Element](/dotnet/framework/configure-apps/file-schema/runtime/netfx40-legacysecuritypolicy-element).| -|"NetFx40_Legacy20SortingBehavior"|String sorting defaults for the .NET Framework 3.5 are enabled in this application domain. Successfully restoring legacy sorting behavior also requires the sort00001000.dll dynamic link library to be available on the local system. See [<CompatSortNLSVersion> Element](/dotnet/framework/configure-apps/file-schema/runtime/compatsortnlsversion-element).| -|"NetFx40_Legacy40SortingBehavior"|String sorting defaults for the .NET Framework 4 and Unicode 5.0 are enabled in this application domain. Successfully restoring legacy sorting behavior also requires the sort00060101.dll dynamic link library to be available on the local system.| -|"NetFx40_TimeSpanLegacyFormatMode"| formatting behavior for the .NET Framework 3.5 is enabled in this application domain. See [<TimeSpan_LegacyFormatMode> Element](/dotnet/framework/configure-apps/file-schema/runtime/timespan-legacyformatmode-element) and the "Restoring Legacy TimeSpan Formatting" section of the topic.| -|"UseRandomizedStringHashAlgorithm"|The runtime calculates hash codes for strings on a per application domain basis instead of using a single hashing algorithm that produces a consistent hash code across application domains. See [<UseRandomizedStringHashAlgorithm> Element](/dotnet/framework/configure-apps/file-schema/runtime/userandomizedstringhashalgorithm-element).| - + method to specify that one or more of these breaking changes should be rolled back for the application domain, to make the behavior compatible with the previous version of the .NET Framework. + + Each time you call this method, it replaces the existing switch settings. To erase the settings, specify `null` for the `switches` parameter. + + The set of string values you provide for `switches` can be a simple string array, because arrays implement the interface. + + The following table provides examples of compatibility switches that can be set to restore the behavior of earlier versions of the .NET Framework. + +|Switch|Meaning| +|------------|-------------| +|"NetFx40_LegacySecurityPolicy"|Code access security (CAS) for the .NET Framework 3.5 is enabled in this application domain. See [<NetFx40_LegacySecurityPolicy> Element](/dotnet/framework/configure-apps/file-schema/runtime/netfx40-legacysecuritypolicy-element).| +|"NetFx40_Legacy20SortingBehavior"|String sorting defaults for the .NET Framework 3.5 are enabled in this application domain. Successfully restoring legacy sorting behavior also requires the sort00001000.dll dynamic link library to be available on the local system. See [<CompatSortNLSVersion> Element](/dotnet/framework/configure-apps/file-schema/runtime/compatsortnlsversion-element).| +|"NetFx40_Legacy40SortingBehavior"|String sorting defaults for the .NET Framework 4 and Unicode 5.0 are enabled in this application domain. Successfully restoring legacy sorting behavior also requires the sort00060101.dll dynamic link library to be available on the local system.| +|"NetFx40_TimeSpanLegacyFormatMode"| formatting behavior for the .NET Framework 3.5 is enabled in this application domain. See [<TimeSpan_LegacyFormatMode> Element](/dotnet/framework/configure-apps/file-schema/runtime/timespan-legacyformatmode-element) and the "Restoring Legacy TimeSpan Formatting" section of the topic.| +|"UseRandomizedStringHashAlgorithm"|The runtime calculates hash codes for strings on a per application domain basis instead of using a single hashing algorithm that produces a consistent hash code across application domains. See [<UseRandomizedStringHashAlgorithm> Element](/dotnet/framework/configure-apps/file-schema/runtime/userandomizedstringhashalgorithm-element).| + ]]> @@ -1309,22 +1309,22 @@ System.Void - + An array that contains the XML configuration information to be used for the application domain. Provides XML configuration information for the application domain, replacing the application's XML configuration information. - method provides a way to replace the configuration information of an application that creates a new application domain. The configuration file information in `value` replaces the configuration file information for the application. For example, when the Example.exe application creates a new application domain, it can replace the configuration information originally obtained from the Example.exe.config file. - + method provides a way to replace the configuration information of an application that creates a new application domain. The configuration file information in `value` replaces the configuration file information for the application. For example, when the Example.exe application creates a new application domain, it can replace the configuration information originally obtained from the Example.exe.config file. + > [!IMPORTANT] -> Some consumers of configuration file information do not use the information stored by the method. The runtime does not enforce this. To ensure that all configuration file information is replaced in a new application domain, use the property to specify a configuration file. The method does affect assembly binding. - - The XML in `value` is the same as the XML in a normal configuration file, except that it is stored as a array. - +> Some consumers of configuration file information do not use the information stored by the method. The runtime does not enforce this. To ensure that all configuration file information is replaced in a new application domain, use the property to specify a configuration file. The method does affect assembly binding. + + The XML in `value` is the same as the XML in a normal configuration file, except that it is stored as a array. + ]]> Runtime Settings Schema @@ -1368,34 +1368,34 @@ A pointer to the function that overrides . Provides the common language runtime with an alternate implementation of a string comparison function. - method: - -- `IsNLSDefinedString` - -- `CompareStringEx` - -- `LCMapStringEx` - -- `FindNLSStringEx` - -- `CompareStringOrdinal` - -- `GetNLSVersion` - - For information about these functions, see [National Language Support Functions](https://go.microsoft.com/fwlink/?LinkId=228134). - + method: + +- `IsNLSDefinedString` + +- `CompareStringEx` + +- `LCMapStringEx` + +- `FindNLSStringEx` + +- `CompareStringOrdinal` + +- `GetNLSVersion` + + For information about these functions, see [National Language Support Functions](https://go.microsoft.com/fwlink/?LinkId=228134). + ]]> is . - is not 1 or greater. - - -or- - + is not 1 or greater. + + -or- + is . @@ -1435,18 +1435,18 @@ Gets or sets the names of the directories containing assemblies to be shadow copied. A list of directory names separated by semicolons. - and properties. The property restricts the shadow copy to the assemblies in the directories specified by . - - If you don't assign a string to the property, or if you set this property to `null`, all assemblies in the directories specified by the and properties are shadow copied. - + and properties. The property restricts the shadow copy to the assemblies in the directories specified by . + + If you don't assign a string to the property, or if you set this property to `null`, all assemblies in the directories specified by the and properties are shadow copied. + > [!IMPORTANT] -> Directory paths must not contain semicolons, because the semicolon is the delimiter character. There is no escape character for semicolons. - - When shadow copying is in effect, assembly files are copied to another location before the assemblies are loaded. The original assembly file is not locked, so it can be updated. For more information on shadow copying, see [Shadow Copying Assemblies](/dotnet/framework/app-domains/shadow-copy-assemblies). - +> Directory paths must not contain semicolons, because the semicolon is the delimiter character. There is no escape character for semicolons. + + When shadow copying is in effect, assembly files are copied to another location before the assemblies are loaded. The original assembly file is not locked, so it can be updated. For more information on shadow copying, see [Shadow Copying Assemblies](/dotnet/framework/app-domains/shadow-copy-assemblies). + ]]> @@ -1484,11 +1484,11 @@ Gets or sets a string that indicates whether shadow copying is turned on or off. The string value "true" to indicate that shadow copying is turned on; or "false" to indicate that shadow copying is turned off. - @@ -1533,13 +1533,13 @@ Gets (or, in .NET Framework, sets) a string that specifies the target framework in a format that can be parsed by the constructor. The target framework of the executable that started the process. - property is inferred from the attribute. In Visual Studio 2010 and later, this attribute is added to the assembly automatically based on the setting of the project's **Target Framework** property. - + property is inferred from the attribute. In Visual Studio 2010 and later, this attribute is added to the assembly automatically based on the setting of the project's **Target Framework** property. + ]]> diff --git a/xml/System/ArgumentException.xml b/xml/System/ArgumentException.xml index 97559f0e493..af76c88eeb7 100644 --- a/xml/System/ArgumentException.xml +++ b/xml/System/ArgumentException.xml @@ -78,36 +78,36 @@ The exception that is thrown when one of the arguments provided to a method is not valid. - is thrown when a method is invoked and at least one of the passed arguments does not meet the parameter specification of the called method. The property identifies the invalid argument. - - Most commonly, an is thrown by the common language runtime or another class library and indicates developer error. If you throw an from your code, you should ensure that the exception's property includes a meaningful error message that describes the invalid argument and the expected range of values for the argument. - - The primary derived classes of are and . These derived classes should be used instead of , except in situations where neither of the derived classes is acceptable. For example, exceptions should be thrown by: - -- whenever `null` is passed to a method that does not accept it as a valid argument. - -- when the value of an argument is outside the range of acceptable values; for example, when the value "46" is passed as the month argument during the creation of a . - -If the method call does not have any argument or if the failure does not involve the arguments themselves, then should be used. - - uses the HRESULT COR_E_ARGUMENT, which has the value 0x80070057. - -For a list of initial property values for an instance of , see the constructors. - + is thrown when a method is invoked and at least one of the passed arguments does not meet the parameter specification of the called method. The property identifies the invalid argument. + + Most commonly, an is thrown by the common language runtime or another class library and indicates developer error. If you throw an from your code, you should ensure that the exception's property includes a meaningful error message that describes the invalid argument and the expected range of values for the argument. + + The primary derived classes of are and . These derived classes should be used instead of , except in situations where neither of the derived classes is acceptable. For example, exceptions should be thrown by: + +- whenever `null` is passed to a method that does not accept it as a valid argument. + +- when the value of an argument is outside the range of acceptable values; for example, when the value "46" is passed as the month argument during the creation of a . + +If the method call does not have any argument or if the failure does not involve the arguments themselves, then should be used. + + uses the HRESULT COR_E_ARGUMENT, which has the value 0x80070057. + +For a list of initial property values for an instance of , see the constructors. + In F#, you can use the [invalidArg](/dotnet/fsharp/language-reference/exception-handling/the-invalidarg-function) function to generate and raise an ArgumentException. - + ## Examples -The following example demonstrates how to throw and catch an . It uses the [ArgumentException.GetType().Name](xref:System.Type.Name%2A) property to display the name of the exception object, and also uses the property to display the text of the exception message. - +The following example demonstrates how to throw and catch an . It uses the [ArgumentException.GetType().Name](xref:System.Type.Name%2A) property to display the name of the exception object, and also uses the property to display the text of the exception message. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/ArgumentException/cpp/argumentexception2.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System/ArgumentException/Overview/argumentexception2.cs" interactive="try-dotnet" id="Snippet3"::: :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR/ArgumentException/FS/argumentexception2.fs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ArgumentException/vb/program2.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ArgumentException/vb/program2.vb" id="Snippet3"::: + ]]> @@ -165,18 +165,18 @@ The following example demonstrates how to throw and catch an Initializes a new instance of the class. - property of the new instance to a system-supplied message that describes the error, such as "An invalid argument was specified." This message takes into account the current system culture. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||A null reference (`Nothing` in Visual Basic).| -||The localized error message string.| - + property of the new instance to a system-supplied message that describes the error, such as "An invalid argument was specified." This message takes into account the current system culture. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||A null reference (`Nothing` in Visual Basic).| +||The localized error message string.| + ]]> @@ -224,18 +224,18 @@ The following example demonstrates how to throw and catch an The error message that explains the reason for the exception. Initializes a new instance of the class with a specified error message. - property of the new instance to a system-supplied message that describes the error, such as "An invalid argument was specified." This message takes into account the current system culture. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||A null reference (`Nothing` in Visual Basic).| -||The error message string.| - + property of the new instance to a system-supplied message that describes the error, such as "An invalid argument was specified." This message takes into account the current system culture. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||A null reference (`Nothing` in Visual Basic).| +||The error message string.| + ]]> @@ -290,19 +290,19 @@ The following example demonstrates how to throw and catch an - - + + The object that holds the serialized object data. The contextual information about the source or destination. Initializes a new instance of the class with serialized data. - XML and SOAP Serialization @@ -353,20 +353,20 @@ The following example demonstrates how to throw and catch an The exception that is the cause of the current exception. If the parameter is not a null reference, the current exception is raised in a block that handles the inner exception. Initializes a new instance of the class with a specified error message and a reference to the inner exception that is the cause of this exception. - property of the new instance using the value of the `message` parameter. The content of the `message` parameter is intended to be understood by humans. The caller of this constructor is required to ensure that this string has been localized for the current system culture. - - An exception that is thrown as a direct result of a previous exception should include a reference to the previous exception in the property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||The inner exception reference.| -||The localized error message string.| - + property of the new instance using the value of the `message` parameter. The content of the `message` parameter is intended to be understood by humans. The caller of this constructor is required to ensure that this string has been localized for the current system culture. + + An exception that is thrown as a direct result of a previous exception should include a reference to the previous exception in the property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||The inner exception reference.| +||The localized error message string.| + ]]> @@ -418,28 +418,28 @@ The following example demonstrates how to throw and catch an The name of the parameter that caused the current exception. Initializes a new instance of the class with a specified error message and the name of the parameter that causes this exception. - property of the new instance using the value of the `message` parameter. The content of the `message` parameter is intended to be understood by humans. The caller of this constructor is required to ensure that this string has been localized for the current system culture. - - This constructor initializes the property of the new instance using `paramName`. The content of `paramName` is intended to be understood by humans. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||The error message string.| -||The parameter name string.| - - - -## Examples - The following code example demonstrates how to call the constructor. This code example is part of a larger example provided for the class. - + property of the new instance using the value of the `message` parameter. The content of the `message` parameter is intended to be understood by humans. The caller of this constructor is required to ensure that this string has been localized for the current system culture. + + This constructor initializes the property of the new instance using `paramName`. The content of `paramName` is intended to be understood by humans. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||The error message string.| +||The parameter name string.| + + + +## Examples + The following code example demonstrates how to call the constructor. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/ArgumentException/cpp/ArgumentException.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System/ArgumentException/Overview/argumentexception.cs" id="Snippet2"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR/ArgumentException/FS/argumentexception.fs" id="Snippet2"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR/ArgumentException/FS/argumentexception.fs" id="Snippet2"::: ]]> @@ -492,23 +492,23 @@ The following example demonstrates how to throw and catch an The exception that is the cause of the current exception. If the parameter is not a null reference, the current exception is raised in a block that handles the inner exception. Initializes a new instance of the class with a specified error message, the parameter name, and a reference to the inner exception that is the cause of this exception. - property of the new instance using the value of the `message` parameter. The content of the `message` parameter is intended to be understood by humans. The caller of this constructor is required to ensure that this string has been localized for the current system culture. - - This constructor initializes the property of the new instance using `paramName`. The content of `paramName` is intended to be understood by humans. - - An exception that is thrown as a direct result of a previous exception should include a reference to the previous exception in the property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||The inner exception reference.| -||The localized error message string.| -||The parameter name string.| - + property of the new instance using the value of the `message` parameter. The content of the `message` parameter is intended to be understood by humans. The caller of this constructor is required to ensure that this string has been localized for the current system culture. + + This constructor initializes the property of the new instance using `paramName`. The content of `paramName` is intended to be understood by humans. + + An exception that is thrown as a direct result of a previous exception should include a reference to the previous exception in the property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||The inner exception reference.| +||The localized error message string.| +||The parameter name string.| + ]]> @@ -571,21 +571,21 @@ The following example demonstrates how to throw and catch an System.Void - - + + The object that holds the serialized object data. The contextual information about the source or destination. Sets the object with the parameter name and additional exception information. - 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 . - + 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 . + ]]> The object is a null reference ( in Visual Basic). @@ -643,27 +643,27 @@ The following example demonstrates how to throw and catch an Gets the error message and the parameter name, or only the error message if no parameter name is set. - A text string describing the details of the exception. The value of this property takes one of two forms: - - Condition - - Value - - The is a null reference ( in Visual Basic) or of zero length. - - The string passed to the constructor. - - The is not null reference ( in Visual Basic) and it has a length greater than zero. - - The string appended with the name of the invalid parameter. - + A text string describing the details of the exception. The value of this property takes one of two forms: + + Condition + + Value + + The is a null reference ( in Visual Basic) or of zero length. + + The string passed to the constructor. + + The is not null reference ( in Visual Basic) and it has a length greater than zero. + + The string appended with the name of the invalid parameter. + - . The error message should be localized. - + . The error message should be localized. + ]]> @@ -711,15 +711,15 @@ The following example demonstrates how to throw and catch an Gets the name of the parameter that causes this exception. The parameter name. - should carry the name of the parameter that causes this exception. - - This property is read-only, and returns the same value as was passed into the constructor. Overriding methods should be used solely to customize the format of the parameter name. - - The parameter name should not be translated for localization purposes. - + should carry the name of the parameter that causes this exception. + + This property is read-only, and returns the same value as was passed into the constructor. Overriding methods should be used solely to customize the format of the parameter name. + + The parameter name should not be translated for localization purposes. + ]]> diff --git a/xml/System/ArgumentNullException.xml b/xml/System/ArgumentNullException.xml index 138579917a4..a9e81f9885f 100644 --- a/xml/System/ArgumentNullException.xml +++ b/xml/System/ArgumentNullException.xml @@ -66,23 +66,23 @@ The exception that is thrown when a null reference ( in Visual Basic) is passed to a method that does not accept it as a valid argument. - exception is thrown when a method is invoked and at least one of the passed arguments is `null` but should never be `null`. - - An exception is thrown at run time in the following two major circumstances, both of which reflect developer error: - -- An uninstantiated object is passed to a method. To prevent the error, instantiate the object. - -- An object returned from a method call is then passed as an argument to a second method, but the value of the original returned object is `null`. To prevent the error, check for a return value that is `null` and call the second method only if the return value is not `null`. - - behaves identically to . It is provided so that application code can differentiate between exceptions caused by `null` arguments and exceptions caused by arguments that are not null. For errors caused by arguments that are not null, see . - - uses the HRESULT E_POINTER, which has the value 0x80004003. - - For a list of initial property values for an instance of , see the constructors. - + exception is thrown when a method is invoked and at least one of the passed arguments is `null` but should never be `null`. + + An exception is thrown at run time in the following two major circumstances, both of which reflect developer error: + +- An uninstantiated object is passed to a method. To prevent the error, instantiate the object. + +- An object returned from a method call is then passed as an argument to a second method, but the value of the original returned object is `null`. To prevent the error, check for a return value that is `null` and call the second method only if the return value is not `null`. + + behaves identically to . It is provided so that application code can differentiate between exceptions caused by `null` arguments and exceptions caused by arguments that are not null. For errors caused by arguments that are not null, see . + + uses the HRESULT E_POINTER, which has the value 0x80004003. + + For a list of initial property values for an instance of , see the constructors. + ]]> @@ -140,18 +140,18 @@ Initializes a new instance of the class. - property of the new instance to a system-supplied message that describes the error, such as "Value cannot be null." This message takes into account the current system culture. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||A null reference (`Nothing` in Visual Basic).| -||A localized error message string, such as "Value cannot be null." for the English language.| - + property of the new instance to a system-supplied message that describes the error, such as "Value cannot be null." This message takes into account the current system culture. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||A null reference (`Nothing` in Visual Basic).| +||A localized error message string, such as "Value cannot be null." for the English language.| + ]]> @@ -199,21 +199,21 @@ The name of the parameter that caused the exception. Initializes a new instance of the class with the name of the parameter that causes this exception. - property of the new instance to a system-supplied message that describes the error and includes the parameter name. This message takes into account the current system culture. - - This constructor initializes the property of the new instance using the `paramName` parameter. The content of `paramName` is intended to be understood by humans. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||A null reference (`Nothing` in Visual Basic).| -||A localized error message string that identifies the null argument. For example, if the `paramName` argument is "arg1", the English language message string is:

On .NET 5+ and .NET Core: `Value cannot be null. (Parameter name: 'arg1')`

On .NET Framework: `Value cannot be null.\r\nParameter name: arg1`| -||The parameter name string.| - + property of the new instance to a system-supplied message that describes the error and includes the parameter name. This message takes into account the current system culture. + + This constructor initializes the property of the new instance using the `paramName` parameter. The content of `paramName` is intended to be understood by humans. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||A null reference (`Nothing` in Visual Basic).| +||A localized error message string that identifies the null argument. For example, if the `paramName` argument is "arg1", the English language message string is:

On .NET 5+ and .NET Core: `Value cannot be null. (Parameter name: 'arg1')`

On .NET Framework: `Value cannot be null.\r\nParameter name: arg1`| +||The parameter name string.| + ]]>
@@ -268,19 +268,19 @@
- - + + The object that holds the serialized object data. An object that describes the source or destination of the serialized data. Initializes a new instance of the class with serialized data. - XML and SOAP Serialization @@ -377,21 +377,21 @@ A message that describes the error. Initializes an instance of the class with a specified error message and the name of the parameter that causes this exception. - property of the new instance using the value of the `message` parameter. The content of the `message` parameter is intended to be understood by humans. The caller of this constructor is required to ensure that this string has been localized for the current system culture. - - This constructor initializes the property of the new instance using the `paramName` parameter. The content of `paramName` is intended to be understood by humans. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||A null reference (`Nothing` in Visual Basic).| -||The error message string.| -||The parameter name string.| - + property of the new instance using the value of the `message` parameter. The content of the `message` parameter is intended to be understood by humans. The caller of this constructor is required to ensure that this string has been localized for the current system culture. + + This constructor initializes the property of the new instance using the `paramName` parameter. The content of `paramName` is intended to be understood by humans. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||A null reference (`Nothing` in Visual Basic).| +||The error message string.| +||The parameter name string.| + ]]> diff --git a/xml/System/ArgumentOutOfRangeException.xml b/xml/System/ArgumentOutOfRangeException.xml index d4dcc097d21..7f1bec628f5 100644 --- a/xml/System/ArgumentOutOfRangeException.xml +++ b/xml/System/ArgumentOutOfRangeException.xml @@ -442,8 +442,8 @@ The following example defines a class to contain information about an invited gu
- - + + The object that holds the serialized object data. @@ -779,8 +779,8 @@ The following example defines a class to contain information about an invited gu System.Void - - + + The object that holds the serialized object data. diff --git a/xml/System/ArithmeticException.xml b/xml/System/ArithmeticException.xml index b5dc1ec615a..2e822ff0a32 100644 --- a/xml/System/ArithmeticException.xml +++ b/xml/System/ArithmeticException.xml @@ -72,23 +72,23 @@ The exception that is thrown for errors in an arithmetic, casting, or conversion operation. - is the base class for the following exceptions: - -- , which is thrown in integer division when the divisor is 0. For example, attempting to divide 10 by 0 throws a exception. - -- , which is thrown when an operation is performed on or returns , , , , , , and the programming language used does not support those values. - -- , which is thrown when the result of an operation is outside the bounds of the target data type. That is, it is less than a number's `MinValue` property or greater than its `MaxValue` property. For example, attempting to assign 200 + 200 to a value throws an exception, since 400 greater than 256, the upper bound of the data type. - - Your code should not handle or throw this exception. Instead, you should either handle or throw one of its derived classes, since it more precisely indicates the exact nature of the error. - - For a list of initial property values for an instance of , see the constructors. - - uses the HRESULT COR_E_ARITHMETIC, which has the value 0x80070216. - + is the base class for the following exceptions: + +- , which is thrown in integer division when the divisor is 0. For example, attempting to divide 10 by 0 throws a exception. + +- , which is thrown when an operation is performed on or returns , , , , , , and the programming language used does not support those values. + +- , which is thrown when the result of an operation is outside the bounds of the target data type. That is, it is less than a number's `MinValue` property or greater than its `MaxValue` property. For example, attempting to assign 200 + 200 to a value throws an exception, since 400 greater than 256, the upper bound of the data type. + + Your code should not handle or throw this exception. Instead, you should either handle or throw one of its derived classes, since it more precisely indicates the exact nature of the error. + + For a list of initial property values for an instance of , see the constructors. + + uses the HRESULT COR_E_ARITHMETIC, which has the value 0x80070216. + ]]> @@ -146,18 +146,18 @@ Initializes a new instance of the class. - property of the new instance to a system-supplied message that describes the error, such as "The arithmetic operation is not allowed." This message takes into account the current system culture. - - The following table shows initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||`null`.| -||The localized error message string.| - + property of the new instance to a system-supplied message that describes the error, such as "The arithmetic operation is not allowed." This message takes into account the current system culture. + + The following table shows initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||`null`.| +||The localized error message string.| + ]]> @@ -205,18 +205,18 @@ A that describes the error. Initializes a new instance of the class with a specified error message. - . - -|Property|Value| -|--------------|-----------| -||The null reference (`Nothing` in Visual Basic).| -||The error message string.| - + . + +|Property|Value| +|--------------|-----------| +||The null reference (`Nothing` in Visual Basic).| +||The error message string.| + ]]> @@ -271,19 +271,19 @@
- - + + The object that holds the serialized object data. The contextual information about the source or destination. Initializes a new instance of the class with serialized data. - XML and SOAP Serialization @@ -334,18 +334,18 @@ The exception that is the cause of the current exception. If the parameter is not a null reference, the current exception is raised in a block that handles the inner exception. Initializes a new instance of the class with a specified error message and a reference to the inner exception that is the cause of this exception. - property. The property returns the same value that is passed into the constructor, or a null reference (`Nothing` in Visual Basic) if the property does not supply the inner exception value to the constructor. - - The following table shows initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||The inner exception reference.| -||The error message string.| - + property. The property returns the same value that is passed into the constructor, or a null reference (`Nothing` in Visual Basic) if the property does not supply the inner exception value to the constructor. + + The following table shows initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||The inner exception reference.| +||The error message string.| + ]]> diff --git a/xml/System/Array.xml b/xml/System/Array.xml index 66fdf518671..0ce69947ecd 100644 --- a/xml/System/Array.xml +++ b/xml/System/Array.xml @@ -201,7 +201,7 @@ - + The type of the elements of the array. @@ -1595,8 +1595,8 @@ - - + + The type of the elements of the source array. @@ -1827,9 +1827,9 @@ System.Void - - - + + + The that contains the data to copy. @@ -2077,11 +2077,11 @@ System.Void - - - - - + + + + + The that contains the data to copy. @@ -2324,8 +2324,8 @@ System.Void - - + + The one-dimensional array that is the destination of the elements copied from the current array. @@ -2614,8 +2614,8 @@ System.Array - - + + [System.ParamArray] @@ -2715,9 +2715,9 @@ System.Array - - - + + + The of the to create. @@ -2927,10 +2927,10 @@ System.Array - - - - + + + + The of the to create. @@ -4334,8 +4334,8 @@ - - + + The type of the elements of the array. @@ -4358,7 +4358,7 @@ :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.array.foreach/cpp/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System/Array/ForEachT/source.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.array.foreach/fs/source.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.array.foreach/vb/source.vb" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.array.foreach/vb/source.vb" id="Snippet1"::: ]]> @@ -4577,7 +4577,7 @@ System.Int64 - + A zero-based dimension of the whose length needs to be determined. @@ -4999,7 +4999,7 @@ System.Object - + A 64-bit integer that represents the position of the element to get. @@ -5065,7 +5065,7 @@ System.Object - + [System.ParamArray] @@ -5145,8 +5145,8 @@ System.Object - - + + A 32-bit integer that represents the first-dimension index of the element to get. @@ -5216,8 +5216,8 @@ System.Object - - + + A 64-bit integer that represents the first-dimension index of the element to get. @@ -5287,9 +5287,9 @@ System.Object - - - + + + A 32-bit integer that represents the first-dimension index of the element to get. @@ -5361,9 +5361,9 @@ System.Object - - - + + + A 64-bit integer that represents the first-dimension index of the element to get. @@ -7772,8 +7772,8 @@ int[,,] TDArray = new int[1,1,1]; System.Void - - + + The new value for the specified element. @@ -7848,7 +7848,7 @@ int[,,] TDArray = new int[1,1,1]; System.Void - + [System.Runtime.CompilerServices.Nullable(2)] @@ -7856,7 +7856,7 @@ int[,,] TDArray = new int[1,1,1]; - + [System.ParamArray] @@ -7945,9 +7945,9 @@ int[,,] TDArray = new int[1,1,1]; System.Void - - - + + + The new value for the specified element. @@ -8026,9 +8026,9 @@ int[,,] TDArray = new int[1,1,1]; System.Void - - - + + + The new value for the specified element. @@ -8107,10 +8107,10 @@ int[,,] TDArray = new int[1,1,1]; System.Void - - - - + + + + The new value for the specified element. @@ -8190,10 +8190,10 @@ int[,,] TDArray = new int[1,1,1]; System.Void - - - - + + + + The new value for the specified element. diff --git a/xml/System/ArrayTypeMismatchException.xml b/xml/System/ArrayTypeMismatchException.xml index 0c4103c3dfe..60e6eb35815 100644 --- a/xml/System/ArrayTypeMismatchException.xml +++ b/xml/System/ArrayTypeMismatchException.xml @@ -72,33 +72,33 @@ The exception that is thrown when an attempt is made to store an element of the wrong type within an array. - is thrown when the system cannot convert the element to the type declared for the array. For example, an element of type cannot be stored in an array because conversion between these types is not supported. It is generally unnecessary for applications to throw this exception. - - The following Microsoft intermediate language (MSIL) instructions throw : - -- `ldelem.` - -- `ldelema` - -- `stelem.` - - uses the HRESULT COR_E_ARRAYTYPEMISMATCH, which has the value 0x80131503. - - For a list of initial property values for an instance of , see the constructors. - - - -## Examples - The following code example demonstrates scenarios where is thrown. - + is thrown when the system cannot convert the element to the type declared for the array. For example, an element of type cannot be stored in an array because conversion between these types is not supported. It is generally unnecessary for applications to throw this exception. + + The following Microsoft intermediate language (MSIL) instructions throw : + +- `ldelem.` + +- `ldelema` + +- `stelem.` + + uses the HRESULT COR_E_ARRAYTYPEMISMATCH, which has the value 0x80131503. + + For a list of initial property values for an instance of , see the constructors. + + + +## Examples + The following code example demonstrates scenarios where is thrown. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.ArrayTypeMismatch/CPP/class1.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System/ArrayTypeMismatchException/Overview/class1.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.ArrayTypeMismatch/FS/class1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.ArrayTypeMismatch/VB/class1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.ArrayTypeMismatch/VB/class1.vb" id="Snippet1"::: + ]]> @@ -156,28 +156,28 @@ Initializes a new instance of the class. - property of the new instance to a system-supplied message that describes the error, such as "Source array type cannot be assigned to destination array type." This message takes into account the current system culture. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||A null reference (`Nothing` in Visual Basic).| -||The localized error message string.| - - - -## Examples - The following example demonstrates the ArrayTypeMismatchException() constructor of the class. It contains a function which takes two arrays as arguments and checks whether the two arrays are of the same type. If the arrays are of different types, a new is thrown and then caught in the calling method. - + property of the new instance to a system-supplied message that describes the error, such as "Source array type cannot be assigned to destination array type." This message takes into account the current system culture. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||A null reference (`Nothing` in Visual Basic).| +||The localized error message string.| + + + +## Examples + The following example demonstrates the ArrayTypeMismatchException() constructor of the class. It contains a function which takes two arrays as arguments and checks whether the two arrays are of the same type. If the arrays are of different types, a new is thrown and then caught in the calling method. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/ArrayTypeMisMatch_Constructor1/CPP/arraytypemismatch_constructor1.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System/ArrayTypeMismatchException/.ctor/arraytypemismatch_constructor1.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR/ArrayTypeMisMatch_Constructor1/FS/arraytypemismatch_constructor1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ArrayTypeMisMatch_Constructor1/VB/arraytypemismatch_constructor1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ArrayTypeMisMatch_Constructor1/VB/arraytypemismatch_constructor1.vb" id="Snippet1"::: + ]]> @@ -225,28 +225,28 @@ A that describes the error. Initializes a new instance of the class with a specified error message. - . - -|Property|Value| -|--------------|-----------| -||A null reference (`Nothing` in Visual Basic).| -||The error message string.| - - - -## Examples - The following example demonstrates the ArrayTypeMismatchException(String) constructor of the class. It contains a function which takes two arrays as arguments and checks whether the two arrays are of the same type. If the arrays are of different types, a new is thrown and then caught in the calling method. - + . + +|Property|Value| +|--------------|-----------| +||A null reference (`Nothing` in Visual Basic).| +||The error message string.| + + + +## Examples + The following example demonstrates the ArrayTypeMismatchException(String) constructor of the class. It contains a function which takes two arrays as arguments and checks whether the two arrays are of the same type. If the arrays are of different types, a new is thrown and then caught in the calling method. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/ArrayTypeMisMatch_Constructor2/CPP/arraytypemismatch_constructor2.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System/ArrayTypeMismatchException/.ctor/arraytypemismatch_constructor2.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR/ArrayTypeMisMatch_Constructor2/FS/arraytypemismatch_constructor2.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ArrayTypeMisMatch_Constructor2/VB/arraytypemismatch_constructor2.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ArrayTypeMisMatch_Constructor2/VB/arraytypemismatch_constructor2.vb" id="Snippet1"::: + ]]> @@ -301,19 +301,19 @@ - - + + The object that holds the serialized object data. The contextual information about the source or destination. Initializes a new instance of the class with serialized data. - XML and SOAP Serialization @@ -364,28 +364,28 @@ The exception that is the cause of the current exception. If the parameter is not a null reference, the current exception is raised in a block that handles the inner exception. Initializes a new instance of the class with a specified error message and a reference to the inner exception that is the cause of this exception. - property. The property returns the same value that is passed into the constructor, or a null reference (`Nothing` in Visual Basic) if the property does not supply the inner exception value to the constructor. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||The inner exception reference.| -||The error message string.| - - - -## Examples - The following code example demonstrates the constructor of the class. It contains a function that takes two arrays as arguments and checks whether the two arrays are of the same type. If the arrays are of different types, a new is thrown and then caught in the calling method. - + property. The property returns the same value that is passed into the constructor, or a null reference (`Nothing` in Visual Basic) if the property does not supply the inner exception value to the constructor. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||The inner exception reference.| +||The error message string.| + + + +## Examples + The following code example demonstrates the constructor of the class. It contains a function that takes two arrays as arguments and checks whether the two arrays are of the same type. If the arrays are of different types, a new is thrown and then caught in the calling method. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/ArrayTypeMisMatch_Constructor3/CPP/arraytypemismatch_constructor3.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System/ArrayTypeMismatchException/.ctor/arraytypemismatch_constructor3.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR/ArrayTypeMisMatch_Constructor3/FS/arraytypemismatch_constructor3.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ArrayTypeMisMatch_Constructor3/VB/arraytypemismatch_constructor3.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ArrayTypeMisMatch_Constructor3/VB/arraytypemismatch_constructor3.vb" id="Snippet1"::: + ]]> diff --git a/xml/System/Attribute.xml b/xml/System/Attribute.xml index 6610c30558d..d3928417006 100644 --- a/xml/System/Attribute.xml +++ b/xml/System/Attribute.xml @@ -300,8 +300,8 @@ When implementing your own class derived from , you can o System.Attribute - - + + An object derived from the class that describes a reusable collection of modules. @@ -372,8 +372,8 @@ When implementing your own class derived from , you can o System.Attribute - - + + An object derived from the class that describes a constructor, event, field, method, or property member of a class. @@ -447,8 +447,8 @@ When implementing your own class derived from , you can o System.Attribute - - + + An object derived from the class that describes a portable executable file. @@ -511,8 +511,8 @@ When implementing your own class derived from , you can o System.Attribute - - + + An object derived from the class that describes a parameter of a member of a class. @@ -581,9 +581,9 @@ When implementing your own class derived from , you can o System.Attribute - - - + + + An object derived from the class that describes a reusable collection of modules. @@ -654,9 +654,9 @@ When implementing your own class derived from , you can o System.Attribute - - - + + + An object derived from the class that describes a constructor, event, field, method, or property member of a class. @@ -730,9 +730,9 @@ When implementing your own class derived from , you can o System.Attribute - - - + + + An object derived from the class that describes a portable executable file. @@ -796,9 +796,9 @@ When implementing your own class derived from , you can o System.Attribute - - - + + + An object derived from the class that describes a parameter of a member of a class. @@ -877,7 +877,7 @@ When implementing your own class derived from , you can o System.Attribute[] - + An object derived from the class that describes a reusable collection of modules. @@ -942,7 +942,7 @@ When implementing your own class derived from , you can o System.Attribute[] - + An object derived from the class that describes a constructor, event, field, method, or property member of a class. @@ -1011,7 +1011,7 @@ When implementing your own class derived from , you can o System.Attribute[] - + An object derived from the class that describes a portable executable file. @@ -1069,7 +1069,7 @@ When implementing your own class derived from , you can o System.Attribute[] - + An object derived from the class that describes a parameter of a member of a class. @@ -1133,8 +1133,8 @@ When implementing your own class derived from , you can o System.Attribute[] - - + + An object derived from the class that describes a reusable collection of modules. @@ -1200,8 +1200,8 @@ When implementing your own class derived from , you can o System.Attribute[] - - + + An object derived from the class that describes a reusable collection of modules. @@ -1269,8 +1269,8 @@ When implementing your own class derived from , you can o System.Attribute[] - - + + An object derived from the class that describes a constructor, event, field, method, or property member of a class. @@ -1340,8 +1340,8 @@ When implementing your own class derived from , you can o System.Attribute[] - - + + An object derived from the class that describes a portable executable file. @@ -1405,8 +1405,8 @@ When implementing your own class derived from , you can o System.Attribute[] - - + + An object derived from the class that describes a portable executable file. @@ -1473,8 +1473,8 @@ When implementing your own class derived from , you can o System.Attribute[] - - + + An object derived from the class that describes a parameter of a member of a class. @@ -1540,8 +1540,8 @@ When implementing your own class derived from , you can o System.Attribute[] - - + + An object derived from the class that describes a parameter of a member of a class. @@ -1608,9 +1608,9 @@ When implementing your own class derived from , you can o System.Attribute[] - - - + + + An object derived from the class that describes a reusable collection of modules. @@ -1684,8 +1684,8 @@ When implementing your own class derived from , you can o System.Attribute[] - - + + @@ -1759,9 +1759,9 @@ When implementing your own class derived from , you can o System.Attribute[] - - - + + + An object derived from the class that describes a portable executable file. @@ -1834,9 +1834,9 @@ When implementing your own class derived from , you can o System.Attribute[] - - - + + + An object derived from the class that describes a parameter of a member of a class. @@ -1909,10 +1909,10 @@ When implementing your own class derived from , you can o System.Attribute[] - - + + - + An object derived from the class that describes a constructor, event, field, method, or property member of a class. @@ -2119,8 +2119,8 @@ When implementing your own class derived from , you can o System.Boolean - - + + An object derived from the class that describes a reusable collection of modules. @@ -2189,8 +2189,8 @@ When implementing your own class derived from , you can o System.Boolean - - + + An object derived from the class that describes a constructor, event, field, method, type, or property member of a class. @@ -2262,8 +2262,8 @@ When implementing your own class derived from , you can o System.Boolean - - + + An object derived from the class that describes a portable executable file. @@ -2330,8 +2330,8 @@ When implementing your own class derived from , you can o System.Boolean - - + + An object derived from the class that describes a parameter of a member of a class. @@ -2398,9 +2398,9 @@ When implementing your own class derived from , you can o System.Boolean - - - + + + An object derived from the class that describes a reusable collection of modules. @@ -2470,9 +2470,9 @@ When implementing your own class derived from , you can o System.Boolean - - - + + + An object derived from the class that describes a constructor, event, field, method, type, or property member of a class. @@ -2550,9 +2550,9 @@ When implementing your own class derived from , you can o System.Boolean - - - + + + An object derived from the class that describes a portable executable file. @@ -2620,9 +2620,9 @@ When implementing your own class derived from , you can o System.Boolean - - - + + + An object derived from the class that describes a parameter of a member of a class. @@ -2694,7 +2694,7 @@ When implementing your own class derived from , you can o System.Boolean - + An to compare with this instance of . @@ -2752,11 +2752,11 @@ When implementing your own class derived from , you can o System.Void - - - - - + + + + + Reserved for future use. Must be IID_NULL. @@ -2803,9 +2803,9 @@ When implementing your own class derived from , you can o System.Void - - - + + + The type information to return. @@ -2850,7 +2850,7 @@ When implementing your own class derived from , you can o System.Void - + When this method returns, points to a location that receives the number of type information interfaces provided by the object. @@ -2893,14 +2893,14 @@ When implementing your own class derived from , you can o System.Void - - - - - - - - + + + + + + + + Identifies the member. diff --git a/xml/System/BadImageFormatException.xml b/xml/System/BadImageFormatException.xml index a29b3d05de5..04bfb1fa372 100644 --- a/xml/System/BadImageFormatException.xml +++ b/xml/System/BadImageFormatException.xml @@ -306,8 +306,8 @@ - - + + The that holds the serialized object data about the exception being thrown. @@ -663,8 +663,8 @@ System.Void - - + + The that holds the serialized object data about the exception being thrown. diff --git a/xml/System/Boolean.xml b/xml/System/Boolean.xml index b216550cadc..ddf96fc8557 100644 --- a/xml/System/Boolean.xml +++ b/xml/System/Boolean.xml @@ -161,47 +161,47 @@ A object to compare to this instance. Compares this instance to a specified object and returns an integer that indicates their relationship to one another. - A signed integer that indicates the relative values of this instance and . - - Return Value - - Condition - - Less than zero - - This instance is and is . - - Zero - - This instance and are equal (either both are or both are ). - - Greater than zero - - This instance is and is . - + A signed integer that indicates the relative values of this instance and . + + Return Value + + Condition + + Less than zero + + This instance is and is . + + Zero + + This instance and are equal (either both are or both are ). + + Greater than zero + + This instance is and is . + - interface and performs slightly better than the method because it does not have to convert the `value` parameter to an object. - - If `value` has fewer bits (is narrower) than the instance type, some programming languages perform an implicit widening conversion that transforms the value of the parameter into a value with more bits. - - For example, suppose the instance type is and the parameter type is . The Microsoft C# compiler generates instructions to represent the value of the parameter as an object, then generates a method to compare the instance and parameter representation. - - Consult your programming language's documentation to determine whether its compiler performs implicit widening conversions on numeric types. - -## Examples - -The following code example demonstrates generic and nongeneric versions of the method for several value and reference types. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/T.CompareTo/CPP/cat.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/Boolean/CompareTo/cat.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/Boolean/CompareTo/cat.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/T.CompareTo/VB/cat.vb" id="Snippet1"::: - + interface and performs slightly better than the method because it does not have to convert the `value` parameter to an object. + + If `value` has fewer bits (is narrower) than the instance type, some programming languages perform an implicit widening conversion that transforms the value of the parameter into a value with more bits. + + For example, suppose the instance type is and the parameter type is . The Microsoft C# compiler generates instructions to represent the value of the parameter as an object, then generates a method to compare the instance and parameter representation. + + Consult your programming language's documentation to determine whether its compiler performs implicit widening conversions on numeric types. + +## Examples + +The following code example demonstrates generic and nongeneric versions of the method for several value and reference types. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/T.CompareTo/CPP/cat.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System/Boolean/CompareTo/cat.cs" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/System/Boolean/CompareTo/cat.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/T.CompareTo/VB/cat.vb" id="Snippet1"::: + ]]> @@ -253,43 +253,43 @@ The following code example demonstrates generic and nongeneric versions of the < System.Int32 - + An object to compare to this instance, or . Compares this instance to a specified object and returns an integer that indicates their relationship to one another. - A signed integer that indicates the relative order of this instance and . - - Return Value - - Condition - - Less than zero - - This instance is and is . - - Zero - - This instance and are equal (either both are or both are ). - - Greater than zero - - This instance is and is . - - -or- - - is . - + A signed integer that indicates the relative order of this instance and . + + Return Value + + Condition + + Less than zero + + This instance is and is . + + Zero + + This instance and are equal (either both are or both are ). + + Greater than zero + + This instance is and is . + + -or- + + is . + - interface. - + interface. + ]]> @@ -360,12 +360,12 @@ The following code example demonstrates generic and nongeneric versions of the < if has the same value as this instance; otherwise, . - interface, and performs slightly better than because it does not have to convert the `obj` parameter to an object. - + interface, and performs slightly better than because it does not have to convert the `obj` parameter to an object. + ]]> @@ -433,12 +433,12 @@ This method implements the if is a and has the same value as this instance; otherwise, . - . - + . + ]]> @@ -492,14 +492,14 @@ This method overrides . Represents the Boolean value as a string. This field is read-only. - property defines the string representation of a `false` value in formatting and parsing operations. - + property defines the string representation of a `false` value in formatting and parsing operations. + ]]> @@ -549,12 +549,12 @@ The property defines the string representation Returns the hash code for this instance. A hash code for the current . - class implements `true` as the integer, one, and `false` as the integer, zero. However, a particular programming language might represent `true` and `false` with other values. - + class implements `true` as the integer, one, and `false` as the integer, zero. However, a particular programming language might represent `true` and `false` with other values. + ]]> @@ -696,21 +696,21 @@ The class implements `true` as the integer, one, and `fals if is equivalent to ; if is equivalent to . - or ; otherwise, an exception is thrown. The comparison is case-insensitive. - -## Examples - -The following code example illustrates the use of method. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Boolean/CPP/booleanmembers.cpp" id="Snippet2"::: - :::code language="csharp" source="~/snippets/csharp/System/Boolean/Parse/booleanmembers.cs" interactive="try-dotnet-method" id="Snippet2"::: - :::code language="fsharp" source="~/snippets/fsharp/System/Boolean/Parse/booleanmembers.fs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Boolean/VB/booleanmembers.vb" id="Snippet2"::: - + or ; otherwise, an exception is thrown. The comparison is case-insensitive. + +## Examples + +The following code example illustrates the use of method. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Boolean/CPP/booleanmembers.cpp" id="Snippet2"::: + :::code language="csharp" source="~/snippets/csharp/System/Boolean/Parse/booleanmembers.cs" interactive="try-dotnet-method" id="Snippet2"::: + :::code language="fsharp" source="~/snippets/fsharp/System/Boolean/Parse/booleanmembers.fs" id="Snippet2"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Boolean/VB/booleanmembers.vb" id="Snippet2"::: + ]]> @@ -757,20 +757,20 @@ The following code example illustrates the use of Compares the current instance with another object of the same type and returns an integer that indicates whether the current instance precedes, follows, or occurs in the same position in the sort order as the other object. A value that indicates the relative order of the objects being compared. - instance is cast to an interface. - -The return value has these meanings: - -| Value | Meaning | -|-------------------|-------------------------------------------------------------------------| -| Less than zero | This instance precedes `obj` in the sort order. | -| Zero | This instance occurs in the same position in the sort order as `obj`. | -| Greater than zero | This instance follows `obj` in the sort order. | - + instance is cast to an interface. + +The return value has these meanings: + +| Value | Meaning | +|-------------------|-------------------------------------------------------------------------| +| Less than zero | This instance precedes `obj` in the sort order. | +| Zero | This instance occurs in the same position in the sort order as `obj`. | +| Greater than zero | This instance follows `obj` in the sort order. | + ]]> @@ -805,12 +805,12 @@ The return value has these meanings: Returns the for this instance. The enumerated constant that is the of the class or value type that implements this interface. - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -863,12 +863,12 @@ This member is an explicit interface member implementation. It can be used only or . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -920,12 +920,12 @@ This member is an explicit interface member implementation. It can be used only For a description of this member, see . 1 if the value of this instance is ; otherwise, 0. - instance is cast to an interface. The recommended alternative is to call the method. - + instance is cast to an interface. The recommended alternative is to call the method. + ]]> @@ -1078,12 +1078,12 @@ This member is an explicit interface member implementation. It can be used only For a description of this member, see . 1 if this instance is ; otherwise, 0. - instance is cast to an interface. The recommended alternative is to call the method. - + instance is cast to an interface. The recommended alternative is to call the method. + ]]> @@ -1135,12 +1135,12 @@ This member is an explicit interface member implementation. It can be used only For a description of this member, see . 1 if this instance is ; otherwise, 0. - instance is cast to an interface. The recommended alternative is to call the method. - + instance is cast to an interface. The recommended alternative is to call the method. + ]]> @@ -1192,12 +1192,12 @@ This member is an explicit interface member implementation. It can be used only For a description of this member, see . 1 if this instance is ; otherwise, 0. - instance is cast to an interface. The recommended alternative is to call the method. - + instance is cast to an interface. The recommended alternative is to call the method. + ]]> @@ -1249,12 +1249,12 @@ This member is an explicit interface member implementation. It can be used only For a description of this member, see . 1 if this instance is ; otherwise, 0. - instance is cast to an interface. The recommended alternative is to call the method. - + instance is cast to an interface. The recommended alternative is to call the method. + ]]> @@ -1306,12 +1306,12 @@ This member is an explicit interface member implementation. It can be used only For a description of this member, see . 1 if this instance is ; otherwise, 0. - instance is cast to an interface. The recommended alternative is to call the method. - + instance is cast to an interface. The recommended alternative is to call the method. + ]]> @@ -1369,12 +1369,12 @@ This member is an explicit interface member implementation. It can be used only For a description of this member, see . 1 if this instance is ; otherwise, 0. - instance is cast to an interface. The recommended alternative is to call the method. - + instance is cast to an interface. The recommended alternative is to call the method. + ]]> @@ -1426,12 +1426,12 @@ This member is an explicit interface member implementation. It can be used only For a description of this member, see . 1 if this instance is ; otherwise, 0. - instance is cast to an interface. The recommended alternative is to call the method. - + instance is cast to an interface. The recommended alternative is to call the method. + ]]> @@ -1469,12 +1469,12 @@ This member is an explicit interface member implementation. It can be used only Converts the value of this instance to an equivalent string using the specified culture-specific formatting information. A string instance equivalent to the value of this instance. - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -1528,12 +1528,12 @@ This member is an explicit interface member implementation. It can be used only For a description of this member, see . An object of the specified type, with a value that is equivalent to the value of this object. - instance is cast to an interface. The recommended alternative is to call the method. - + instance is cast to an interface. The recommended alternative is to call the method. + ]]> @@ -1595,12 +1595,12 @@ This member is an explicit interface member implementation. It can be used only For a description of this member, see . 1 if this instance is ; otherwise, 0. - instance is cast to an interface. The recommended alternative is to call the method. - + instance is cast to an interface. The recommended alternative is to call the method. + ]]> @@ -1660,12 +1660,12 @@ This member is an explicit interface member implementation. It can be used only For a description of this member, see . 1 if this instance is ; otherwise, 0. - instance is cast to an interface. The recommended alternative is to call the method. - + instance is cast to an interface. The recommended alternative is to call the method. + ]]> @@ -1725,12 +1725,12 @@ This member is an explicit interface member implementation. It can be used only For a description of this member, see . 1 if this instance is ; otherwise, 0. - instance is cast to an interface. The recommended alternative is to call the method. - + instance is cast to an interface. The recommended alternative is to call the method. + ]]> @@ -1952,23 +1952,23 @@ This member is an explicit interface member implementation. It can be used only Converts the value of this instance to its equivalent string representation (either "True" or "False"). "True" (the value of the property) if the value of this instance is , or "False" (the value of the property) if the value of this instance is . - method is to be written to an XML file, its method should be called first to convert it to lowercase. - -## Examples - -The following example illustrates the method. - - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Boolean/CPP/booleanmembers.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System/Boolean/Parse/booleanmembers.cs" interactive="try-dotnet-method" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/Boolean/Parse/booleanmembers.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Boolean/VB/booleanmembers.vb" id="Snippet1"::: - + method is to be written to an XML file, its method should be called first to convert it to lowercase. + +## Examples + +The following example illustrates the method. + + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Boolean/CPP/booleanmembers.cpp" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/System/Boolean/Parse/booleanmembers.cs" interactive="try-dotnet-method" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/System/Boolean/Parse/booleanmembers.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Boolean/VB/booleanmembers.vb" id="Snippet1"::: + ]]> @@ -2018,7 +2018,7 @@ The following example illustrates the method. System.String - + [System.Runtime.CompilerServices.Nullable(2)] @@ -2033,14 +2033,14 @@ The following example illustrates the method. if the value of this instance is , or if the value of this instance is . - method, unlike most methods with a `provider` parameter, does not reflect culture-specific settings. - - This method returns the constants "True" or "False". Note that XML is case-sensitive, and that the XML specification recognizes "true" and "false" as the valid set of Boolean values. If the object returned by the method is to be written to an XML file, its method should be called first to convert it to lowercase. - + method, unlike most methods with a `provider` parameter, does not reflect culture-specific settings. + + This method returns the constants "True" or "False". Note that XML is case-sensitive, and that the XML specification recognizes "true" and "false" as the valid set of Boolean values. If the object returned by the method is to be written to an XML file, its method should be called first to convert it to lowercase. + ]]> @@ -2092,14 +2092,14 @@ The `provider` parameter is reserved. It does not participate in the execution o Represents the Boolean value as a string. This field is read-only. - property defines the string representation of a `true` value in formatting and parsing operations. - + property defines the string representation of a `true` value in formatting and parsing operations. + ]]> @@ -2250,22 +2250,22 @@ The property defines the string representation if was converted successfully; otherwise, . - method is like the method, except the method does not throw an exception if the conversion fails. - - The `value` parameter can be preceded or followed by white space. The comparison is ordinal and case-insensitive. - -## Examples - -The following example calls the method to parse an array of strings. Note that the parse operation succeeds only if the string to be parsed is "True" (the value of the field) or "False" (the value of the field) in a case-insensitive comparison. - - :::code language="csharp" source="~/snippets/csharp/System/Boolean/TryParse/tryparseex.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/Boolean/TryParse/tryparseex.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.boolean.tryparse/vb/tryparseex.vb" id="Snippet1"::: - + method is like the method, except the method does not throw an exception if the conversion fails. + + The `value` parameter can be preceded or followed by white space. The comparison is ordinal and case-insensitive. + +## Examples + +The following example calls the method to parse an array of strings. Note that the parse operation succeeds only if the string to be parsed is "True" (the value of the field) or "False" (the value of the field) in a case-insensitive comparison. + + :::code language="csharp" source="~/snippets/csharp/System/Boolean/TryParse/tryparseex.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/System/Boolean/TryParse/tryparseex.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.boolean.tryparse/vb/tryparseex.vb" id="Snippet1"::: + ]]> diff --git a/xml/System/Byte.xml b/xml/System/Byte.xml index 9e2e8657b03..ea12ae6c0f0 100644 --- a/xml/System/Byte.xml +++ b/xml/System/Byte.xml @@ -455,7 +455,7 @@ System.Int32 - + An object to compare, or . diff --git a/xml/System/Char.xml b/xml/System/Char.xml index a1f62eb9bc4..a76e69bd1e0 100644 --- a/xml/System/Char.xml +++ b/xml/System/Char.xml @@ -422,7 +422,7 @@ The following code example demonstrates some of the methods in System.Int32 - + An object to compare this instance to, or . @@ -1203,7 +1203,7 @@ The following code example demonstrates some of the methods in System.Globalization.UnicodeCategory - + The Unicode character to categorize. @@ -1268,8 +1268,8 @@ The following code example demonstrates some of the methods in System.Globalization.UnicodeCategory - - + + A . @@ -9023,8 +9023,8 @@ This member is an explicit interface member implementation. It can be used only System.Char - - + + The Unicode character to convert. @@ -9306,7 +9306,7 @@ This member is an explicit interface member implementation. It can be used only System.String - + [System.Runtime.CompilerServices.Nullable(2)] @@ -9462,8 +9462,8 @@ This member is an explicit interface member implementation. It can be used only System.Char - - + + The Unicode character to convert. diff --git a/xml/System/Console.xml b/xml/System/Console.xml index e306b6aa050..e7e0ace8b4a 100644 --- a/xml/System/Console.xml +++ b/xml/System/Console.xml @@ -5718,11 +5718,11 @@ This method can be used to reacquire the standard output stream after it has bee System.Void - - - - - + + + + + A composite format string. @@ -7240,11 +7240,11 @@ This method can be used to reacquire the standard output stream after it has bee System.Void - - - - - + + + + + A composite format string. diff --git a/xml/System/Convert.xml b/xml/System/Convert.xml index d81b89cdeeb..68e406eb7d5 100644 --- a/xml/System/Convert.xml +++ b/xml/System/Convert.xml @@ -255,8 +255,8 @@ - - + + An object that implements the interface. @@ -1083,7 +1083,7 @@ System.Boolean - + [System.Diagnostics.CodeAnalysis.NotNullWhen(true)] @@ -1291,12 +1291,12 @@ System.Int32 - - - - - - + + + + + + An input array of 8-bit unsigned integers. @@ -1505,8 +1505,8 @@ System.String - - + + An array of 8-bit unsigned integers. @@ -1734,10 +1734,10 @@ System.String - - - - + + + + An array of 8-bit unsigned integers. @@ -1956,7 +1956,7 @@ System.Boolean - + The Unicode character to convert. @@ -2005,7 +2005,7 @@ System.Boolean - + The date and time value to convert. @@ -3239,7 +3239,7 @@ System.Byte - + The date and time value to convert. @@ -4365,7 +4365,7 @@ System.Char - + The Boolean value to convert. @@ -4474,7 +4474,7 @@ System.Char - + The Unicode character to return. @@ -4522,7 +4522,7 @@ System.Char - + The date and time value to convert. @@ -4570,7 +4570,7 @@ System.Char - + The decimal number to convert. @@ -4630,7 +4630,7 @@ System.Char - + The double-precision floating-point number to convert. @@ -5014,7 +5014,7 @@ System.Char - + The single-precision floating-point number to convert. @@ -5524,7 +5524,7 @@ System.DateTime - + The Boolean value to convert. @@ -5573,7 +5573,7 @@ System.DateTime - + The 8-bit unsigned integer to convert. @@ -5622,7 +5622,7 @@ System.DateTime - + The Unicode character to convert. @@ -5671,7 +5671,7 @@ System.DateTime - + A date and time value. @@ -5719,7 +5719,7 @@ System.DateTime - + The number to convert. @@ -5767,7 +5767,7 @@ System.DateTime - + The double-precision floating-point value to convert. @@ -5816,7 +5816,7 @@ System.DateTime - + The 16-bit signed integer to convert. @@ -5865,7 +5865,7 @@ System.DateTime - + The 32-bit signed integer to convert. @@ -5914,7 +5914,7 @@ System.DateTime - + The 64-bit signed integer to convert. @@ -6046,7 +6046,7 @@ System.DateTime - + The 8-bit signed integer to convert. @@ -6095,7 +6095,7 @@ System.DateTime - + The single-precision floating-point value to convert. @@ -6225,7 +6225,7 @@ System.DateTime - + The 16-bit unsigned integer to convert. @@ -6280,7 +6280,7 @@ System.DateTime - + The 32-bit unsigned integer to convert. @@ -6335,7 +6335,7 @@ System.DateTime - + The 64-bit unsigned integer to convert. @@ -6675,7 +6675,7 @@ System.Decimal - + The Unicode character to convert. @@ -6736,7 +6736,7 @@ System.Decimal - + The date and time value to convert. @@ -7893,7 +7893,7 @@ System.Double - + The Unicode character to convert. @@ -7942,7 +7942,7 @@ System.Double - + The date and time value to convert. @@ -9404,7 +9404,7 @@ System.Int16 - + The date and time value to convert. @@ -10704,7 +10704,7 @@ System.Int32 - + The date and time value to convert. @@ -11994,7 +11994,7 @@ System.Int64 - + The date and time value to convert. @@ -13316,7 +13316,7 @@ System.SByte - + The date and time value to convert. @@ -14640,7 +14640,7 @@ System.Single - + The Unicode character to convert. @@ -14689,7 +14689,7 @@ System.Single - + The date and time value to convert. @@ -16566,7 +16566,7 @@ - + The string to return. @@ -18169,8 +18169,8 @@ - - + + The string to return. @@ -18708,7 +18708,7 @@ System.UInt16 - + The date and time value to convert. @@ -20104,7 +20104,7 @@ System.UInt32 - + The date and time value to convert. @@ -21498,7 +21498,7 @@ System.UInt64 - + The date and time value to convert. diff --git a/xml/System/DBNull.xml b/xml/System/DBNull.xml index 0d44a1e5e4b..d86fcbff77b 100644 --- a/xml/System/DBNull.xml +++ b/xml/System/DBNull.xml @@ -87,24 +87,24 @@ Represents a nonexistent value. This class cannot be inherited. - class represents a nonexistent value. In a database, for example, a column in a row of a table might not contain any data whatsoever. That is, the column is considered to not exist at all instead of merely not having a value. A object represents the nonexistent column. Additionally, COM interop uses the class to distinguish between a VT_NULL variant, which indicates a nonexistent value, and a VT_EMPTY variant, which indicates an unspecified value. - - The type is a singleton class, which means only one object exists. The member represents the sole object. can be used to explicitly assign a nonexistent value to a database field, although most ADO.NET data providers automatically assign values of when a field does not have a valid value. You can determine whether a value retrieved from a database field is a value by passing the value of that field to the `DBNull.Value.Equals` method. However, some languages and database objects supply methods that make it easier to determine whether the value of a database field is . These include the Visual Basic `IsDBNull` function, the method, the method, and the method. - - Do not confuse the notion of `null` in an object-oriented programming language with a object. In an object-oriented programming language, `null` means the absence of a reference to an object. represents an uninitialized variant or nonexistent database column. - - - -## Examples - The following example calls the `DBNull.Value.Equals` method to determine whether a database field in a contacts database has a valid value. If it does, the field value is appended to the string output in a label. - + class represents a nonexistent value. In a database, for example, a column in a row of a table might not contain any data whatsoever. That is, the column is considered to not exist at all instead of merely not having a value. A object represents the nonexistent column. Additionally, COM interop uses the class to distinguish between a VT_NULL variant, which indicates a nonexistent value, and a VT_EMPTY variant, which indicates an unspecified value. + + The type is a singleton class, which means only one object exists. The member represents the sole object. can be used to explicitly assign a nonexistent value to a database field, although most ADO.NET data providers automatically assign values of when a field does not have a valid value. You can determine whether a value retrieved from a database field is a value by passing the value of that field to the `DBNull.Value.Equals` method. However, some languages and database objects supply methods that make it easier to determine whether the value of a database field is . These include the Visual Basic `IsDBNull` function, the method, the method, and the method. + + Do not confuse the notion of `null` in an object-oriented programming language with a object. In an object-oriented programming language, `null` means the absence of a reference to an object. represents an uninitialized variant or nonexistent database column. + + + +## Examples + The following example calls the `DBNull.Value.Equals` method to determine whether a database field in a contacts database has a valid value. If it does, the field value is appended to the string output in a label. + :::code language="csharp" source="~/snippets/csharp/System/DBNull/Overview/DBNullExamples.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DBNull.Class/fs/DBNullExamples.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DBNull.Class/vb/DBNullExamples.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DBNull.Class/vb/DBNullExamples.vb" id="Snippet1"::: + ]]> @@ -167,8 +167,8 @@ System.Void - - + + A object containing information required to serialize the object. @@ -271,7 +271,7 @@ System.Boolean - + An object that implements the interface. (This parameter is not used; specify .) @@ -323,7 +323,7 @@ System.Byte - + An object that implements the interface. (This parameter is not used; specify .) @@ -375,7 +375,7 @@ System.Char - + An object that implements the interface. (This parameter is not used; specify .) @@ -427,7 +427,7 @@ System.DateTime - + An object that implements the interface. (This parameter is not used; specify .) @@ -479,7 +479,7 @@ System.Decimal - + An object that implements the interface. (This parameter is not used; specify .) @@ -531,7 +531,7 @@ System.Double - + An object that implements the interface. (This parameter is not used; specify .) @@ -583,7 +583,7 @@ System.Int16 - + An object that implements the interface. (This parameter is not used; specify .) @@ -635,7 +635,7 @@ System.Int32 - + An object that implements the interface. (This parameter is not used; specify .) @@ -687,7 +687,7 @@ System.Int64 - + An object that implements the interface. (This parameter is not used; specify .) @@ -745,7 +745,7 @@ System.SByte - + An object that implements the interface. (This parameter is not used; specify .) @@ -797,7 +797,7 @@ System.Single - + An object that implements the interface. (This parameter is not used; specify .) @@ -849,8 +849,8 @@ System.Object - - + + The type to convert the current object to. @@ -858,11 +858,11 @@ Converts the current object to the specified type. The boxed equivalent of the current object, if that conversion is supported; otherwise, an exception is thrown and no value is returned. - or , the return value is the current object itself. If the `type` parameter specifies , the return value is the string returned by the method. - + or , the return value is the current object itself. If the `type` parameter specifies , the return value is the string returned by the method. + ]]> This conversion is not supported for the type. @@ -919,7 +919,7 @@ System.UInt16 - + An object that implements the interface. (This parameter is not used; specify .) @@ -977,7 +977,7 @@ System.UInt32 - + An object that implements the interface. (This parameter is not used; specify .) @@ -1035,7 +1035,7 @@ System.UInt64 - + An object that implements the interface. (This parameter is not used; specify .) @@ -1158,10 +1158,10 @@ - The to be used to format the return value. - - -or- - + The to be used to format the return value. + + -or- + to obtain the format information from the current locale setting of the operating system. Returns an empty string using the specified . An empty string (). @@ -1211,24 +1211,24 @@ Represents the sole instance of the class. - is a singleton class, which means only this instance of this class can exist. - - If a database field has missing data, you can use the property to explicitly assign a object value to the field. However, most data providers do this automatically. - - To evaluate database fields to determine whether their values are , you can pass the field value to the `DBNull.Value.Equals` method. However, this method is rarely used because there are a number of other ways to evaluate a database field for missing data. These include the Visual Basic `IsDBNull` function, the method, the method, the method, and several other methods. - - - -## Examples - The following example calls the `DBNull.Value.Equals` method to determine whether a database field in a contacts database has a valid value. If it does, the field value is appended to the string output in a label. - + is a singleton class, which means only this instance of this class can exist. + + If a database field has missing data, you can use the property to explicitly assign a object value to the field. However, most data providers do this automatically. + + To evaluate database fields to determine whether their values are , you can pass the field value to the `DBNull.Value.Equals` method. However, this method is rarely used because there are a number of other ways to evaluate a database field for missing data. These include the Visual Basic `IsDBNull` function, the method, the method, the method, and several other methods. + + + +## Examples + The following example calls the `DBNull.Value.Equals` method to determine whether a database field in a contacts database has a valid value. If it does, the field value is appended to the string output in a label. + :::code language="csharp" source="~/snippets/csharp/System/DBNull/Overview/DBNullExamples.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DBNull.Class/fs/DBNullExamples.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DBNull.Class/vb/DBNullExamples.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DBNull.Class/vb/DBNullExamples.vb" id="Snippet1"::: + ]]> diff --git a/xml/System/DateTime.xml b/xml/System/DateTime.xml index e182219c619..95e5bb876c3 100644 --- a/xml/System/DateTime.xml +++ b/xml/System/DateTime.xml @@ -451,10 +451,10 @@ 9.0.0.0 - - - - + + + + The year (1 through the number of years in ). @@ -726,13 +726,13 @@ 9.0.0.0 - - - - - - - + + + + + + + The year (1 through the number of years in ). @@ -1032,14 +1032,14 @@ 9.0.0.0 - - - - - - - - + + + + + + + + The year (1 through the number of years in ). @@ -1227,15 +1227,15 @@ For applications in which portability of date and time data or a limited degree 9.0.0.0 - - - - - - - - - + + + + + + + + + The year (1 through the number of years in ). @@ -2500,7 +2500,7 @@ The value parameter is rounded to the nearest integer. System.Int32 - + A boxed object to compare, or . @@ -3449,7 +3449,7 @@ The value parameter is rounded to the nearest integer. System.DateTime - + An OLE Automation Date value. @@ -7884,8 +7884,8 @@ This member is an explicit interface member implementation. It can be used only System.Void - - + + The object to populate with data. diff --git a/xml/System/DateTimeOffset.xml b/xml/System/DateTimeOffset.xml index 5aac53e1b22..7b4867fd367 100644 --- a/xml/System/DateTimeOffset.xml +++ b/xml/System/DateTimeOffset.xml @@ -114,51 +114,51 @@ Represents a point in time, typically expressed as a date and time of day, relative to Coordinated Universal Time (UTC). - structure includes a value, together with an property that defines the difference between the current instance's date and time and Coordinated Universal Time (UTC). Because it exactly defines a date and time relative to UTC, the structure does not include a `Kind` member, as the structure does. It represents dates and times with values whose UTC ranges from 12:00:00 midnight, January 1, 0001 Anno Domini (Common Era), to 11:59:59 P.M., December 31, 9999 A.D. (C.E.). - -[!INCLUDE[japanese-era-note](~/includes/calendar-era.md)] - - The time component of a value is measured in 100-nanosecond units called ticks, and a particular date is the number of ticks since 12:00 midnight, January 1, 0001 A.D. (C.E.) in the calendar. A value is always expressed in the context of an explicit or default calendar. Ticks that are attributable to leap seconds are not included in the total number of ticks. - - Although a value includes an offset, it is not a fully time zone-aware data structure. While an offset from UTC is one characteristic of a time zone, it does not unambiguously identify a time zone. Not only do multiple time zones share the same offset from UTC, but the offset of a single time zone changes if it observes daylight saving time. This means that, as soon as a value is disassociated from its time zone, it can no longer be unambiguously linked back to its original time zone. - - Because is a structure, a object that has been declared but not otherwise initialized contains the default values for each of its member fields. This means that its property is set to and its property is set to . - - You can create a new value by calling any of the overloads of its constructor, which are similar to the overloaded constructors for the structure. You can also create a new value by assigning it a value. This is an implicit conversion; it does not require a casting operator (in C#) or call to a conversion method (in Visual Basic). You can also initialize a value from the string representation of a date and time by calling a number of static string parsing methods, which include , , , and . - - The members of the structure provide functionality in the following areas: - -- Date and time arithmetic. - - You can add or subtract either dates or time intervals from a particular value. Arithmetic operations with values, unlike those with values, adjust for differences in time offsets when returning a result. For example, the following code uses variables to subtract the current local time from the current UTC time. The code then uses variables to perform the same operation. The subtraction with values returns the local time zone's difference from UTC, while the subtraction with values returns . - - :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Overview/Type.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Type/fs/Type.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Type/vb/Type.vb" id="Snippet1"::: - -- Type conversion operations. - - You can convert values to values and vice versa. - -- Time manipulation and extraction operations. - - You can extract either the date or the time of a value. You can also retrieve the value of a particular component, such as its year or its month. - - > [!NOTE] - > If you are working with a ticks value that you want to convert to some other time interval, such as minutes or seconds, you should use the , , , , or constant to perform the conversion. For example, to add the number of seconds represented by a specified number of ticks to the component of a value, you can use the expression `dateValue.Second + nTicks/Timespan.TicksPerSecond`. - - -- Date and time conversion. - - You can convert any value to another value that represents the same point in time in another time zone. However, a time zone's adjustment rules are applied only in the case of the method, which converts a value to the date and time in the local system zone. - -- Date and time comparison. - - You can determine whether any particular value is earlier than, the same as, or later than another value. Before the comparison is performed, all values are converted to UTC. - + structure includes a value, together with an property that defines the difference between the current instance's date and time and Coordinated Universal Time (UTC). Because it exactly defines a date and time relative to UTC, the structure does not include a `Kind` member, as the structure does. It represents dates and times with values whose UTC ranges from 12:00:00 midnight, January 1, 0001 Anno Domini (Common Era), to 11:59:59 P.M., December 31, 9999 A.D. (C.E.). + +[!INCLUDE[japanese-era-note](~/includes/calendar-era.md)] + + The time component of a value is measured in 100-nanosecond units called ticks, and a particular date is the number of ticks since 12:00 midnight, January 1, 0001 A.D. (C.E.) in the calendar. A value is always expressed in the context of an explicit or default calendar. Ticks that are attributable to leap seconds are not included in the total number of ticks. + + Although a value includes an offset, it is not a fully time zone-aware data structure. While an offset from UTC is one characteristic of a time zone, it does not unambiguously identify a time zone. Not only do multiple time zones share the same offset from UTC, but the offset of a single time zone changes if it observes daylight saving time. This means that, as soon as a value is disassociated from its time zone, it can no longer be unambiguously linked back to its original time zone. + + Because is a structure, a object that has been declared but not otherwise initialized contains the default values for each of its member fields. This means that its property is set to and its property is set to . + + You can create a new value by calling any of the overloads of its constructor, which are similar to the overloaded constructors for the structure. You can also create a new value by assigning it a value. This is an implicit conversion; it does not require a casting operator (in C#) or call to a conversion method (in Visual Basic). You can also initialize a value from the string representation of a date and time by calling a number of static string parsing methods, which include , , , and . + + The members of the structure provide functionality in the following areas: + +- Date and time arithmetic. + + You can add or subtract either dates or time intervals from a particular value. Arithmetic operations with values, unlike those with values, adjust for differences in time offsets when returning a result. For example, the following code uses variables to subtract the current local time from the current UTC time. The code then uses variables to perform the same operation. The subtraction with values returns the local time zone's difference from UTC, while the subtraction with values returns . + + :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Overview/Type.cs" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Type/fs/Type.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Type/vb/Type.vb" id="Snippet1"::: + +- Type conversion operations. + + You can convert values to values and vice versa. + +- Time manipulation and extraction operations. + + You can extract either the date or the time of a value. You can also retrieve the value of a particular component, such as its year or its month. + + > [!NOTE] + > If you are working with a ticks value that you want to convert to some other time interval, such as minutes or seconds, you should use the , , , , or constant to perform the conversion. For example, to add the number of seconds represented by a specified number of ticks to the component of a value, you can use the expression `dateValue.Second + nTicks/Timespan.TicksPerSecond`. + + +- Date and time conversion. + + You can convert any value to another value that represents the same point in time in another time zone. However, a time zone's adjustment rules are applied only in the case of the method, which converts a value to the date and time in the local system zone. + +- Date and time comparison. + + You can determine whether any particular value is earlier than, the same as, or later than another value. Before the comparison is performed, all values are converted to UTC. + ]]> Choosing Between DateTime, DateTimeOffset, TimeSpan, and TimeZoneInfo @@ -220,30 +220,30 @@ A date and time. Initializes a new instance of the structure using the specified value. - property of the `dateTime` parameter: - -- If the value of is , the property of the new instance is set equal to `dateTime`, and the property is set equal to . - -- If the value of is or , the property of the new instance is set equal to `dateTime`, and the property is set equal to the offset of the local system's current time zone. - - - -## Examples - The following example illustrates how the value of the property of the `dateTime` parameter affects the date and time value that is returned by this constructor. - - :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/.ctor/Constructors.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Constructors/fs/Constructors.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Constructors/vb/Constructors.vb" id="Snippet1"::: - + property of the `dateTime` parameter: + +- If the value of is , the property of the new instance is set equal to `dateTime`, and the property is set equal to . + +- If the value of is or , the property of the new instance is set equal to `dateTime`, and the property is set equal to the offset of the local system's current time zone. + + + +## Examples + The following example illustrates how the value of the property of the `dateTime` parameter affects the date and time value that is returned by this constructor. + + :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/.ctor/Constructors.cs" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Constructors/fs/Constructors.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Constructors/vb/Constructors.vb" id="Snippet1"::: + ]]> - The Coordinated Universal Time (UTC) date and time that results from applying the offset is earlier than DateTimeOffset.MinValue. - - -or- - + The Coordinated Universal Time (UTC) date and time that results from applying the offset is earlier than DateTimeOffset.MinValue. + + -or- + The UTC date and time that results from applying the offset is later than DateTimeOffset.MaxValue. Instantiating a DateTimeOffset Object @@ -291,43 +291,43 @@ The time's offset from Coordinated Universal Time (UTC). Initializes a new instance of the structure using the specified value and offset. - property of the `dateTime` parameter: - -- If the value of is , the value of the `offset` parameter must be 0 or an is thrown. - -- If the value of is , the value of the `offset` parameter must be equal to the local time zone's offset from Coordinated Universal Time (UTC) for that particular date or an is thrown. - -- If the value of is , the `offset` parameter can have any valid value. - - - -## Examples - The following example shows how to initialize a object with a date and time and the offset of the local time zone when that time zone is not known in advance. - - :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/.ctor/Constructors.cs" id="Snippet3"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Constructors/fs/Constructors.fs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Constructors/vb/Constructors.vb" id="Snippet3"::: - + property of the `dateTime` parameter: + +- If the value of is , the value of the `offset` parameter must be 0 or an is thrown. + +- If the value of is , the value of the `offset` parameter must be equal to the local time zone's offset from Coordinated Universal Time (UTC) for that particular date or an is thrown. + +- If the value of is , the `offset` parameter can have any valid value. + + + +## Examples + The following example shows how to initialize a object with a date and time and the offset of the local time zone when that time zone is not known in advance. + + :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/.ctor/Constructors.cs" id="Snippet3"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Constructors/fs/Constructors.fs" id="Snippet3"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Constructors/vb/Constructors.vb" id="Snippet3"::: + ]]> - equals and does not equal zero. - - -or- - - equals and does not equal the offset of the system's local time zone. - - -or- - + equals and does not equal zero. + + -or- + + equals and does not equal the offset of the system's local time zone. + + -or- + is not specified in whole minutes. - is less than -14 hours or greater than 14 hours. - - -or- - + is less than -14 hours or greater than 14 hours. + + -or- + is less than DateTimeOffset.MinValue or greater than DateTimeOffset.MaxValue. Instantiating a DateTimeOffset Object @@ -375,36 +375,36 @@ The time's offset from Coordinated Universal Time (UTC). Initializes a new instance of the structure using the specified number of ticks and offset. - constructor to instantiate a value with a local time and an offset other than that of the local time zone throws an . You can use this overload of the constructor to work around this limitation. The following example uses the local time's number of ticks to instantiate a value whose offset does not necessarily represent that of the local time: - - :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/.ctor/Constructors.cs" id="Snippet4"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Constructors/fs/Constructors.fs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Constructors/vb/Constructors.vb" id="Snippet4"::: - - - -## Examples - The following example initializes a object by using the number of ticks in an arbitrary date (in this case, July 16, 2007, at 1:32 PM) with an offset of -5. - - :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/.ctor/Constructors.cs" id="Snippet2"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Constructors/fs/Constructors.fs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Constructors/vb/Constructors.vb" id="Snippet2"::: - + constructor to instantiate a value with a local time and an offset other than that of the local time zone throws an . You can use this overload of the constructor to work around this limitation. The following example uses the local time's number of ticks to instantiate a value whose offset does not necessarily represent that of the local time: + + :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/.ctor/Constructors.cs" id="Snippet4"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Constructors/fs/Constructors.fs" id="Snippet4"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Constructors/vb/Constructors.vb" id="Snippet4"::: + + + +## Examples + The following example initializes a object by using the number of ticks in an arbitrary date (in this case, July 16, 2007, at 1:32 PM) with an offset of -5. + + :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/.ctor/Constructors.cs" id="Snippet2"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Constructors/fs/Constructors.fs" id="Snippet2"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Constructors/vb/Constructors.vb" id="Snippet2"::: + ]]> is not specified in whole minutes. - The property is earlier than DateTimeOffset.MinValue or later than DateTimeOffset.MaxValue. - - -or- - - is less than or greater than . - - -or- - + The property is earlier than DateTimeOffset.MinValue or later than DateTimeOffset.MaxValue. + + -or- + + is less than or greater than . + + -or- + s less than -14 hours or greater than 14 hours. Instantiating a DateTimeOffset Object @@ -494,53 +494,53 @@ The time's offset from Coordinated Universal Time (UTC). Initializes a new instance of the structure using the specified year, month, day, hour, minute, second, and offset. - value by using the year, month, and day in another calendar, call the constructor. - - - -## Examples - The following example instantiates a object by using the constructor overload. - - :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/.ctor/Constructors.cs" id="Snippet5"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Constructors/fs/Constructors.fs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Constructors/vb/Constructors.vb" id="Snippet5"::: - + value by using the year, month, and day in another calendar, call the constructor. + + + +## Examples + The following example instantiates a object by using the constructor overload. + + :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/.ctor/Constructors.cs" id="Snippet5"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Constructors/fs/Constructors.fs" id="Snippet5"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Constructors/vb/Constructors.vb" id="Snippet5"::: + ]]> does not represent whole minutes. - is less than one or greater than 9999. - - -or- - - is less than one or greater than 12. - - -or- - - is less than one or greater than the number of days in . - - -or- - - is less than zero or greater than 23. - - -or- - - is less than 0 or greater than 59. - - -or- - - is less than 0 or greater than 59. - - -or- - - is less than -14 hours or greater than 14 hours. - - -or- - + is less than one or greater than 9999. + + -or- + + is less than one or greater than 12. + + -or- + + is less than one or greater than the number of days in . + + -or- + + is less than zero or greater than 23. + + -or- + + is less than 0 or greater than 59. + + -or- + + is less than 0 or greater than 59. + + -or- + + is less than -14 hours or greater than 14 hours. + + -or- + The property is earlier than DateTimeOffset.MinValue or later than DateTimeOffset.MaxValue. Instantiating a DateTimeOffset Object @@ -600,57 +600,57 @@ The time's offset from Coordinated Universal Time (UTC). Initializes a new instance of the structure using the specified year, month, day, hour, minute, second, millisecond, and offset. - value by using the year, month, and day in another calendar, call the constructor. - - - -## Examples - The following example instantiates a object by using the constructor overload. - - :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/.ctor/Constructors.cs" id="Snippet7"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Constructors/fs/Constructors.fs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Constructors/vb/Constructors.vb" id="Snippet7"::: - + value by using the year, month, and day in another calendar, call the constructor. + + + +## Examples + The following example instantiates a object by using the constructor overload. + + :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/.ctor/Constructors.cs" id="Snippet7"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Constructors/fs/Constructors.fs" id="Snippet7"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Constructors/vb/Constructors.vb" id="Snippet7"::: + ]]> does not represent whole minutes. - is less than one or greater than 9999. - - -or- - - is less than one or greater than 12. - - -or- - - is less than one or greater than the number of days in . - - -or- - - is less than zero or greater than 23. - - -or- - - is less than 0 or greater than 59. - - -or- - - is less than 0 or greater than 59. - - -or- - - is less than 0 or greater than 999. - - -or- - - is less than -14 or greater than 14. - - -or- - + is less than one or greater than 9999. + + -or- + + is less than one or greater than 12. + + -or- + + is less than one or greater than the number of days in . + + -or- + + is less than zero or greater than 23. + + -or- + + is less than 0 or greater than 59. + + -or- + + is less than 0 or greater than 59. + + -or- + + is less than 0 or greater than 999. + + -or- + + is less than -14 or greater than 14. + + -or- + The property is earlier than DateTimeOffset.MinValue or later than DateTimeOffset.MaxValue. Instantiating a DateTimeOffset Object @@ -692,15 +692,15 @@ - - - - - - - - - + + + + + + + + + The year. @@ -714,20 +714,20 @@ The time's offset from Coordinated Universal Time (UTC). Initializes a new instance of the structure using the specified year, month, day, hour, minute, second, millisecond, and offset of a specified calendar. - class and the class to instantiate a value. That date is then displayed to the console using the respective calendars and the Gregorian calendar. - - :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/.ctor/Constructors.cs" id="Snippet8"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Constructors/fs/Constructors.fs" id="Snippet8"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Constructors/vb/Constructors.vb" id="Snippet8"::: - + class and the class to instantiate a value. That date is then displayed to the console using the respective calendars and the Gregorian calendar. + + :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/.ctor/Constructors.cs" id="Snippet8"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Constructors/fs/Constructors.fs" id="Snippet8"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Constructors/vb/Constructors.vb" id="Snippet8"::: + ]]> @@ -735,42 +735,42 @@ cannot be . - is less than the parameter's or greater than . - - -or- - - is either less than or greater than the number of months in in the . - - -or- - - is less than one or greater than the number of days in . - - -or- - - is less than zero or greater than 23. - - -or- - - is less than 0 or greater than 59. - - -or- - - is less than 0 or greater than 59. - - -or- - - is less than 0 or greater than 999. - - -or- - - is less than -14 hours or greater than 14 hours. - - -or- - - The , , and parameters cannot be represented as a date and time value. - - -or- - + is less than the parameter's or greater than . + + -or- + + is either less than or greater than the number of months in in the . + + -or- + + is less than one or greater than the number of days in . + + -or- + + is less than zero or greater than 23. + + -or- + + is less than 0 or greater than 59. + + -or- + + is less than 0 or greater than 59. + + -or- + + is less than 0 or greater than 999. + + -or- + + is less than -14 hours or greater than 14 hours. + + -or- + + The , , and parameters cannot be represented as a date and time value. + + -or- + The property is earlier than DateTimeOffset.MinValue or later than DateTimeOffset.MaxValue. Instantiating a DateTimeOffset Object @@ -818,47 +818,47 @@ The time's offset from Coordinated Universal Time (UTC). Initializes a new instance of the structure using the specified , , , , , , , and . - value by using the year, month and day in another calendar, call - the constructor. - + value by using the year, month and day in another calendar, call + the constructor. + ]]> does not represent whole minutes. - is less than 1 or greater than 9999. - --or- - - is less than 1 or greater than 12. - --or- - - is less than 1 or greater than the number of days in . - --or- - - is less than 0 or greater than 23. - --or- - - is less than 0 or greater than 59. - --or- - - is less than 0 or greater than 59. - --or- - - is less than 0 or greater than 999. - --or- - + is less than 1 or greater than 9999. + +-or- + + is less than 1 or greater than 12. + +-or- + + is less than 1 or greater than the number of days in . + +-or- + + is less than 0 or greater than 23. + +-or- + + is less than 0 or greater than 59. + +-or- + + is less than 0 or greater than 59. + +-or- + + is less than 0 or greater than 999. + +-or- + is less than 0 or greater than 999. @@ -913,60 +913,60 @@ This constructor interprets `year`, `month` and `day` as a year, month and day The time's offset from Coordinated Universal Time (UTC). Initializes a new instance of the structure using the specified , , , , , , , and . - value by using the year, month and day in another calendar, call - the constructor. - + value by using the year, month and day in another calendar, call + the constructor. + ]]> does not represent whole minutes. - is not in the range supported by . - --or- - - is less than 1 or greater than the number of months in . - --or- - - is less than 1 or greater than the number of days in . - --or- - - is less than 0 or greater than 23. - --or- - - is less than 0 or greater than 59. - --or- - - is less than 0 or greater than 59. - --or- - - is less than 0 or greater than 999. - --or- - - is less than 0 or greater than 999. - --or- - - is less than -14 hours or greater than 14 hours. - --or- - -The , , and parameters - cannot be represented as a date and time value. - --or- - + is not in the range supported by . + +-or- + + is less than 1 or greater than the number of months in . + +-or- + + is less than 1 or greater than the number of days in . + +-or- + + is less than 0 or greater than 23. + +-or- + + is less than 0 or greater than 59. + +-or- + + is less than 0 or greater than 59. + +-or- + + is less than 0 or greater than 999. + +-or- + + is less than 0 or greater than 999. + +-or- + + is less than -14 hours or greater than 14 hours. + +-or- + +The , , and parameters + cannot be represented as a date and time value. + +-or- + The property is earlier than or later than . @@ -1015,35 +1015,35 @@ The property is earlier than Returns a new object that adds a specified time interval to the value of this instance. An object whose value is the sum of the date and time represented by the current object and the time interval represented by . - method to add more than one kind of time interval (days, hours, minutes, seconds, or milliseconds) in a single operation. This method's behavior is identical to the addition operator. The structure also supports specialized addition methods (such as , , and ) for each time interval. - -> [!NOTE] -> This method returns a new object. It does not modify the value of the current object by adding `timeSpan` to its date and time. - - The method does not affect the value of the current object's property. - - Because a object does not represent the date and time in a specific time zone, the method does not consider a particular time zone's adjustment rules when it performs date and time arithmetic. - - If the `timeSpan` parameter is `null`, this method returns the value of the original object unchanged. - - - -## Examples - The following example creates an array of objects that represent the flight times between destinations. The method then adds these times to a object that represents a flight's initial takeoff time. The result reflects the scheduled arrival time at each destination. - - :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Add/Methods.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Methods/fs/Methods.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Methods/vb/Methods.vb" id="Snippet1"::: - + method to add more than one kind of time interval (days, hours, minutes, seconds, or milliseconds) in a single operation. This method's behavior is identical to the addition operator. The structure also supports specialized addition methods (such as , , and ) for each time interval. + +> [!NOTE] +> This method returns a new object. It does not modify the value of the current object by adding `timeSpan` to its date and time. + + The method does not affect the value of the current object's property. + + Because a object does not represent the date and time in a specific time zone, the method does not consider a particular time zone's adjustment rules when it performs date and time arithmetic. + + If the `timeSpan` parameter is `null`, this method returns the value of the original object unchanged. + + + +## Examples + The following example creates an array of objects that represent the flight times between destinations. The method then adds these times to a object that represents a flight's initial takeoff time. The result reflects the scheduled arrival time at each destination. + + :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Add/Methods.cs" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Methods/fs/Methods.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Methods/vb/Methods.vb" id="Snippet1"::: + ]]> - The resulting value is less than DateTimeOffset.MinValue. - - -or- - + The resulting value is less than DateTimeOffset.MinValue. + + -or- + The resulting value is greater than DateTimeOffset.MaxValue. Performing Arithmetic Operations with Dates and Times @@ -1094,36 +1094,36 @@ The property is earlier than Returns a new object that adds a specified number of whole and fractional days to the value of this instance. An object whose value is the sum of the date and time represented by the current object and the number of days represented by . - precision of the `days` parameter is used. However, due to the inherent imprecision of floating point math, the resulting precision will vary. - -> [!NOTE] -> This method returns a new object. It does not modify the value of the current object by adding `days` to its date and time. - - Because a object does not represent the date and time in a specific time zone, the method does not consider a particular time zone's adjustment rules when it performs date and time arithmetic. - - Converting time intervals of less than a day to a fraction can involve a loss of precision. If this is problematic, you can use the method, which enables you to specify more than one kind of time interval in a single method call and eliminates the need to convert time intervals to fractional parts of a day. - - - -## Examples - The following example uses the method to list the dates that fall on Monday, the start of the work week, in March 2008. - - :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Add/Methods.cs" interactive="try-dotnet-method" id="Snippet2"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Methods/fs/Methods.fs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Methods/vb/Methods.vb" id="Snippet2"::: - + precision of the `days` parameter is used. However, due to the inherent imprecision of floating point math, the resulting precision will vary. + +> [!NOTE] +> This method returns a new object. It does not modify the value of the current object by adding `days` to its date and time. + + Because a object does not represent the date and time in a specific time zone, the method does not consider a particular time zone's adjustment rules when it performs date and time arithmetic. + + Converting time intervals of less than a day to a fraction can involve a loss of precision. If this is problematic, you can use the method, which enables you to specify more than one kind of time interval in a single method call and eliminates the need to convert time intervals to fractional parts of a day. + + + +## Examples + The following example uses the method to list the dates that fall on Monday, the start of the work week, in March 2008. + + :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Add/Methods.cs" interactive="try-dotnet-method" id="Snippet2"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Methods/fs/Methods.fs" id="Snippet2"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Methods/vb/Methods.vb" id="Snippet2"::: + ]]> - The resulting value is less than DateTimeOffset.MinValue. - - -or- - + The resulting value is less than DateTimeOffset.MinValue. + + -or- + The resulting value is greater than DateTimeOffset.MaxValue. @@ -1172,34 +1172,34 @@ In .NET 6 and earlier versions, the `days` parameter is rounded to the nearest m Returns a new object that adds a specified number of whole and fractional hours to the value of this instance. An object whose value is the sum of the date and time represented by the current object and the number of hours represented by . - precision of the `hours` parameter is used. However, due to the inherent imprecision of floating point math, the resulting precision will vary. - -> [!NOTE] -> This method returns a new object. It does not modify the value of the current object by adding `hours` to its date and time. - - Because a object does not represent the date and time in a specific time zone, the method does not consider a particular time zone's adjustment rules when it performs date and time arithmetic. - - Converting time intervals of less than an hour to a fraction can involve a loss of precision. (For example, one minute is 0.01666 of an hour.) If this is problematic, you can use the method, which enables you to specify more than one kind of time interval in a single method call and eliminates the need to convert time intervals to fractional parts of an hour. - -## Examples - The following example uses the method to list the start times of work shifts for a particular week at an office that has two eight-hour shifts per day. - - :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Add/Methods.cs" id="Snippet3"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Methods/fs/Methods.fs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Methods/vb/Methods.vb" id="Snippet3"::: - + precision of the `hours` parameter is used. However, due to the inherent imprecision of floating point math, the resulting precision will vary. + +> [!NOTE] +> This method returns a new object. It does not modify the value of the current object by adding `hours` to its date and time. + + Because a object does not represent the date and time in a specific time zone, the method does not consider a particular time zone's adjustment rules when it performs date and time arithmetic. + + Converting time intervals of less than an hour to a fraction can involve a loss of precision. (For example, one minute is 0.01666 of an hour.) If this is problematic, you can use the method, which enables you to specify more than one kind of time interval in a single method call and eliminates the need to convert time intervals to fractional parts of an hour. + +## Examples + The following example uses the method to list the start times of work shifts for a particular week at an office that has two eight-hour shifts per day. + + :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Add/Methods.cs" id="Snippet3"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Methods/fs/Methods.fs" id="Snippet3"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Methods/vb/Methods.vb" id="Snippet3"::: + ]]> - The resulting value is less than DateTimeOffset.MinValue. - - -or- - + The resulting value is less than DateTimeOffset.MinValue. + + -or- + The resulting value is greater than DateTimeOffset.MaxValue. Performing Arithmetic Operations with Dates and Times @@ -1235,24 +1235,24 @@ In .NET 6 and earlier versions, the `hours` parameter is rounded to the nearest Returns a new object that adds a specified number of microseconds to the value of this instance. An object whose value is the sum of the date and time represented by the current object and the number of whole microseconds represented by . - object does not represent the date and time in a specific time zone, - the method does not consider a particular time zone's adjustment rules - when it performs date and time arithmetic. - + object does not represent the date and time in a specific time zone, + the method does not consider a particular time zone's adjustment rules + when it performs date and time arithmetic. + ]]> - The resulting value is less than DateTimeOffset.MinValue. - --or- - + The resulting value is less than DateTimeOffset.MinValue. + +-or- + The resulting value is greater than DateTimeOffset.MaxValue. @@ -1301,23 +1301,23 @@ The resulting value is greater than Returns a new object that adds a specified number of milliseconds to the value of this instance. An object whose value is the sum of the date and time represented by the current object and the number of whole milliseconds represented by . - precision of the `milliseconds` parameter is used. However, due to the inherent imprecision of floating point math, the resulting precision will vary. - -> [!NOTE] -> This method returns a new object. It does not modify the value of the current object by adding `milliseconds` to its date and time. - - Because a object does not represent the date and time in a specific time zone, the method does not consider a particular time zone's adjustment rules when it performs date and time arithmetic. - + precision of the `milliseconds` parameter is used. However, due to the inherent imprecision of floating point math, the resulting precision will vary. + +> [!NOTE] +> This method returns a new object. It does not modify the value of the current object by adding `milliseconds` to its date and time. + + Because a object does not represent the date and time in a specific time zone, the method does not consider a particular time zone's adjustment rules when it performs date and time arithmetic. + ]]> - The resulting value is less than DateTimeOffset.MinValue. - - -or- - + The resulting value is less than DateTimeOffset.MinValue. + + -or- + The resulting value is greater than DateTimeOffset.MaxValue. Performing Arithmetic Operations with Dates and Times @@ -1367,27 +1367,27 @@ The fractional part of the `milliseconds` parameter is the fractional part of a Returns a new object that adds a specified number of whole and fractional minutes to the value of this instance. An object whose value is the sum of the date and time represented by the current object and the number of minutes represented by . - precision of the `minutes` parameter is used. However, due to the inherent imprecision of floating point math, the resulting precision will vary. - -> [!NOTE] -> This method returns a new object. It does not modify the value of the current object by adding `minutes` to its date and time. - - Because a object does not represent the date and time in a specific time zone, the method does not consider a particular time zone's adjustment rules when it performs date and time arithmetic. - - Converting time intervals of less than a minute to a fraction can involve a loss of precision. (For example, one second is 0.01666 of a minute.) If this is problematic, you can use the method, which enables you to specify more than one kind of time interval in a single method call and eliminates the need to convert time intervals to fractional parts of a minute. - + precision of the `minutes` parameter is used. However, due to the inherent imprecision of floating point math, the resulting precision will vary. + +> [!NOTE] +> This method returns a new object. It does not modify the value of the current object by adding `minutes` to its date and time. + + Because a object does not represent the date and time in a specific time zone, the method does not consider a particular time zone's adjustment rules when it performs date and time arithmetic. + + Converting time intervals of less than a minute to a fraction can involve a loss of precision. (For example, one second is 0.01666 of a minute.) If this is problematic, you can use the method, which enables you to specify more than one kind of time interval in a single method call and eliminates the need to convert time intervals to fractional parts of a minute. + ]]> - The resulting value is less than DateTimeOffset.MinValue. - - -or- - + The resulting value is less than DateTimeOffset.MinValue. + + -or- + The resulting value is greater than DateTimeOffset.MaxValue. Performing Arithmetic Operations with Dates and Times @@ -1437,29 +1437,29 @@ In .NET 6 and earlier versions, the `minutes` parameter is rounded to the neares Returns a new object that adds a specified number of months to the value of this instance. An object whose value is the sum of the date and time represented by the current object and the number of months represented by . - does not enable you to add fractional parts of a month. To add a time that consists of other time units in addition to months to a object, use the method. - -> [!NOTE] -> This method returns a new object. It does not modify the value of the current object by adding `months` to its date and time. - - - -## Examples - The following example uses the method to display the start date of each quarter of the year 2007. - - :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Add/Methods.cs" id="Snippet4"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Methods/fs/Methods.fs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Methods/vb/Methods.vb" id="Snippet4"::: - + does not enable you to add fractional parts of a month. To add a time that consists of other time units in addition to months to a object, use the method. + +> [!NOTE] +> This method returns a new object. It does not modify the value of the current object by adding `months` to its date and time. + + + +## Examples + The following example uses the method to display the start date of each quarter of the year 2007. + + :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Add/Methods.cs" id="Snippet4"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Methods/fs/Methods.fs" id="Snippet4"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Methods/vb/Methods.vb" id="Snippet4"::: + ]]> - The resulting value is less than DateTimeOffset.MinValue. - - -or- - + The resulting value is less than DateTimeOffset.MinValue. + + -or- + The resulting value is greater than DateTimeOffset.MaxValue. @@ -1508,30 +1508,30 @@ In .NET 6 and earlier versions, the `minutes` parameter is rounded to the neares Returns a new object that adds a specified number of whole and fractional seconds to the value of this instance. An object whose value is the sum of the date and time represented by the current object and the number of seconds represented by . - precision of the `seconds` parameter is used. However, due to the inherent imprecision of floating point math, the resulting precision will vary. - -> [!NOTE] -> This method returns a new object. It does not modify the value of the current object by adding `seconds` to its date and time. - - Because a object does not represent the date and time in a specific time zone, the method does not consider a particular time zone's adjustment rules when it performs date and time arithmetic. - + precision of the `seconds` parameter is used. However, due to the inherent imprecision of floating point math, the resulting precision will vary. + +> [!NOTE] +> This method returns a new object. It does not modify the value of the current object by adding `seconds` to its date and time. + + Because a object does not represent the date and time in a specific time zone, the method does not consider a particular time zone's adjustment rules when it performs date and time arithmetic. + ]]> - The resulting value is less than DateTimeOffset.MinValue. - - -or- - + The resulting value is less than DateTimeOffset.MinValue. + + -or- + The resulting value is greater than DateTimeOffset.MaxValue. Performing Arithmetic Operations with Dates and Times @@ -1581,35 +1581,35 @@ In .NET 6 and earlier versions, the `seconds` parameter is rounded to the neares Returns a new object that adds a specified number of ticks to the value of this instance. An object whose value is the sum of the date and time represented by the current object and the number of ticks represented by . - [!NOTE] -> This method returns a new object. It does not modify the value of the current object by adding `ticks` to its date and time. - - The following table lists the number of ticks in a particular time interval. - -|Time interval|Number of ticks| -|-------------------|---------------------| -|Second|10,000,000| -|Minute|600,000,000| -|Hour|36,000,000,000| -|Day|864,000,000,000| -|Week|6,048,000,000,000| -|Month|Depends on number of days in the month.| -|Non-leap year|315,360,000,000,000| -|Leap year|316,224,000,000,000| - - Because a object does not represent the date and time in a specific time zone, the method does not consider a particular time zone's adjustment rules when it performs date and time arithmetic. - + [!NOTE] +> This method returns a new object. It does not modify the value of the current object by adding `ticks` to its date and time. + + The following table lists the number of ticks in a particular time interval. + +|Time interval|Number of ticks| +|-------------------|---------------------| +|Second|10,000,000| +|Minute|600,000,000| +|Hour|36,000,000,000| +|Day|864,000,000,000| +|Week|6,048,000,000,000| +|Month|Depends on number of days in the month.| +|Non-leap year|315,360,000,000,000| +|Leap year|316,224,000,000,000| + + Because a object does not represent the date and time in a specific time zone, the method does not consider a particular time zone's adjustment rules when it performs date and time arithmetic. + ]]> - The resulting value is less than DateTimeOffset.MinValue. - - -or- - + The resulting value is less than DateTimeOffset.MinValue. + + -or- + The resulting value is greater than DateTimeOffset.MaxValue. Performing Arithmetic Operations with Dates and Times @@ -1659,27 +1659,27 @@ In .NET 6 and earlier versions, the `seconds` parameter is rounded to the neares Returns a new object that adds a specified number of years to the value of this instance. An object whose value is the sum of the date and time represented by the current object and the number of years represented by . - does not enable you to add fractional parts of a year. To add a time that consists of other time units in addition to years to a object, use the method. - -> [!NOTE] -> This method returns a new object. It does not modify the value of the current object by adding `years` to its date and time. - -## Examples - In the United States, driver's licenses cannot be issued to persons under 16 years of age. The following example displays the latest possible date on which a person must be born in order to legally be issued a driver's license. - - :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Add/Methods.cs" id="Snippet6"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Methods/fs/Methods.fs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Methods/vb/Methods.vb" id="Snippet6"::: - + does not enable you to add fractional parts of a year. To add a time that consists of other time units in addition to years to a object, use the method. + +> [!NOTE] +> This method returns a new object. It does not modify the value of the current object by adding `years` to its date and time. + +## Examples + In the United States, driver's licenses cannot be issued to persons under 16 years of age. The following example displays the latest possible date on which a person must be born in order to legally be issued a driver's license. + + :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Add/Methods.cs" id="Snippet6"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Methods/fs/Methods.fs" id="Snippet6"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Methods/vb/Methods.vb" id="Snippet6"::: + ]]> - The resulting value is less than DateTimeOffset.MinValue. - - -or- - + The resulting value is less than DateTimeOffset.MinValue. + + -or- + The resulting value is greater than DateTimeOffset.MaxValue. @@ -1728,46 +1728,46 @@ In .NET 6 and earlier versions, the `seconds` parameter is rounded to the neares The first object to compare. The second object to compare. Compares two objects and indicates whether the first is earlier than the second, equal to the second, or later than the second. - A signed integer that indicates whether the value of the parameter is earlier than, later than, or the same time as the value of the parameter, as the following table shows. - - Return value - - Meaning - - Less than zero - - is earlier than . - - Zero - - is equal to . - - Greater than zero - - is later than . - + A signed integer that indicates whether the value of the parameter is earlier than, later than, or the same time as the value of the parameter, as the following table shows. + + Return value + + Meaning + + Less than zero + + is earlier than . + + Zero + + is equal to . + + Greater than zero + + is later than . + - method determines whether two objects represent a single point in time. It directly compares neither dates and times nor offsets. - - - -## Examples - The following example illustrates calls to the method to compare objects. - - :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Add/Methods2.cs" id="Snippet7"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Methods/fs/Methods2.fs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Methods/vb/Methods2.vb" id="Snippet7"::: - + method determines whether two objects represent a single point in time. It directly compares neither dates and times nor offsets. + + + +## Examples + The following example illustrates calls to the method to compare objects. + + :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Add/Methods2.cs" id="Snippet7"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Methods/fs/Methods2.fs" id="Snippet7"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Methods/vb/Methods2.vb" id="Snippet7"::: + ]]> @@ -1818,40 +1818,40 @@ In .NET 6 and earlier versions, the `seconds` parameter is rounded to the neares An object to compare with the current object. Compares the current object to a specified object and indicates whether the current object is earlier than, the same as, or later than the second object. - A signed integer that indicates the relationship between the current object and , as the following table shows. - - Return Value - - Description - - Less than zero - - The current object is earlier than . - - Zero - - The current object is the same as . - - Greater than zero. - - The current object is later than . - + A signed integer that indicates the relationship between the current object and , as the following table shows. + + Return Value + + Description + + Less than zero + + The current object is earlier than . + + Zero + + The current object is the same as . + + Greater than zero. + + The current object is later than . + - objects by comparing their values; that is, it determines whether the two objects represent a single point in time, and indicates whether the current object is earlier than, later than, or the same as the `other` parameter. - - - -## Examples - The following example illustrates calls to the method to compare objects. - - :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Add/Methods3.cs" id="Snippet8"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Methods/fs/Methods3.fs" id="Snippet8"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Methods/vb/Methods3.vb" id="Snippet8"::: - + objects by comparing their values; that is, it determines whether the two objects represent a single point in time, and indicates whether the current object is earlier than, later than, or the same as the `other` parameter. + + + +## Examples + The following example illustrates calls to the method to compare objects. + + :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Add/Methods3.cs" id="Snippet8"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Methods/fs/Methods3.fs" id="Snippet8"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Methods/vb/Methods3.vb" id="Snippet8"::: + ]]> @@ -1897,24 +1897,24 @@ In .NET 6 and earlier versions, the `seconds` parameter is rounded to the neares Gets a value that represents the date component of the current object. A value that represents the date component of the current object. - object and returns only its significant date component. For example, if the object has a date and time value of "1/12/07 4:01pm +7:30", the property returns a value of "1/12/07 12:00:00 AM". The value can then be displayed by using any of the standard or custom format specifiers that display dates only. (See the Example section for an illustration.) - - The value of the property of the returned object is always . It is not affected by the value of the property. - - To display a date without its time component, you can also use the "D" or "d" format specifiers; for an illustration, see the Example section. - - - -## Examples - The following example retrieves the value of the property for a specific date. It then displays that value to the console using some standard and custom date-only format specifiers. - - :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Date/Properties.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Properties/fs/Properties.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Properties/vb/Properties.vb" id="Snippet1"::: - + object and returns only its significant date component. For example, if the object has a date and time value of "1/12/07 4:01pm +7:30", the property returns a value of "1/12/07 12:00:00 AM". The value can then be displayed by using any of the standard or custom format specifiers that display dates only. (See the Example section for an illustration.) + + The value of the property of the returned object is always . It is not affected by the value of the property. + + To display a date without its time component, you can also use the "D" or "d" format specifiers; for an illustration, see the Example section. + + + +## Examples + The following example retrieves the value of the property for a specific date. It then displays that value to the console using some standard and custom date-only format specifiers. + + :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Date/Properties.cs" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Properties/fs/Properties.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Properties/vb/Properties.vb" id="Snippet1"::: + ]]> Standard DateTime Format Strings @@ -1962,24 +1962,24 @@ In .NET 6 and earlier versions, the `seconds` parameter is rounded to the neares Gets a value that represents the date and time of the current object. The date and time of the current object. - property is not affected by the value of the property. - - This property returns both the date and the time component of a object, which makes it useful for performing to conversion. For example, if the object has a date and time value of "1/12/07 4:01pm + 7:30", the property returns a date of "1/12/07 4:01pm". - - The value of the property of the returned object is . - - - -## Examples - The following example illustrates the use of the property to convert the time returned by the and properties to values. - - :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Date/Properties.cs" id="Snippet2"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Properties/fs/Properties.fs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Properties/vb/Properties.vb" id="Snippet2"::: - + property is not affected by the value of the property. + + This property returns both the date and the time component of a object, which makes it useful for performing to conversion. For example, if the object has a date and time value of "1/12/07 4:01pm + 7:30", the property returns a date of "1/12/07 4:01pm". + + The value of the property of the returned object is . + + + +## Examples + The following example illustrates the use of the property to convert the time returned by the and properties to values. + + :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Date/Properties.cs" id="Snippet2"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Properties/fs/Properties.fs" id="Snippet2"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Properties/vb/Properties.vb" id="Snippet2"::: + ]]> @@ -2027,28 +2027,28 @@ In .NET 6 and earlier versions, the `seconds` parameter is rounded to the neares Gets the day of the month represented by the current object. The day component of the current object, expressed as a value between 1 and 31. - property is not affected by the value of the property. - - You can also create a string representation of a object's day component by calling the method with the "d" or "dd" custom format specifiers. - - - -## Examples - The following example displays the day component of a object in three different ways: - -- By retrieving the value of the property. - -- By calling the method with the "d" format specifier. - -- By calling the method with the "dd" format specifier. - - :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Date/Properties.cs" id="Snippet10"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Properties/fs/Properties.fs" id="Snippet10"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Properties/vb/Properties.vb" id="Snippet10"::: - + property is not affected by the value of the property. + + You can also create a string representation of a object's day component by calling the method with the "d" or "dd" custom format specifiers. + + + +## Examples + The following example displays the day component of a object in three different ways: + +- By retrieving the value of the property. + +- By calling the method with the "d" format specifier. + +- By calling the method with the "dd" format specifier. + + :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Date/Properties.cs" id="Snippet10"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Properties/fs/Properties.fs" id="Snippet10"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Properties/vb/Properties.vb" id="Snippet10"::: + ]]> @@ -2094,32 +2094,32 @@ In .NET 6 and earlier versions, the `seconds` parameter is rounded to the neares Gets the day of the week represented by the current object. One of the enumeration values that indicates the day of the week of the current object. - enumeration ranges from to . If cast to an integer, its value ranges from zero (which indicates ) to six (which indicates ). - - You can also display the weekday name of a particular date by using the "D" format specifier or the "dddd" custom format specifier. For example: - - :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Date/Properties.cs" id="Snippet4"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Properties/fs/Properties.fs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Properties/vb/Properties.vb" id="Snippet4"::: - - Note that the string returned by calling the `ToString` method of the enumeration member that is returned by this property is not localized. To extract a string that contains the weekday name of the current culture or of a specific culture, call the method with the "dddd" custom format specifier. For example, the following code displays the weekday name for a date using the `fr-fr` culture. - - :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Date/Properties.cs" id="Snippet5"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Properties/fs/Properties.fs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Properties/vb/Properties.vb" id="Snippet5"::: - - - -## Examples - The following example displays the weekday name of the first day of each month of the year 2008. - - :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Date/Properties.cs" id="Snippet3"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Properties/fs/Properties.fs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Properties/vb/Properties.vb" id="Snippet3"::: - + enumeration ranges from to . If cast to an integer, its value ranges from zero (which indicates ) to six (which indicates ). + + You can also display the weekday name of a particular date by using the "D" format specifier or the "dddd" custom format specifier. For example: + + :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Date/Properties.cs" id="Snippet4"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Properties/fs/Properties.fs" id="Snippet4"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Properties/vb/Properties.vb" id="Snippet4"::: + + Note that the string returned by calling the `ToString` method of the enumeration member that is returned by this property is not localized. To extract a string that contains the weekday name of the current culture or of a specific culture, call the method with the "dddd" custom format specifier. For example, the following code displays the weekday name for a date using the `fr-fr` culture. + + :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Date/Properties.cs" id="Snippet5"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Properties/fs/Properties.fs" id="Snippet5"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Properties/vb/Properties.vb" id="Snippet5"::: + + + +## Examples + The following example displays the weekday name of the first day of each month of the year 2008. + + :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Date/Properties.cs" id="Snippet3"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Properties/fs/Properties.fs" id="Snippet3"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Properties/vb/Properties.vb" id="Snippet3"::: + ]]> @@ -2270,30 +2270,30 @@ In .NET 6 and earlier versions, the `seconds` parameter is rounded to the neares if both objects have the same value; otherwise, . - objects to Coordinated Universal Time (UTC). The method is equivalent to the following: - - :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Compare/Syntax.cs" id="Snippet2"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Syntax/fs/Syntax.fs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Syntax/vb/Syntax.vb" id="Snippet2"::: - - In other words, the method determines whether two objects represent a single point in time. It directly compares neither dates and times nor offsets. To determine whether two objects represent the same time and have the same offset value, use the method. - - A object that is not `null` is considered to be later (or greater) than one that is `null`. - - This overload of the method implements the method. It offers slightly better performance than the overload because the `other` parameter does not have to be converted from an object. - - - -## Examples - The following example illustrates calls to the method to test objects for equality with the current object. - - :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Add/Methods.cs" id="Snippet9"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Methods/fs/Methods.fs" id="Snippet9"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Methods/vb/Methods.vb" id="Snippet9"::: - + objects to Coordinated Universal Time (UTC). The method is equivalent to the following: + + :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Compare/Syntax.cs" id="Snippet2"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Syntax/fs/Syntax.fs" id="Snippet2"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Syntax/vb/Syntax.vb" id="Snippet2"::: + + In other words, the method determines whether two objects represent a single point in time. It directly compares neither dates and times nor offsets. To determine whether two objects represent the same time and have the same offset value, use the method. + + A object that is not `null` is considered to be later (or greater) than one that is `null`. + + This overload of the method implements the method. It offers slightly better performance than the overload because the `other` parameter does not have to be converted from an object. + + + +## Examples + The following example illustrates calls to the method to test objects for equality with the current object. + + :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Add/Methods.cs" id="Snippet9"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Methods/fs/Methods.fs" id="Snippet9"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Methods/vb/Methods.vb" id="Snippet9"::: + ]]> @@ -2359,28 +2359,28 @@ In .NET 6 and earlier versions, the `seconds` parameter is rounded to the neares if the parameter is a object and represents the same point in time as the current object; otherwise, . - object and the `obj` parameter to Coordinated Universal Time (UTC). The method is equivalent to the following: - - :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Compare/Syntax.cs" id="Snippet3"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Syntax/fs/Syntax.fs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Syntax/vb/Syntax.vb" id="Snippet3"::: - - In other words, the method determines whether the current object and a specified object represent a single point in time. It directly compares neither dates and times nor offsets. To determine whether two objects represent the same time and have the same offset value, use the method. - - If `obj` is `null`, or if the run-time type of `obj` is not , the method returns `false`. - - - -## Examples - The following example indicates whether the current object is equal to several other objects, as well as to a null reference and a object. - - :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Add/Methods.cs" id="Snippet10"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Methods/fs/Methods.fs" id="Snippet10"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Methods/vb/Methods.vb" id="Snippet10"::: - + object and the `obj` parameter to Coordinated Universal Time (UTC). The method is equivalent to the following: + + :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Compare/Syntax.cs" id="Snippet3"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Syntax/fs/Syntax.fs" id="Snippet3"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Syntax/vb/Syntax.vb" id="Snippet3"::: + + In other words, the method determines whether the current object and a specified object represent a single point in time. It directly compares neither dates and times nor offsets. To determine whether two objects represent the same time and have the same offset value, use the method. + + If `obj` is `null`, or if the run-time type of `obj` is not , the method returns `false`. + + + +## Examples + The following example indicates whether the current object is equal to several other objects, as well as to a null reference and a object. + + :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Add/Methods.cs" id="Snippet10"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Methods/fs/Methods.fs" id="Snippet10"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Methods/vb/Methods.vb" id="Snippet10"::: + ]]> @@ -2434,26 +2434,26 @@ In .NET 6 and earlier versions, the `seconds` parameter is rounded to the neares if the two objects have the same value; otherwise, . - objects to Coordinated Universal Time (UTC). The method is equivalent to the following: - - :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Compare/Syntax.cs" id="Snippet4"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Syntax/fs/Syntax.fs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Syntax/vb/Syntax.vb" id="Snippet4"::: - - In other words, the method determines whether the two objects represent a single point in time. It directly compares neither dates and times nor offsets. To determine whether two objects represent the same time and have the same offset value, use the method. - - - -## Examples - The following example illustrates calls to the method to test various pairs of objects for equality. - - :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Add/Methods.cs" id="Snippet11"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Methods/fs/Methods.fs" id="Snippet11"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Methods/vb/Methods.vb" id="Snippet11"::: - + objects to Coordinated Universal Time (UTC). The method is equivalent to the following: + + :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Compare/Syntax.cs" id="Snippet4"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Syntax/fs/Syntax.fs" id="Snippet4"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Syntax/vb/Syntax.vb" id="Snippet4"::: + + In other words, the method determines whether the two objects represent a single point in time. It directly compares neither dates and times nor offsets. To determine whether two objects represent the same time and have the same offset value, use the method. + + + +## Examples + The following example illustrates calls to the method to test various pairs of objects for equality. + + :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Add/Methods.cs" id="Snippet11"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Methods/fs/Methods.fs" id="Snippet11"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Methods/vb/Methods.vb" id="Snippet11"::: + ]]> @@ -2505,22 +2505,22 @@ In .NET 6 and earlier versions, the `seconds` parameter is rounded to the neares if the current object and have the same date and time value and the same value; otherwise, . - method, the overloads of the method determine only whether two values represent a single point in time. They do not indicate that two values have the same date and time as well as the same offset. - - - -## Examples - The following example illustrates the use of the method to compare similar objects. - - :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Add/Methods.cs" id="Snippet12"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Methods/fs/Methods.fs" id="Snippet12"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Methods/vb/Methods.vb" id="Snippet12"::: - + method, the overloads of the method determine only whether two values represent a single point in time. They do not indicate that two values have the same date and time as well as the same offset. + + + +## Examples + The following example illustrates the use of the method to compare similar objects. + + :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Add/Methods.cs" id="Snippet12"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Methods/fs/Methods.fs" id="Snippet12"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Methods/vb/Methods.vb" id="Snippet12"::: + ]]> @@ -2571,31 +2571,31 @@ In .NET 6 and earlier versions, the `seconds` parameter is rounded to the neares Converts the specified Windows file time to an equivalent local time. An object that represents the date and time of with the offset set to the local time offset. - values. - - Windows file time values can also be created from values by calling the and methods, and from values by calling the method. - - - -## Examples - The following example uses the Windows API to retrieve the Windows file times for the WordPad executable. - - :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/FromFileTime/FileTime.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.FromFileTime/fs/FileTime.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.FromFileTime/vb/FileTime.vb" id="Snippet1"::: - + values. + + Windows file time values can also be created from values by calling the and methods, and from values by calling the method. + + + +## Examples + The following example uses the Windows API to retrieve the Windows file times for the WordPad executable. + + :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/FromFileTime/FileTime.cs" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.FromFileTime/fs/FileTime.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.FromFileTime/vb/FileTime.vb" id="Snippet1"::: + ]]> - is less than zero. - - -or- - + is less than zero. + + -or- + is greater than .
@@ -2641,18 +2641,18 @@ In .NET 6 and earlier versions, the `seconds` parameter is rounded to the neares Converts a Unix time expressed as the number of milliseconds that have elapsed since 1970-01-01T00:00:00Z to a value. A date and time value that represents the same moment in time as the Unix time. - property value of the returned instance is , which represents Coordinated Universal Time. You can convert it to the time in a specific time zone by calling the method. - + property value of the returned instance is , which represents Coordinated Universal Time. You can convert it to the time in a specific time zone by calling the method. + ]]> - is less than -62,135,596,800,000. - - -or- - + is less than -62,135,596,800,000. + + -or- + is greater than 253,402,300,799,999. @@ -2700,18 +2700,18 @@ In .NET 6 and earlier versions, the `seconds` parameter is rounded to the neares Converts a Unix time expressed as the number of seconds that have elapsed since 1970-01-01T00:00:00Z to a value. A date and time value that represents the same moment in time as the Unix time. - property value of the returned instance is , which represents Coordinated Universal Time. You can convert it to the time in a specific time zone by calling the method. - + property value of the returned instance is , which represents Coordinated Universal Time. You can convert it to the time in a specific time zone by calling the method. + ]]> - is less than -62,135,596,800. - - -or- - + is less than -62,135,596,800. + + -or- + is greater than 253,402,300,799. @@ -2802,28 +2802,28 @@ In .NET 6 and earlier versions, the `seconds` parameter is rounded to the neares Gets the hour component of the time represented by the current object. The hour component of the current object. This property uses a 24-hour clock; the value ranges from 0 to 23. - property is not affected by the value of the property. - - You can also create a string representation of a object's hour component by calling the method with the "H", or "HH" custom format specifiers. - - - -## Examples - The following example displays the hour component of a object in three different ways: - -- By retrieving the value of the property. - -- By calling the method with the "H" format specifier. - -- By calling the method with the "HH" format specifier. - - :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Date/Properties.cs" id="Snippet6"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Properties/fs/Properties.fs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Properties/vb/Properties.vb" id="Snippet6"::: - + property is not affected by the value of the property. + + You can also create a string representation of a object's hour component by calling the method with the "H", or "HH" custom format specifiers. + + + +## Examples + The following example displays the hour component of a object in three different ways: + +- By retrieving the value of the property. + +- By calling the method with the "H" format specifier. + +- By calling the method with the "HH" format specifier. + + :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Date/Properties.cs" id="Snippet6"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Properties/fs/Properties.fs" id="Snippet6"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Properties/vb/Properties.vb" id="Snippet6"::: + ]]>
@@ -2869,28 +2869,28 @@ In .NET 6 and earlier versions, the `seconds` parameter is rounded to the neares Gets a value that represents the local date and time of the current object. The local date and time of the current object. - property converts the current object's date and time to the local system's date and time. The conversion is a two-step operation: - -1. The property converts the current object's time to Coordinated Universal Time (UTC). - -2. The property then converts UTC to local time. - - There are no invalid times and ambiguous times are mapped to the local zone's standard time. (However, the conversion can create an anomaly: if a value that is derived from the local computer reflects an ambiguous date and time, that value can be converted to UTC and then back to a local time that differs from the original time.) The property applies any adjustment rules in the local time zone when it performs this conversion. - - This property returns both the date and the time component of a object, which makes it useful for to conversion. In addition to performing any necessary time conversion, this property differs from the property by setting the value of the property of the returned object to . - - - -## Examples - The following example illustrates several conversions of values to local times in the U.S. Pacific Standard Time zone. Note that the last three times are all ambiguous; the property maps all of them to a single date and time in the Pacific Standard Time zone. - - :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Date/Properties.cs" id="Snippet7"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Properties/fs/Properties.fs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Properties/vb/Properties.vb" id="Snippet7"::: - + property converts the current object's date and time to the local system's date and time. The conversion is a two-step operation: + +1. The property converts the current object's time to Coordinated Universal Time (UTC). + +2. The property then converts UTC to local time. + + There are no invalid times and ambiguous times are mapped to the local zone's standard time. (However, the conversion can create an anomaly: if a value that is derived from the local computer reflects an ambiguous date and time, that value can be converted to UTC and then back to a local time that differs from the original time.) The property applies any adjustment rules in the local time zone when it performs this conversion. + + This property returns both the date and the time component of a object, which makes it useful for to conversion. In addition to performing any necessary time conversion, this property differs from the property by setting the value of the property of the returned object to . + + + +## Examples + The following example illustrates several conversions of values to local times in the U.S. Pacific Standard Time zone. Note that the last three times are all ambiguous; the property maps all of them to a single date and time in the Pacific Standard Time zone. + + :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Date/Properties.cs" id="Snippet7"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Properties/fs/Properties.fs" id="Snippet7"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Properties/vb/Properties.vb" id="Snippet7"::: + ]]> @@ -2936,15 +2936,15 @@ In .NET 6 and earlier versions, the `seconds` parameter is rounded to the neares Represents the greatest possible value of . This field is read-only. - property is used to determine whether the value of a new object or the value returned by an arithmetic operation is the same as or earlier than this maximum range value. If it is not, the method throws an . Any value is converted to Coordinated Universal Time (UTC) before the method compares it with . This means that a value whose date and time are close to the maximum range, but whose offset is negative, may throw an exception. For example, the value 12/31/9999 11:00 PM -02:00 is out of range because it is one hour later than when it is converted to UTC. - - Some calendars, such as the , support an upper date range that is earlier than . In these cases, trying to access in variable assignments or formatting and parsing operations can throw an . Instead of retrieving the value of , you can retrieve the value of the specified culture's latest valid date value from the property. - + property is used to determine whether the value of a new object or the value returned by an arithmetic operation is the same as or earlier than this maximum range value. If it is not, the method throws an . Any value is converted to Coordinated Universal Time (UTC) before the method compares it with . This means that a value whose date and time are close to the maximum range, but whose offset is negative, may throw an exception. For example, the value 12/31/9999 11:00 PM -02:00 is out of range because it is one hour later than when it is converted to UTC. + + Some calendars, such as the , support an upper date range that is earlier than . In these cases, trying to access in variable assignments or formatting and parsing operations can throw an . Instead of retrieving the value of , you can retrieve the value of the specified culture's latest valid date value from the property. + ]]> @@ -2978,14 +2978,14 @@ In .NET 6 and earlier versions, the `seconds` parameter is rounded to the neares Gets the microsecond component of the time represented by the current object. To be added. - or to accurately track the number of elapsed microseconds, - the precision of the time's microseconds component depends on the resolution of the system clock. - On Windows NT 3.5 and later, and Windows Vista operating systems, the clock's resolution is approximately 10000-15000 microseconds. - + or to accurately track the number of elapsed microseconds, + the precision of the time's microseconds component depends on the resolution of the system clock. + On Windows NT 3.5 and later, and Windows Vista operating systems, the clock's resolution is approximately 10000-15000 microseconds. + ]]> @@ -3031,22 +3031,22 @@ If you rely on properties such as or Gets the millisecond component of the time represented by the current object. The millisecond component of the current object, expressed as an integer between 0 and 999. - object's millisecond component by calling the method with the "fff" custom format specifier. - - If you rely on properties such as or to accurately track the number of elapsed milliseconds, the precision of the time's millisecond component depends on the resolution of the system clock. On Windows NT 3.5 and later, and Windows Vista operating systems, the clock's resolution is approximately 10-15 milliseconds. - - - -## Examples - The following example displays the number of milliseconds of a object by using a custom format specifier and by directly accessing the property. - - :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Date/Properties.cs" id="Snippet12"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Properties/fs/Properties.fs" id="Snippet12"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Properties/vb/Properties.vb" id="Snippet12"::: - + object's millisecond component by calling the method with the "fff" custom format specifier. + + If you rely on properties such as or to accurately track the number of elapsed milliseconds, the precision of the time's millisecond component depends on the resolution of the system clock. On Windows NT 3.5 and later, and Windows Vista operating systems, the clock's resolution is approximately 10-15 milliseconds. + + + +## Examples + The following example displays the number of milliseconds of a object by using a custom format specifier and by directly accessing the property. + + :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Date/Properties.cs" id="Snippet12"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Properties/fs/Properties.fs" id="Snippet12"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Properties/vb/Properties.vb" id="Snippet12"::: + ]]>
@@ -3092,28 +3092,28 @@ If you rely on properties such as or Gets the minute component of the time represented by the current object. The minute component of the current object, expressed as an integer between 0 and 59. - property is not affected by the value of the property. - - You can also create a string representation of a object's minute component by calling the method with the "m", or "mm" custom format specifiers. - - - -## Examples - The following example displays the minute component of a object in three different ways: - -- By retrieving the value of the property. - -- By calling the method with the "m" format specifier. - -- By calling the method with the "mm" format specifier. - - :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Date/Properties.cs" id="Snippet8"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Properties/fs/Properties.fs" id="Snippet8"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Properties/vb/Properties.vb" id="Snippet8"::: - + property is not affected by the value of the property. + + You can also create a string representation of a object's minute component by calling the method with the "m", or "mm" custom format specifiers. + + + +## Examples + The following example displays the minute component of a object in three different ways: + +- By retrieving the value of the property. + +- By calling the method with the "m" format specifier. + +- By calling the method with the "mm" format specifier. + + :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Date/Properties.cs" id="Snippet8"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Properties/fs/Properties.fs" id="Snippet8"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Properties/vb/Properties.vb" id="Snippet8"::: + ]]> @@ -3158,13 +3158,13 @@ If you rely on properties such as or Represents the earliest possible value. This field is read-only. - property is used to determine whether the value of a new object or the value returned by an arithmetic operation is the same as or later than this minimum range value. If it is not, the method throws an . Any value is converted to Coordinated Universal Time (UTC) before the method performs the comparison with . This means that a value whose date and time are close to the minimum range, but whose offset is positive, may throw an exception. For example, the value 1/1/0001 1:00:00 AM +02:00 is out of range because it is one hour earlier than when it is converted to UTC. - + property is used to determine whether the value of a new object or the value returned by an arithmetic operation is the same as or later than this minimum range value. If it is not, the method throws an . Any value is converted to Coordinated Universal Time (UTC) before the method performs the comparison with . This means that a value whose date and time are close to the minimum range, but whose offset is positive, may throw an exception. For example, the value 1/1/0001 1:00:00 AM +02:00 is out of range because it is one hour earlier than when it is converted to UTC. + ]]> @@ -3211,28 +3211,28 @@ If you rely on properties such as or Gets the month component of the date represented by the current object. The month component of the current object, expressed as an integer between 1 and 12. - property is not affected by the value of the property. - - You can also create a string representation of a object's month component by calling the method with the "M" or "MM" custom format specifiers. - - - -## Examples - The following example displays the month component of a value in three different ways: - -- By retrieving the value of the property. - -- By calling the method with the "M" format specifier. - -- By calling the method with the "MM" format specifier. - - :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Date/Properties.cs" id="Snippet9"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Properties/fs/Properties.fs" id="Snippet9"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Properties/vb/Properties.vb" id="Snippet9"::: - + property is not affected by the value of the property. + + You can also create a string representation of a object's month component by calling the method with the "M" or "MM" custom format specifiers. + + + +## Examples + The following example displays the month component of a value in three different ways: + +- By retrieving the value of the property. + +- By calling the method with the "M" format specifier. + +- By calling the method with the "MM" format specifier. + + :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Date/Properties.cs" id="Snippet9"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Properties/fs/Properties.fs" id="Snippet9"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Properties/vb/Properties.vb" id="Snippet9"::: + ]]> @@ -3264,14 +3264,14 @@ If you rely on properties such as or Gets the nanosecond component of the time represented by the current object. To be added. - or to accurately track the number of elapsed nanosecond, - the precision of the time's nanosecond component depends on the resolution of the system clock. - On Windows NT 3.5 and later, and Windows Vista operating systems, the clock's resolution is approximately 10000000-15000000 nanoseconds. - + or to accurately track the number of elapsed nanosecond, + the precision of the time's nanosecond component depends on the resolution of the system clock. + On Windows NT 3.5 and later, and Windows Vista operating systems, the clock's resolution is approximately 10000000-15000000 nanoseconds. + ]]> @@ -3317,26 +3317,26 @@ If you rely on properties such as or Gets a object that is set to the current date and time on the current computer, with the offset set to the local time's offset from Coordinated Universal Time (UTC). A object whose date and time is the current local time and whose offset is the local time zone's offset from Coordinated Universal Time (UTC). - property to retrieve the current date and time and displays it by using each of the [standard date and time format strings](/dotnet/standard/base-types/standard-date-and-time-format-strings) supported by the type. - - :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Now/now1.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.datetimeoffset.now/fs/now1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.datetimeoffset.now/vb/now1.vb" id="Snippet1"::: - - The following example uses the and properties to determine the resolution of the system clock. It displays the time only when the value of its millisecond component has changed. - - :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Date/Properties.cs" id="Snippet11"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Properties/fs/Properties.fs" id="Snippet11"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Properties/vb/Properties.vb" id="Snippet11"::: - + property to retrieve the current date and time and displays it by using each of the [standard date and time format strings](/dotnet/standard/base-types/standard-date-and-time-format-strings) supported by the type. + + :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Now/now1.cs" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.datetimeoffset.now/fs/now1.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.datetimeoffset.now/vb/now1.vb" id="Snippet1"::: + + The following example uses the and properties to determine the resolution of the system clock. It displays the time only when the value of its millisecond component has changed. + + :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Date/Properties.cs" id="Snippet11"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Properties/fs/Properties.fs" id="Snippet11"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Properties/vb/Properties.vb" id="Snippet11"::: + ]]> @@ -3383,22 +3383,22 @@ If you rely on properties such as or Gets the time's offset from Coordinated Universal Time (UTC). The difference between the current object's time value and Coordinated Universal Time (UTC). - property of the returned object can range from -14 hours to 14 hours. - - The value of the property is precise to the minute. - - - -## Examples - The following example uses the property to display the local time's difference from Coordinated Universal Time (UTC). - - :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Date/Properties.cs" id="Snippet13"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Properties/fs/Properties.fs" id="Snippet13"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Properties/vb/Properties.vb" id="Snippet13"::: - + property of the returned object can range from -14 hours to 14 hours. + + The value of the property is precise to the minute. + + + +## Examples + The following example uses the property to display the local time's difference from Coordinated Universal Time (UTC). + + :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Date/Properties.cs" id="Snippet13"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Properties/fs/Properties.fs" id="Snippet13"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Properties/vb/Properties.vb" id="Snippet13"::: + ]]> @@ -3457,23 +3457,23 @@ If you rely on properties such as or Adds a specified time interval to a object that has a specified date and time, and yields a object that has new a date and time. An object whose value is the sum of the values of and . - method defines the addition operation for values. It enables code such as the following: - - :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/op_Addition/Operators.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Operators/fs/Operators.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Operators/vb/Operators.vb" id="Snippet1"::: - - Languages that do not support custom operators and operator overloading can call the method instead. - + method defines the addition operation for values. It enables code such as the following: + + :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/op_Addition/Operators.cs" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Operators/fs/Operators.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Operators/vb/Operators.vb" id="Snippet1"::: + + Languages that do not support custom operators and operator overloading can call the method instead. + The equivalent method for this operator is .]]> - The resulting value is less than DateTimeOffset.MinValue. - - -or- - + The resulting value is less than DateTimeOffset.MinValue. + + -or- + The resulting value is greater than DateTimeOffset.MaxValue. Performing Arithmetic Operations with Dates and Times @@ -3527,23 +3527,23 @@ If you rely on properties such as or if both objects have the same value; otherwise, . - method defines the operation of the equality operator for objects. It enables code such as the following: - - :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/op_Addition/Operators.cs" id="Snippet2"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Operators/fs/Operators.fs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Operators/vb/Operators.vb" id="Snippet2"::: - - Before evaluating the `left` and `right` operands for equality, the operator converts both values to Coordinated Universal Time (UTC). The operation is equivalent to the following: - - :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Compare/Syntax.cs" id="Snippet4"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Syntax/fs/Syntax.fs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Syntax/vb/Syntax.vb" id="Snippet4"::: - - In other words, the method determines whether the two objects represent a single point in time. It directly compares neither dates and times nor offsets. To determine whether two objects represent the same time and have the same offset value, use the method. - + method defines the operation of the equality operator for objects. It enables code such as the following: + + :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/op_Addition/Operators.cs" id="Snippet2"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Operators/fs/Operators.fs" id="Snippet2"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Operators/vb/Operators.vb" id="Snippet2"::: + + Before evaluating the `left` and `right` operands for equality, the operator converts both values to Coordinated Universal Time (UTC). The operation is equivalent to the following: + + :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Compare/Syntax.cs" id="Snippet4"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Syntax/fs/Syntax.fs" id="Snippet4"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Syntax/vb/Syntax.vb" id="Snippet4"::: + + In other words, the method determines whether the two objects represent a single point in time. It directly compares neither dates and times nor offsets. To determine whether two objects represent the same time and have the same offset value, use the method. + The equivalent method for this operator is ]]> @@ -3597,25 +3597,25 @@ If you rely on properties such as or if the value of is later than the value of ; otherwise, . - method defines the operation of the greater than operator for objects. It enables code such as the following: - - :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/op_Addition/Operators.cs" id="Snippet3"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Operators/fs/Operators.fs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Operators/vb/Operators.vb" id="Snippet3"::: - - Languages that do not support custom operators can call the method instead. They can also call the method directly, as the following example shows. - - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Operators/vb/Operators.vb" id="Snippet4"::: - - Before evaluating the `left` and `right` operands, the operator converts both values to Coordinated Universal Time (UTC). The operation is equivalent to the following: - - :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Compare/Syntax.cs" id="Snippet5"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Syntax/fs/Syntax.fs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Syntax/vb/Syntax.vb" id="Snippet5"::: - + method defines the operation of the greater than operator for objects. It enables code such as the following: + + :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/op_Addition/Operators.cs" id="Snippet3"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Operators/fs/Operators.fs" id="Snippet3"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Operators/vb/Operators.vb" id="Snippet3"::: + + Languages that do not support custom operators can call the method instead. They can also call the method directly, as the following example shows. + + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Operators/vb/Operators.vb" id="Snippet4"::: + + Before evaluating the `left` and `right` operands, the operator converts both values to Coordinated Universal Time (UTC). The operation is equivalent to the following: + + :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Compare/Syntax.cs" id="Snippet5"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Syntax/fs/Syntax.fs" id="Snippet5"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Syntax/vb/Syntax.vb" id="Snippet5"::: + The equivalent method for this operator is ]]> @@ -3669,25 +3669,25 @@ If you rely on properties such as or if the value of is the same as or later than the value of ; otherwise, . - method defines the operation of the greater than or equal to operator for objects. It enables code such as the following: - - :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/op_Addition/Operators.cs" id="Snippet5"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Operators/fs/Operators.fs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Operators/vb/Operators.vb" id="Snippet5"::: - - Languages that do not support custom operators can call the method instead. Some languages can also call the method directly, as the following example shows. - - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Operators/vb/Operators.vb" id="Snippet6"::: - - Before evaluating the `left` and `right` operands, the operator converts both values to Coordinated Universal Time (UTC). The operation is equivalent to the following: - - :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Compare/Syntax.cs" id="Snippet6"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Syntax/fs/Syntax.fs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Syntax/vb/Syntax.vb" id="Snippet6"::: - + method defines the operation of the greater than or equal to operator for objects. It enables code such as the following: + + :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/op_Addition/Operators.cs" id="Snippet5"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Operators/fs/Operators.fs" id="Snippet5"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Operators/vb/Operators.vb" id="Snippet5"::: + + Languages that do not support custom operators can call the method instead. Some languages can also call the method directly, as the following example shows. + + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Operators/vb/Operators.vb" id="Snippet6"::: + + Before evaluating the `left` and `right` operands, the operator converts both values to Coordinated Universal Time (UTC). The operation is equivalent to the following: + + :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Compare/Syntax.cs" id="Snippet6"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Syntax/fs/Syntax.fs" id="Snippet6"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Syntax/vb/Syntax.vb" id="Snippet6"::: + The equivalent method for this operator is ]]> @@ -3738,27 +3738,27 @@ If you rely on properties such as or Defines an implicit conversion of a object to a object. The converted object. - method enables the compiler to automatically convert a object to a object without an explicit casting operator (in C#) or a call to a conversion function (in Visual Basic). It defines a widening conversion that does not involve data loss and does not throw an . The method makes code such as the following possible: - - :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/op_Addition/Operators.cs" id="Snippet7"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Operators/fs/Operators.fs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Operators/vb/Operators.vb" id="Snippet7"::: - - This method is equivalent to the constructor. The offset of the resulting object depends on the value of the property of the `dateTime` parameter: - -- If the value of the property is , the date and time of the object is set equal to `dateTime`, and its property is set equal to 0. - -- If the value of the property is or , the date and time of the object is set equal to `dateTime`, and its property is set equal to the offset of the local system's current time zone. - + method enables the compiler to automatically convert a object to a object without an explicit casting operator (in C#) or a call to a conversion function (in Visual Basic). It defines a widening conversion that does not involve data loss and does not throw an . The method makes code such as the following possible: + + :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/op_Addition/Operators.cs" id="Snippet7"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Operators/fs/Operators.fs" id="Snippet7"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Operators/vb/Operators.vb" id="Snippet7"::: + + This method is equivalent to the constructor. The offset of the resulting object depends on the value of the property of the `dateTime` parameter: + +- If the value of the property is , the date and time of the object is set equal to `dateTime`, and its property is set equal to 0. + +- If the value of the property is or , the date and time of the object is set equal to `dateTime`, and its property is set equal to the offset of the local system's current time zone. + The equivalent method for this operator is ]]> - The Coordinated Universal Time (UTC) date and time that results from applying the offset is earlier than DateTimeOffset.MinValue. - - -or- - + The Coordinated Universal Time (UTC) date and time that results from applying the offset is earlier than DateTimeOffset.MinValue. + + -or- + The UTC date and time that results from applying the offset is later than DateTimeOffset.MaxValue. @@ -3810,27 +3810,27 @@ If you rely on properties such as or if and do not have the same value; otherwise, . - method defines the operation of the inequality operator for objects. It always returns the opposite result from . The method enables code such as the following: - - :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/op_Addition/Operators.cs" id="Snippet8"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Operators/fs/Operators.fs" id="Snippet8"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Operators/vb/Operators.vb" id="Snippet8"::: - - Before evaluating the `left` and `right` operands for equality, the operator converts both values to Coordinated Universal Time (UTC). The operation is equivalent to the following: - - :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Compare/Syntax.cs" id="Snippet4"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Syntax/fs/Syntax.fs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Syntax/vb/Syntax.vb" id="Snippet4"::: - - In other words, the method determines whether the two objects represent different points in time. It directly compares neither dates and times nor offsets. - - Languages that do not support custom operators can call the method instead. In addition, some languages can also call the method directly, as the following example shows. - - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Operators/vb/Operators.vb" id="Snippet9"::: - + method defines the operation of the inequality operator for objects. It always returns the opposite result from . The method enables code such as the following: + + :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/op_Addition/Operators.cs" id="Snippet8"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Operators/fs/Operators.fs" id="Snippet8"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Operators/vb/Operators.vb" id="Snippet8"::: + + Before evaluating the `left` and `right` operands for equality, the operator converts both values to Coordinated Universal Time (UTC). The operation is equivalent to the following: + + :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Compare/Syntax.cs" id="Snippet4"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Syntax/fs/Syntax.fs" id="Snippet4"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Syntax/vb/Syntax.vb" id="Snippet4"::: + + In other words, the method determines whether the two objects represent different points in time. It directly compares neither dates and times nor offsets. + + Languages that do not support custom operators can call the method instead. In addition, some languages can also call the method directly, as the following example shows. + + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Operators/vb/Operators.vb" id="Snippet9"::: + The equivalent method for this operator is ]]> @@ -3883,25 +3883,25 @@ If you rely on properties such as or if the value of is earlier than the value of ; otherwise, . - method defines the operation of the less than operator for objects. It enables code such as the following: - - :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/op_Addition/Operators.cs" id="Snippet10"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Operators/fs/Operators.fs" id="Snippet10"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Operators/vb/Operators.vb" id="Snippet10"::: - - Before evaluating the `left` and `right` operands, the operator converts both operands to Coordinated Universal Time (UTC). The operation is equivalent to the following: - - :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Compare/Syntax.cs" id="Snippet8"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Syntax/fs/Syntax.fs" id="Snippet8"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Syntax/vb/Syntax.vb" id="Snippet8"::: - - Languages that do not support custom operators can call the method instead. In addition, some languages can also call the method directly, as the following example shows. - - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Operators/vb/Operators.vb" id="Snippet11"::: - + method defines the operation of the less than operator for objects. It enables code such as the following: + + :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/op_Addition/Operators.cs" id="Snippet10"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Operators/fs/Operators.fs" id="Snippet10"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Operators/vb/Operators.vb" id="Snippet10"::: + + Before evaluating the `left` and `right` operands, the operator converts both operands to Coordinated Universal Time (UTC). The operation is equivalent to the following: + + :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Compare/Syntax.cs" id="Snippet8"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Syntax/fs/Syntax.fs" id="Snippet8"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Syntax/vb/Syntax.vb" id="Snippet8"::: + + Languages that do not support custom operators can call the method instead. In addition, some languages can also call the method directly, as the following example shows. + + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Operators/vb/Operators.vb" id="Snippet11"::: + The equivalent method for this operator is ]]> @@ -3955,25 +3955,25 @@ If you rely on properties such as or if the value of is earlier than the value of ; otherwise, . - method defines the operation of the less than or equal to operator for objects. It enables code such as the following: - - :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/op_Addition/Operators.cs" id="Snippet12"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Operators/fs/Operators.fs" id="Snippet12"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Operators/vb/Operators.vb" id="Snippet12"::: - - Languages that do not support custom operators can call the method instead. Some languages can also call the method directly, as the following example shows. - - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Operators/vb/Operators.vb" id="Snippet13"::: - - Before evaluating the `left` and `right` operands, the operator converts both values to Coordinated Universal Time (UTC). The operation is equivalent to the following: - - :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Compare/Syntax.cs" id="Snippet9"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Syntax/fs/Syntax.fs" id="Snippet9"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Syntax/vb/Syntax.vb" id="Snippet9"::: - + method defines the operation of the less than or equal to operator for objects. It enables code such as the following: + + :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/op_Addition/Operators.cs" id="Snippet12"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Operators/fs/Operators.fs" id="Snippet12"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Operators/vb/Operators.vb" id="Snippet12"::: + + Languages that do not support custom operators can call the method instead. Some languages can also call the method directly, as the following example shows. + + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Operators/vb/Operators.vb" id="Snippet13"::: + + Before evaluating the `left` and `right` operands, the operator converts both values to Coordinated Universal Time (UTC). The operation is equivalent to the following: + + :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Compare/Syntax.cs" id="Snippet9"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Syntax/fs/Syntax.fs" id="Snippet9"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Syntax/vb/Syntax.vb" id="Snippet9"::: + The equivalent method for this operator is ]]> @@ -4039,17 +4039,17 @@ If you rely on properties such as or Subtracts one object from another and yields a time interval. An object that represents the difference between and . - method defines the subtraction operation for objects. It enables code such as the following: - - :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/op_Addition/Operators.cs" id="Snippet14"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Operators/fs/Operators.fs" id="Snippet14"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Operators/vb/Operators.vb" id="Snippet14"::: - - Languages that do not support custom operators and operator overloading can call the method instead. - + method defines the subtraction operation for objects. It enables code such as the following: + + :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/op_Addition/Operators.cs" id="Snippet14"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Operators/fs/Operators.fs" id="Snippet14"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Operators/vb/Operators.vb" id="Snippet14"::: + + Languages that do not support custom operators and operator overloading can call the method instead. + The equivalent method for this operator is .]]> @@ -4110,17 +4110,17 @@ If you rely on properties such as or Subtracts a specified time interval from a specified date and time, and yields a new date and time. An object that is equal to the value of minus . - method defines the subtraction operation for objects. It enables code such as the following: - - :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/op_Addition/Operators.cs" id="Snippet15"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Operators/fs/Operators.fs" id="Snippet15"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Operators/vb/Operators.vb" id="Snippet15"::: - - Languages that do not support custom operators and operator overloading can call the method instead. - + method defines the subtraction operation for objects. It enables code such as the following: + + :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/op_Addition/Operators.cs" id="Snippet15"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Operators/fs/Operators.fs" id="Snippet15"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Operators/vb/Operators.vb" id="Snippet15"::: + + Languages that do not support custom operators and operator overloading can call the method instead. + The equivalent method for this operator is .]]> The resulting value is less than DateTimeOffset.MinValue or greater than DateTimeOffset.MaxValue. @@ -4140,10 +4140,10 @@ If you rely on properties such as or Converts the specified string representation of a date and time to its equivalent. - @@ -4203,40 +4203,40 @@ If you rely on properties such as or Converts the specified string representation of a date, time, and offset to its equivalent. An object that is equivalent to the date and time that is contained in . - parses a string with three elements that can appear in any order and are delimited by white space. These three elements are as shown in the following table. - -|Element|Example| -|-------------|-------------| -|\|"2/10/2007"| -|\ The offset is greater than 14 hours or less than -14 hours. is . - does not contain a valid string representation of a date and time. - - -or- - + does not contain a valid string representation of a date and time. + + -or- + contains the string representation of an offset value without a date or time. @@ -4353,48 +4353,48 @@ If you rely on properties such as or Converts the specified string representation of a date and time to its equivalent using the specified culture-specific format information. An object that is equivalent to the date and time that is contained in , as specified by . - |"2/10/2007"| -|\ The offset is greater than 14 hours or less than -14 hours. is . - does not contain a valid string representation of a date and time. - - -or- - + does not contain a valid string representation of a date and time. + + -or- + contains the string representation of an offset value without a date or time. @@ -4516,78 +4516,78 @@ If you rely on properties such as or Converts the specified string representation of a date and time to its equivalent using the specified culture-specific format information and formatting style. An object that is equivalent to the date and time that is contained in as specified by and . - |"2/10/2007"| -|\ - The offset is greater than 14 hours or less than -14 hours. - - -or- - - is not a valid value. - - -or- - - includes an unsupported value. - - -or- - + The offset is greater than 14 hours or less than -14 hours. + + -or- + + is not a valid value. + + -or- + + includes an unsupported value. + + -or- + includes values that cannot be used together. is . - does not contain a valid string representation of a date and time. - - -or- - + does not contain a valid string representation of a date and time. + + -or- + contains the string representation of an offset value without a date or time. @@ -4604,10 +4604,10 @@ If you rely on properties such as or Converts the specified string representation of a date and time to its equivalent. The format of the string representation must match a specified format exactly. - @@ -4681,61 +4681,61 @@ If you rely on properties such as or Converts the specified string representation of a date and time to its equivalent using the specified format and culture-specific format information. The format of the string representation must match the specified format exactly. An object that is equivalent to the date and time that is contained in as specified by and . - method parses the string representation of a date, which must be in the format defined by the `format` parameter. It also requires that the \, \ The offset is greater than 14 hours or less than -14 hours. - is . - - -or- - + is . + + -or- + is . - is an empty string (""). - - -or- - - does not contain a valid string representation of a date and time. - - -or- - - is an empty string. - - -or- - + is an empty string (""). + + -or- + + does not contain a valid string representation of a date and time. + + -or- + + is an empty string. + + -or- + The hour component and the AM/PM designator in do not agree. In the .NET Framework 4, the method throws a if the string to be parsed contains an hour component and an AM/PM designator that are not in agreement. In the .NET Framework 3.5 and earlier versions, the AM/PM designator is ignored. @@ -4801,38 +4801,38 @@ The following example parses an array of strings that are expected to conform to Converts a character span that represents a date and time to its equivalent using the specified format, culture-specific format information, and style. The format of the date and time representation must match the specified format exactly. An object that is equivalent to the date and time that is contained in the parameter, as specified by the , , and parameters. - , \ - The offset is greater than 14 hours or less than -14 hours. --or- -The parameter includes an unsupported value. --or- + The offset is greater than 14 hours or less than -14 hours. +-or- +The parameter includes an unsupported value. +-or- The parameter contains values that cannot be used together. - is an empty character span. - -or- - does not contain a valid string representation of a date and time. - -or- - is an empty character span. - -or- + is an empty character span. + -or- + does not contain a valid string representation of a date and time. + -or- + is an empty character span. + -or- The hour component and the AM/PM designator in do not agree. @@ -4896,55 +4896,55 @@ The parameter contains equivalent using the specified formats, culture-specific format information, and style. The format of the date and time representation must match one of the specified formats exactly. An object that is equivalent to the date and time that is contained in the parameter, as specified by the , , and parameters. - . Aside from comparing `input` to multiple formatting patterns, this overload behaves identically to the method. - - The `formats` parameter is a string array whose elements contain either a single standard format specifier or one or more custom format specifiers that define the possible pattern of the `input` parameter. When the method is called, `input` must match one of these patterns. For details about valid formatting codes, see [Standard Date and Time Format Strings](/dotnet/standard/base-types/standard-date-and-time-format-strings) and [Custom Date and Time Format Strings](/dotnet/standard/base-types/custom-date-and-time-format-strings). If the matched element in `formats` includes the `z`, `zz`, or `zzz` custom format specifiers to indicate that an offset must be present in `input`, that offset must include either a negative sign or a positive sign. If the sign is missing, the method throws a . - -> [!IMPORTANT] -> Using the `formats` parameter of this overload to specify multiple formats can help reduce the frustration many users experience when they enter dates and times. In particular, the ability to define multiple input patterns enables an application to handle date and time representations that can either include or lack leading zeros in months, days, hours, minutes, and seconds. - - If the matched element in `formats` requires that `input` contain a date but not a time, the resulting object is assigned a time of midnight (0:00:00). If the matched element in `formats` requires that `input` contain a time but not a date, the resulting object is assigned the current date on the local system. If the matched element in `formats` does not require that `input` contain an offset, the offset of the resulting object depends on the value of the `styles` parameter. If `styles` includes , the offset of the local time zone is assigned to the object. If `styles` includes , the Coordinated Universal Time (UTC) offset, or +00:00, is assigned to the object. If neither value is specified, the offset of the local time zone is used. - - The particular date and time symbols and strings used in `input` are defined by the `formatProvider` parameter. The same is true for the precise format of `input`, if the matching element of `formats` is a standard format specifier string. The `formatProvider` parameter can be either of the following: - -- A object that represents the culture based on which `input` is interpreted. The object returned by the property defines the symbols and formatting in `input`. - -- A object that defines the format of date and time data. - - If `formatprovider` is `null`, the object that corresponds to the current culture is used. - - The `styles` parameter defines whether white space is permitted in the input string, indicates how strings without an explicit offset component are parsed, and supports UTC conversion as part of the parsing operation. All members of the enumeration are supported except . The following table lists the effect of each supported member. - -|`DateTimeStyles` member|Behavior| -|-----------------------------|--------------| -||Parses `input` and, if necessary, converts it to UTC. It is equivalent to parsing a string, and then calling the method of the returned object.| -||If the matched element in `formats` does not require that `input` contain an offset value, the returned object is given the offset of the local time zone. This is the default value.| -||If the matched element in `formats` does not require that `input` contain an offset value, the returned object is given the UTC offset (+00:00).| -||Allows `input` to include inner white space not specified by `format`. Extra white space can appear between date and time components and within individual components (except the offset), and is ignored when parsing the string.| -||Allows `input` to include leading spaces not specified by `formats`. These are ignored when parsing the string.| -||Allows `input` to include trailing spaces not specified by `formats`. These are ignored when parsing the string.| -||Allows `input` to include leading, trailing, and inner spaces not specified by `formats`. All extra white-space characters not specified in the matched element in `formats` are ignored when parsing the string.| -||Indicates that additional white space is not permitted in `input`. White space must appear exactly as specified in a particular element of `formats` for a match to occur. This is the default behavior.| -||Has no effect because the structure does not include a `Kind` property.| - + . Aside from comparing `input` to multiple formatting patterns, this overload behaves identically to the method. + + The `formats` parameter is a string array whose elements contain either a single standard format specifier or one or more custom format specifiers that define the possible pattern of the `input` parameter. When the method is called, `input` must match one of these patterns. For details about valid formatting codes, see [Standard Date and Time Format Strings](/dotnet/standard/base-types/standard-date-and-time-format-strings) and [Custom Date and Time Format Strings](/dotnet/standard/base-types/custom-date-and-time-format-strings). If the matched element in `formats` includes the `z`, `zz`, or `zzz` custom format specifiers to indicate that an offset must be present in `input`, that offset must include either a negative sign or a positive sign. If the sign is missing, the method throws a . + +> [!IMPORTANT] +> Using the `formats` parameter of this overload to specify multiple formats can help reduce the frustration many users experience when they enter dates and times. In particular, the ability to define multiple input patterns enables an application to handle date and time representations that can either include or lack leading zeros in months, days, hours, minutes, and seconds. + + If the matched element in `formats` requires that `input` contain a date but not a time, the resulting object is assigned a time of midnight (0:00:00). If the matched element in `formats` requires that `input` contain a time but not a date, the resulting object is assigned the current date on the local system. If the matched element in `formats` does not require that `input` contain an offset, the offset of the resulting object depends on the value of the `styles` parameter. If `styles` includes , the offset of the local time zone is assigned to the object. If `styles` includes , the Coordinated Universal Time (UTC) offset, or +00:00, is assigned to the object. If neither value is specified, the offset of the local time zone is used. + + The particular date and time symbols and strings used in `input` are defined by the `formatProvider` parameter. The same is true for the precise format of `input`, if the matching element of `formats` is a standard format specifier string. The `formatProvider` parameter can be either of the following: + +- A object that represents the culture based on which `input` is interpreted. The object returned by the property defines the symbols and formatting in `input`. + +- A object that defines the format of date and time data. + + If `formatprovider` is `null`, the object that corresponds to the current culture is used. + + The `styles` parameter defines whether white space is permitted in the input string, indicates how strings without an explicit offset component are parsed, and supports UTC conversion as part of the parsing operation. All members of the enumeration are supported except . The following table lists the effect of each supported member. + +|`DateTimeStyles` member|Behavior| +|-----------------------------|--------------| +||Parses `input` and, if necessary, converts it to UTC. It is equivalent to parsing a string, and then calling the method of the returned object.| +||If the matched element in `formats` does not require that `input` contain an offset value, the returned object is given the offset of the local time zone. This is the default value.| +||If the matched element in `formats` does not require that `input` contain an offset value, the returned object is given the UTC offset (+00:00).| +||Allows `input` to include inner white space not specified by `format`. Extra white space can appear between date and time components and within individual components (except the offset), and is ignored when parsing the string.| +||Allows `input` to include leading spaces not specified by `formats`. These are ignored when parsing the string.| +||Allows `input` to include trailing spaces not specified by `formats`. These are ignored when parsing the string.| +||Allows `input` to include leading, trailing, and inner spaces not specified by `formats`. All extra white-space characters not specified in the matched element in `formats` are ignored when parsing the string.| +||Indicates that additional white space is not permitted in `input`. White space must appear exactly as specified in a particular element of `formats` for a match to occur. This is the default behavior.| +||Has no effect because the structure does not include a `Kind` property.| + ]]> - The offset is greater than 14 hours or less than -14 hours. --or- - includes an unsupported value. --or- + The offset is greater than 14 hours or less than -14 hours. +-or- + includes an unsupported value. +-or- The parameter contains values that cannot be used together. - is an empty character span. --or- - does not contain a valid string representation of a date and time. --or- -No element of contains a valid format specifier. --or- + is an empty character span. +-or- + does not contain a valid string representation of a date and time. +-or- +No element of contains a valid format specifier. +-or- The hour component and the AM/PM designator in do not agree. @@ -5020,89 +5020,89 @@ The hour component and the AM/PM designator in do not Converts the specified string representation of a date and time to its equivalent using the specified format, culture-specific format information, and style. The format of the string representation must match the specified format exactly. An object that is equivalent to the date and time that is contained in the parameter, as specified by the , , and parameters. - method parses the string representation of a date, which must be in the format defined by the `format` parameter. It also requires that the \, \ - The offset is greater than 14 hours or less than -14 hours. - - -or- - - The parameter includes an unsupported value. - - -or- - + The offset is greater than 14 hours or less than -14 hours. + + -or- + + The parameter includes an unsupported value. + + -or- + The parameter contains values that cannot be used together. - is . - - -or- - + is . + + -or- + is . - is an empty string (""). - - -or- - - does not contain a valid string representation of a date and time. - - -or- - - is an empty string. - - -or- - + is an empty string (""). + + -or- + + does not contain a valid string representation of a date and time. + + -or- + + is an empty string. + + -or- + The hour component and the AM/PM designator in do not agree. In the .NET Framework 4, the method throws a if the string to be parsed contains an hour component and an AM/PM designator that are not in agreement. In the .NET Framework 3.5 and earlier versions, the AM/PM designator is ignored. @@ -5184,75 +5184,75 @@ Strings that do not specify a UTC offset are assumed to have the offset of the l Converts the specified string representation of a date and time to its equivalent using the specified formats, culture-specific format information, and style. The format of the string representation must match one of the specified formats exactly. An object that is equivalent to the date and time that is contained in the parameter, as specified by the , , and parameters. - method parses the string representation of a date that matches any one of the patterns assigned to the `formats` parameter. If the `input` string does not match any one of these patterns with any of the variations defined by the `styles` parameter, the method throws a . Aside from comparing `input` to multiple formatting patterns, this overload behaves identically to the method. - - The `formats` parameter is a string array whose elements contain either a single standard format specifier or one or more custom format specifiers that define the possible pattern of the `input` parameter. When the method is called, `input` must match one of these patterns. For details about valid formatting codes, see [Standard Date and Time Format Strings](/dotnet/standard/base-types/standard-date-and-time-format-strings) and [Custom Date and Time Format Strings](/dotnet/standard/base-types/custom-date-and-time-format-strings). If the matched element in `formats` includes the `z`, `zz`, or `zzz` custom format specifiers to indicate that an offset must be present in `input`, that offset must include either a negative sign or a positive sign. If the sign is missing, the method throws a . - -> [!IMPORTANT] -> Using the `formats` parameter of this overload to specify multiple formats can help reduce the frustration many users experience when they enter dates and times. In particular, the ability to define multiple input patterns enables an application to handle date and time representations that can either include or lack leading zeros in months, days, hours, minutes, and seconds. The example provides an illustration of this. - - If the matched element in `formats` requires that `input` contain a date but not a time, the resulting object is assigned a time of midnight (0:00:00). If the matched element in `formats` requires that `input` contain a time but not a date, the resulting object is assigned the current date on the local system. If the matched element in `formats` does not require that `input` contain an offset, the offset of the resulting object depends on the value of the `styles` parameter. If `styles` includes , the offset of the local time zone is assigned to the object. If `styles` includes , the Coordinated Universal Time (UTC) offset, or +00:00, is assigned to the object. If neither value is specified, the offset of the local time zone is used. - - The particular date and time symbols and strings used in `input` are defined by the `formatProvider` parameter. The same is true for the precise format of `input`, if the matching element of `formats` is a standard format specifier string. The `formatProvider` parameter can be either of the following: - -- A object that represents the culture based on which `input` is interpreted. The object returned by the property defines the symbols and formatting in `input`. - -- A object that defines the format of date and time data. - - If `formatprovider` is `null`, the object that corresponds to the current culture is used. - - The `styles` parameter defines whether white space is permitted in the input string, indicates how strings without an explicit offset component are parsed, and supports UTC conversion as part of the parsing operation. All members of the enumeration are supported except . The following table lists the effect of each supported member. - -|`DateTimeStyles` member|Behavior| -|-----------------------------|--------------| -||Parses `input` and, if necessary, converts it to UTC. It is equivalent to parsing a string, and then calling the method of the returned object.| -||If the matched element in `formats` does not require that `input` contain an offset value, the returned object is given the offset of the local time zone. This is the default value.| -||If the matched element in `formats` does not require that `input` contain an offset value, the returned object is given the UTC offset (+00:00).| -||Allows `input` to include inner white space not specified by `format`. Extra white space can appear between date and time components and within individual components (except the offset), and is ignored when parsing the string.| -||Allows `input` to include leading spaces not specified by `formats`. These are ignored when parsing the string.| -||Allows `input` to include trailing spaces not specified by `formats`. These are ignored when parsing the string.| -||Allows `input` to include leading, trailing, and inner spaces not specified by `formats`. All extra white-space characters not specified in the matched element in `formats` are ignored when parsing the string.| -||Indicates that additional white space is not permitted in `input`. White space must appear exactly as specified in a particular element of `formats` for a match to occur. This is the default behavior.| -||Has no effect because the structure does not include a `Kind` property.| - - - -## Examples - The following example defines multiple input formats for the string representation of a date and time and offset value, and then passes the string that is entered by the user to the method. - - :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/ParseExact/ParseExact.cs" id="Snippet3"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.ParseExact/fs/ParseExact.fs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.ParseExact/vb/ParseExact.vb" id="Snippet3"::: - + method parses the string representation of a date that matches any one of the patterns assigned to the `formats` parameter. If the `input` string does not match any one of these patterns with any of the variations defined by the `styles` parameter, the method throws a . Aside from comparing `input` to multiple formatting patterns, this overload behaves identically to the method. + + The `formats` parameter is a string array whose elements contain either a single standard format specifier or one or more custom format specifiers that define the possible pattern of the `input` parameter. When the method is called, `input` must match one of these patterns. For details about valid formatting codes, see [Standard Date and Time Format Strings](/dotnet/standard/base-types/standard-date-and-time-format-strings) and [Custom Date and Time Format Strings](/dotnet/standard/base-types/custom-date-and-time-format-strings). If the matched element in `formats` includes the `z`, `zz`, or `zzz` custom format specifiers to indicate that an offset must be present in `input`, that offset must include either a negative sign or a positive sign. If the sign is missing, the method throws a . + +> [!IMPORTANT] +> Using the `formats` parameter of this overload to specify multiple formats can help reduce the frustration many users experience when they enter dates and times. In particular, the ability to define multiple input patterns enables an application to handle date and time representations that can either include or lack leading zeros in months, days, hours, minutes, and seconds. The example provides an illustration of this. + + If the matched element in `formats` requires that `input` contain a date but not a time, the resulting object is assigned a time of midnight (0:00:00). If the matched element in `formats` requires that `input` contain a time but not a date, the resulting object is assigned the current date on the local system. If the matched element in `formats` does not require that `input` contain an offset, the offset of the resulting object depends on the value of the `styles` parameter. If `styles` includes , the offset of the local time zone is assigned to the object. If `styles` includes , the Coordinated Universal Time (UTC) offset, or +00:00, is assigned to the object. If neither value is specified, the offset of the local time zone is used. + + The particular date and time symbols and strings used in `input` are defined by the `formatProvider` parameter. The same is true for the precise format of `input`, if the matching element of `formats` is a standard format specifier string. The `formatProvider` parameter can be either of the following: + +- A object that represents the culture based on which `input` is interpreted. The object returned by the property defines the symbols and formatting in `input`. + +- A object that defines the format of date and time data. + + If `formatprovider` is `null`, the object that corresponds to the current culture is used. + + The `styles` parameter defines whether white space is permitted in the input string, indicates how strings without an explicit offset component are parsed, and supports UTC conversion as part of the parsing operation. All members of the enumeration are supported except . The following table lists the effect of each supported member. + +|`DateTimeStyles` member|Behavior| +|-----------------------------|--------------| +||Parses `input` and, if necessary, converts it to UTC. It is equivalent to parsing a string, and then calling the method of the returned object.| +||If the matched element in `formats` does not require that `input` contain an offset value, the returned object is given the offset of the local time zone. This is the default value.| +||If the matched element in `formats` does not require that `input` contain an offset value, the returned object is given the UTC offset (+00:00).| +||Allows `input` to include inner white space not specified by `format`. Extra white space can appear between date and time components and within individual components (except the offset), and is ignored when parsing the string.| +||Allows `input` to include leading spaces not specified by `formats`. These are ignored when parsing the string.| +||Allows `input` to include trailing spaces not specified by `formats`. These are ignored when parsing the string.| +||Allows `input` to include leading, trailing, and inner spaces not specified by `formats`. All extra white-space characters not specified in the matched element in `formats` are ignored when parsing the string.| +||Indicates that additional white space is not permitted in `input`. White space must appear exactly as specified in a particular element of `formats` for a match to occur. This is the default behavior.| +||Has no effect because the structure does not include a `Kind` property.| + + + +## Examples + The following example defines multiple input formats for the string representation of a date and time and offset value, and then passes the string that is entered by the user to the method. + + :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/ParseExact/ParseExact.cs" id="Snippet3"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.ParseExact/fs/ParseExact.fs" id="Snippet3"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.ParseExact/vb/ParseExact.vb" id="Snippet3"::: + ]]> - The offset is greater than 14 hours or less than -14 hours. - - -or- - - includes an unsupported value. - - -or- - + The offset is greater than 14 hours or less than -14 hours. + + -or- + + includes an unsupported value. + + -or- + The parameter contains values that cannot be used together. is . - is an empty string (""). - - -or- - - does not contain a valid string representation of a date and time. - - -or- - - No element of contains a valid format specifier. - - -or- - + is an empty string (""). + + -or- + + does not contain a valid string representation of a date and time. + + -or- + + No element of contains a valid format specifier. + + -or- + The hour component and the AM/PM designator in do not agree. In the .NET Framework 4, the method throws a if the string to be parsed contains an hour component and an AM/PM designator that are not in agreement. In the .NET Framework 3.5 and earlier versions, the AM/PM designator is ignored. @@ -5303,28 +5303,28 @@ Strings that do not specify a UTC offset are assumed to have the offset of the l Gets the second component of the clock time represented by the current object. The second component of the object, expressed as an integer value between 0 and 59. - property is not affected by the value of the property. - - You can also create a string representation of a object's second component by calling the method with the "s", or "ss" custom format specifiers. - - - -## Examples - The following example displays the second component of a object in three different ways: - -- By retrieving the value of the property. - -- By calling the method with the "s" format specifier. - -- By calling the method with the "ss" format specifier. - - :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Date/Properties.cs" id="Snippet14"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Properties/fs/Properties.fs" id="Snippet14"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Properties/vb/Properties.vb" id="Snippet14"::: - + property is not affected by the value of the property. + + You can also create a string representation of a object's second component by calling the method with the "s", or "ss" custom format specifiers. + + + +## Examples + The following example displays the second component of a object in three different ways: + +- By retrieving the value of the property. + +- By calling the method with the "s" format specifier. + +- By calling the method with the "ss" format specifier. + + :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Date/Properties.cs" id="Snippet14"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Properties/fs/Properties.fs" id="Snippet14"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Properties/vb/Properties.vb" id="Snippet14"::: + ]]> @@ -5387,25 +5387,25 @@ Strings that do not specify a UTC offset are assumed to have the offset of the l Subtracts a value that represents a specific date and time from the current object. An object that specifies the interval between the two objects. - objects to Coordinated Universal Time (UTC) before calculating the time interval that separates them. This removes any effect that different offsets from UTC may have on the comparison. - -> [!NOTE] -> For languages that support custom operators, you can also perform date and time subtraction by using the subtraction operator. For details, see the method. - - Because neither the current object nor the `value` parameter represent the date and time in a specific time zone, the method does not consider a particular time zone's adjustment rules when it subtracts dates and times. - - - -## Examples - The following example illustrates subtraction that uses the method. - - :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Add/Methods.cs" id="Snippet13"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Methods/fs/Methods.fs" id="Snippet13"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Methods/vb/Methods.vb" id="Snippet13"::: - + objects to Coordinated Universal Time (UTC) before calculating the time interval that separates them. This removes any effect that different offsets from UTC may have on the comparison. + +> [!NOTE] +> For languages that support custom operators, you can also perform date and time subtraction by using the subtraction operator. For details, see the method. + + Because neither the current object nor the `value` parameter represent the date and time in a specific time zone, the method does not consider a particular time zone's adjustment rules when it subtracts dates and times. + + + +## Examples + The following example illustrates subtraction that uses the method. + + :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Add/Methods.cs" id="Snippet13"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Methods/fs/Methods.fs" id="Snippet13"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Methods/vb/Methods.vb" id="Snippet13"::: + ]]> Performing Arithmetic Operations with Dates and Times @@ -5456,31 +5456,31 @@ Strings that do not specify a UTC offset are assumed to have the offset of the l Subtracts a specified time interval from the current object. An object that is equal to the date and time represented by the current object, minus the time interval represented by . - method to subtract more than one kind of time interval (days, hours, minutes, seconds, or milliseconds) in a single operation. Its behavior is identical to the method, which defines the subtraction operator. The structure also supports specialized addition methods (such as , , and ) that allow you to perform subtraction by assigning a negative value to the method parameter. - -> [!NOTE] -> This method returns a new object. It does not modify the value of the current object by subtracting `value` from its date and time. - - The method does not affect the value of the object's property. The returned object has the same offset as the original object. - - Because the current object does not represent the date and time in a specific time zone, the method does not consider a particular time zone's adjustment rules when it performs the subtraction. - -## Examples - The following example illustrates subtraction that uses the method. - - :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Add/Methods.cs" id="Snippet14"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Methods/fs/Methods.fs" id="Snippet14"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Methods/vb/Methods.vb" id="Snippet14"::: - + method to subtract more than one kind of time interval (days, hours, minutes, seconds, or milliseconds) in a single operation. Its behavior is identical to the method, which defines the subtraction operator. The structure also supports specialized addition methods (such as , , and ) that allow you to perform subtraction by assigning a negative value to the method parameter. + +> [!NOTE] +> This method returns a new object. It does not modify the value of the current object by subtracting `value` from its date and time. + + The method does not affect the value of the object's property. The returned object has the same offset as the original object. + + Because the current object does not represent the date and time in a specific time zone, the method does not consider a particular time zone's adjustment rules when it performs the subtraction. + +## Examples + The following example illustrates subtraction that uses the method. + + :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Add/Methods.cs" id="Snippet14"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Methods/fs/Methods.fs" id="Snippet14"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Methods/vb/Methods.vb" id="Snippet14"::: + ]]> - The resulting value is less than DateTimeOffset.MinValue. - - -or- - + The resulting value is less than DateTimeOffset.MinValue. + + -or- + The resulting value is greater than DateTimeOffset.MaxValue. Performing Arithmetic Operations with Dates and Times @@ -5531,24 +5531,24 @@ Strings that do not specify a UTC offset are assumed to have the offset of the l The object to compare with the current object. Compares the value of the current object with another object of the same type. - A 32-bit signed integer that indicates whether the current object is less than, equal to, or greater than . The return values of the method are interpreted as follows: - - Return Value - - Description - - Less than zero - - The current object is less than (earlier than) . - - Zero - - The current object is equal to (the same point in time as) . - - Greater than zero - - The current object is greater than (later than) . - + A 32-bit signed integer that indicates whether the current object is less than, equal to, or greater than . The return values of the method are interpreted as follows: + + Return Value + + Description + + Less than zero + + The current object is less than (earlier than) . + + Zero + + The current object is equal to (the same point in time as) . + + Greater than zero + + The current object is greater than (later than) . + To be added. @@ -5590,7 +5590,7 @@ Strings that do not specify a UTC offset are assumed to have the offset of the l System.Void - + The object that initiated the callback. The functionality for this parameter is not currently implemented. @@ -5641,8 +5641,8 @@ Strings that do not specify a UTC offset are assumed to have the offset of the l System.Void - - + + The object to populate with data. @@ -5693,24 +5693,24 @@ Strings that do not specify a UTC offset are assumed to have the offset of the l Gets the number of ticks that represents the date and time of the current object in clock time. The number of ticks in the object's clock time. - property is not affected by the value of the property. - - The value of the property represents the number of 100-nanosecond intervals that have elapsed since 12:00:00 midnight on January 1, 0001 (the value of ). It does not include ticks that would be added by leap seconds. A nanosecond is one billionth of a second; there are ten million ticks in a second. The value of the property ranges from `DateTimeOffset.MinValue.Ticks` to `DateTimeOffset.MaxValue.Ticks`. - - You can assign the number of ticks to a object by using the constructor overload. - - - -## Examples - The following example initializes a object by approximating the number of ticks in the date July 1, 2008 1:23:07. It then displays the date and the number of ticks represented by that date to the console. - - :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Date/Properties.cs" id="Snippet15"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Properties/fs/Properties.fs" id="Snippet15"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Properties/vb/Properties.vb" id="Snippet15"::: - + property is not affected by the value of the property. + + The value of the property represents the number of 100-nanosecond intervals that have elapsed since 12:00:00 midnight on January 1, 0001 (the value of ). It does not include ticks that would be added by leap seconds. A nanosecond is one billionth of a second; there are ten million ticks in a second. The value of the property ranges from `DateTimeOffset.MinValue.Ticks` to `DateTimeOffset.MaxValue.Ticks`. + + You can assign the number of ticks to a object by using the constructor overload. + + + +## Examples + The following example initializes a object by approximating the number of ticks in the date July 1, 2008 1:23:07. It then displays the date and the number of ticks represented by that date to the console. + + :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Date/Properties.cs" id="Snippet15"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Properties/fs/Properties.fs" id="Snippet15"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Properties/vb/Properties.vb" id="Snippet15"::: + ]]> @@ -5757,22 +5757,22 @@ Strings that do not specify a UTC offset are assumed to have the offset of the l Gets the time of day for the current object. The time interval of the current date that has elapsed since midnight. - property is not affected by the value of the property. - - The property returns the time component of a object in the form of a object. It is equivalent to the property. - - - -## Examples - The following example uses the property to extract the time and display it to the console. - - :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Date/Properties.cs" id="Snippet16"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Properties/fs/Properties.fs" id="Snippet16"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Properties/vb/Properties.vb" id="Snippet16"::: - + property is not affected by the value of the property. + + The property returns the time component of a object in the form of a object. It is equivalent to the property. + + + +## Examples + The following example uses the property to extract the time and display it to the console. + + :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Date/Properties.cs" id="Snippet16"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Properties/fs/Properties.fs" id="Snippet16"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Properties/vb/Properties.vb" id="Snippet16"::: + ]]> @@ -5819,21 +5819,21 @@ Strings that do not specify a UTC offset are assumed to have the offset of the l Converts the value of the current object to a Windows file time. The value of the current object, expressed as a Windows file time. - method converts the current object's date and time to UTC before it performs the conversion. In other words, calling the method is equivalent to the following method call: - -```csharp -this.ToUtcDateTime().ToFileTime(); -``` - -```vb -Me.ToUtcDateTime().ToFileTime() -``` - + method converts the current object's date and time to UTC before it performs the conversion. In other words, calling the method is equivalent to the following method call: + +```csharp +this.ToUtcDateTime().ToFileTime(); +``` + +```vb +Me.ToUtcDateTime().ToFileTime() +``` + ]]> The resulting file time would represent a date and time before midnight on January 1, 1601 C.E. Coordinated Universal Time (UTC). @@ -5882,24 +5882,24 @@ Me.ToUtcDateTime().ToFileTime() Converts the current object to a object that represents the local time. An object that represents the date and time of the current object converted to local time. - object's date and time to Coordinated Universal Time (UTC) by subtracting the offset from the time. It then converts the UTC date and time to local time by adding the local time zone offset. In doing this, it takes account of any adjustment rules for the local time zone. - - Both the value of the current object and the value of the object returned by the method call represent the same point in time. That is, if both are passed to the method, the method will return `true`. - - If the conversion causes a time that is out of range of the type, the method returns a object that has the date and time set to either or and the offset set to the local time zone offset. - - - -## Examples - The following example uses the method to convert a value to local time in the Pacific Standard Time zone. It also illustrates the method's support for the local time zone's adjustment rules. - - :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Add/Methods.cs" id="Snippet15"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Methods/fs/Methods.fs" id="Snippet15"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Methods/vb/Methods.vb" id="Snippet15"::: - + object's date and time to Coordinated Universal Time (UTC) by subtracting the offset from the time. It then converts the UTC date and time to local time by adding the local time zone offset. In doing this, it takes account of any adjustment rules for the local time zone. + + Both the value of the current object and the value of the object returned by the method call represent the same point in time. That is, if both are passed to the method, the method will return `true`. + + If the conversion causes a time that is out of range of the type, the method returns a object that has the date and time set to either or and the offset set to the local time zone offset. + + + +## Examples + The following example uses the method to convert a value to local time in the Pacific Standard Time zone. It also illustrates the method's support for the local time zone's adjustment rules. + + :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Add/Methods.cs" id="Snippet15"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Methods/fs/Methods.fs" id="Snippet15"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Methods/vb/Methods.vb" id="Snippet15"::: + ]]> @@ -5950,32 +5950,32 @@ Me.ToUtcDateTime().ToFileTime() Converts the value of the current object to the date and time specified by an offset value. An object that is equal to the original object (that is, their methods return identical points in time) but whose property is set to . - method is an alternative to calling the method. It can be useful for performing simple conversions from one time zone to another when the time zones' offsets from Coordinated Universal Time (UTC) are known. However, because neither the original object nor the new object returned by the method call are unambiguously related to a particular time zone, the method does not apply any time zone adjustment rules in the conversion. - - - -## Examples - The following example illustrates how to use the method to convert a object to a object with a different offset. - - :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/ToOffset/ToOffset.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.ToOffset/fs/ToOffset.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.ToOffset/vb/ToOffset.vb" id="Snippet1"::: - + method is an alternative to calling the method. It can be useful for performing simple conversions from one time zone to another when the time zones' offsets from Coordinated Universal Time (UTC) are known. However, because neither the original object nor the new object returned by the method call are unambiguously related to a particular time zone, the method does not apply any time zone adjustment rules in the conversion. + + + +## Examples + The following example illustrates how to use the method to convert a object to a object with a different offset. + + :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/ToOffset/ToOffset.cs" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.ToOffset/fs/ToOffset.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.ToOffset/vb/ToOffset.vb" id="Snippet1"::: + ]]> - The resulting object has a value earlier than DateTimeOffset.MinValue. - - -or- - + The resulting object has a value earlier than DateTimeOffset.MinValue. + + -or- + The resulting object has a value later than DateTimeOffset.MaxValue. - is less than -14 hours. - - -or- - + is less than -14 hours. + + -or- + is greater than 14 hours. @@ -5990,10 +5990,10 @@ Me.ToUtcDateTime().ToFileTime() Converts the value of the current object to its equivalent string representation. - @@ -6049,30 +6049,30 @@ Me.ToUtcDateTime().ToFileTime() Converts the value of the current object to its equivalent string representation. A string representation of a object that includes the offset appended at the end of the string. - method, except that it includes a space followed by the offset appended at the end of the string. In other words, it formats output using the short date pattern, the long time pattern, and the `zzz` custom format string, with each element separated from the previous element by a space. For example, if returns a value of 1/12/2008 6:15:50 PM, returns a value of 1/12/2008 6:15:50 PM -08:00 for a time that is eight hours behind Coordinated Universal Time (UTC). - - This method uses formatting information derived from the current culture. For more information, see . Other overloads of the method enable you to specify the culture whose formatting to use, and to define the output pattern of the value. - - - -## Examples - The following example illustrates calls to the method and displays its output on a system whose current culture is en-us. - - :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/ToString/ToString.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.ToString/fs/ToString.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.ToString/vb/ToString.vb" id="Snippet1"::: - + method, except that it includes a space followed by the offset appended at the end of the string. In other words, it formats output using the short date pattern, the long time pattern, and the `zzz` custom format string, with each element separated from the previous element by a space. For example, if returns a value of 1/12/2008 6:15:50 PM, returns a value of 1/12/2008 6:15:50 PM -08:00 for a time that is eight hours behind Coordinated Universal Time (UTC). + + This method uses formatting information derived from the current culture. For more information, see . Other overloads of the method enable you to specify the culture whose formatting to use, and to define the output pattern of the value. + + + +## Examples + The following example illustrates calls to the method and displays its output on a system whose current culture is en-us. + + :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/ToString/ToString.cs" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.ToString/fs/ToString.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.ToString/vb/ToString.vb" id="Snippet1"::: + ]]> The date and time is outside the range of dates supported by the calendar used by the current culture. - The method returns the string representation of the date and time in the calendar used by the current culture. If the value of the current instance is earlier than or later than , the method throws an . The following example provides an illustration. It attempts to format a date that is outside the range of the class when the current culture is Arabic (Syria). - - :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/ToString/datetimeoffset.tostring.argumentoutofrangeexception2.cs" id="Snippet2"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.datetimeoffset.tostring.argumentoutofrangeexception/fs/datetimeoffset.tostring.argumentoutofrangeexception2.fs" id="Snippet2"::: + The method returns the string representation of the date and time in the calendar used by the current culture. If the value of the current instance is earlier than or later than , the method throws an . The following example provides an illustration. It attempts to format a date that is outside the range of the class when the current culture is Arabic (Syria). + + :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/ToString/datetimeoffset.tostring.argumentoutofrangeexception2.cs" id="Snippet2"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.datetimeoffset.tostring.argumentoutofrangeexception/fs/datetimeoffset.tostring.argumentoutofrangeexception2.fs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.datetimeoffset.tostring.argumentoutofrangeexception/vb/datetimeoffset.tostring.argumentoutofrangeexception2.vb" id="Snippet2"::: @@ -6140,36 +6140,36 @@ Me.ToUtcDateTime().ToFileTime() Converts the value of the current object to its equivalent string representation using the specified culture-specific formatting information. A string representation of the value of the current object, as specified by . - method, except that it includes a space followed by the offset appended at the end of the string. In other words, it formats output using the short date pattern, the long time pattern, and the `zzz` custom format string, with each element separated from the previous element by a space. - - The format of these three elements is defined by the `formatProvider` parameter. The `formatProvider` parameter can be either of the following: - -- A object that represents the culture whose formatting conventions are applied to the returned string. The object returned by the property defines the formatting of the returned string. - -- A object that defines the format of date and time data. - - If `formatProvider` is `null`, the object associated with the current culture is used (see ). - - - -## Examples - The following example displays a object using objects that represent the invariant culture, as well as four other cultures. - - :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/ToString/ToString.cs" interactive="try-dotnet-method" id="Snippet2"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.ToString/fs/ToString.fs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.ToString/vb/ToString.vb" id="Snippet2"::: - + method, except that it includes a space followed by the offset appended at the end of the string. In other words, it formats output using the short date pattern, the long time pattern, and the `zzz` custom format string, with each element separated from the previous element by a space. + + The format of these three elements is defined by the `formatProvider` parameter. The `formatProvider` parameter can be either of the following: + +- A object that represents the culture whose formatting conventions are applied to the returned string. The object returned by the property defines the formatting of the returned string. + +- A object that defines the format of date and time data. + + If `formatProvider` is `null`, the object associated with the current culture is used (see ). + + + +## Examples + The following example displays a object using objects that represent the invariant culture, as well as four other cultures. + + :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/ToString/ToString.cs" interactive="try-dotnet-method" id="Snippet2"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.ToString/fs/ToString.fs" id="Snippet2"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.ToString/vb/ToString.vb" id="Snippet2"::: + ]]> The date and time is outside the range of dates supported by the calendar used by . - The method returns the string representation of the date and time in the calendar used by the culture represented by the parameter. Its calendar is defined by the property. If the value of the current instance is earlier than or later than , the method throws an . The following example provides an illustration. It attempts to format a date that is outside the range of the class. - - :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/ToString/datetimeoffset.tostring.argumentoutofrangeexception1.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.datetimeoffset.tostring.argumentoutofrangeexception/fs/datetimeoffset.tostring.argumentoutofrangeexception1.fs" id="Snippet1"::: + The method returns the string representation of the date and time in the calendar used by the culture represented by the parameter. Its calendar is defined by the property. If the value of the current instance is earlier than or later than , the method throws an . The following example provides an illustration. It attempts to format a date that is outside the range of the class. + + :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/ToString/datetimeoffset.tostring.argumentoutofrangeexception1.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.datetimeoffset.tostring.argumentoutofrangeexception/fs/datetimeoffset.tostring.argumentoutofrangeexception1.fs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.datetimeoffset.tostring.argumentoutofrangeexception/vb/datetimeoffset.tostring.argumentoutofrangeexception1.vb" id="Snippet1"::: @@ -6241,46 +6241,46 @@ Me.ToUtcDateTime().ToFileTime() Converts the value of the current object to its equivalent string representation using the specified format. A string representation of the value of the current object, as specified by . - value is output using the default format. - - The following table shows the exact operation of certain format specifiers when used with , which differs from their behavior when used with . - -|Existing format specifier|New behavior| -|-------------------------------|------------------| -|"K"|Designed to round-trip a date and time. With , maps to "zzz" (the offset is always displayed with hours and minutes). Note that "K" is a custom format specifier; it cannot appear as the single character in `format`.| -|"U"|Not supported.| -|"r"|Converts the object to Coordinated Universal Time (UTC) and outputs it using the custom format string `ddd, dd MMM yyyy HH:mm:ss GMT`.| -|"u"|Converts the object to UTC and outputs it using the format `yyyy-MM-dd HH:mm:ssZ`.| - - The remaining standard date and time format specifiers behave the same with the method as they do with the method. - - This method uses formatting information derived from the current culture. For more information, see . - - - -## Examples - The following example displays a object to the console using each of the standard date and time format specifiers. The output is formatted by using the en-us culture. - - :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/ToString/ToString.cs" id="Snippet3"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.ToString/fs/ToString.fs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.ToString/vb/ToString.vb" id="Snippet3"::: - + value is output using the default format. + + The following table shows the exact operation of certain format specifiers when used with , which differs from their behavior when used with . + +|Existing format specifier|New behavior| +|-------------------------------|------------------| +|"K"|Designed to round-trip a date and time. With , maps to "zzz" (the offset is always displayed with hours and minutes). Note that "K" is a custom format specifier; it cannot appear as the single character in `format`.| +|"U"|Not supported.| +|"r"|Converts the object to Coordinated Universal Time (UTC) and outputs it using the custom format string `ddd, dd MMM yyyy HH:mm:ss GMT`.| +|"u"|Converts the object to UTC and outputs it using the format `yyyy-MM-dd HH:mm:ssZ`.| + + The remaining standard date and time format specifiers behave the same with the method as they do with the method. + + This method uses formatting information derived from the current culture. For more information, see . + + + +## Examples + The following example displays a object to the console using each of the standard date and time format specifiers. The output is formatted by using the en-us culture. + + :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/ToString/ToString.cs" id="Snippet3"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.ToString/fs/ToString.fs" id="Snippet3"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.ToString/vb/ToString.vb" id="Snippet3"::: + ]]> - The length of is one, and it is not one of the standard format specifier characters defined for . - - -or- - + The length of is one, and it is not one of the standard format specifier characters defined for . + + -or- + does not contain a valid custom format pattern. The date and time is outside the range of dates supported by the calendar used by the current culture. - The method returns the string representation of the date and time in the calendar used by the current culture. If the value of the current instance is earlier than or later than , the method throws an . The following example provides an illustration. It attempts to format a date that is outside the range of the class when the current culture is Hebrew (Israel). - - :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/ToString/datetimeoffset.tostring.argumentoutofrangeexception3.cs" interactive="try-dotnet" id="Snippet3"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.datetimeoffset.tostring.argumentoutofrangeexception/fs/datetimeoffset.tostring.argumentoutofrangeexception3.fs" id="Snippet3"::: + The method returns the string representation of the date and time in the calendar used by the current culture. If the value of the current instance is earlier than or later than , the method throws an . The following example provides an illustration. It attempts to format a date that is outside the range of the class when the current culture is Hebrew (Israel). + + :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/ToString/datetimeoffset.tostring.argumentoutofrangeexception3.cs" interactive="try-dotnet" id="Snippet3"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.datetimeoffset.tostring.argumentoutofrangeexception/fs/datetimeoffset.tostring.argumentoutofrangeexception3.fs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.datetimeoffset.tostring.argumentoutofrangeexception/vb/datetimeoffset.tostring.argumentoutofrangeexception3.vb" id="Snippet3"::: Standard Date and Time Format Strings @@ -6355,52 +6355,52 @@ Me.ToUtcDateTime().ToFileTime() Converts the value of the current object to its equivalent string representation using the specified format and culture-specific format information. A string representation of the value of the current object, as specified by and . - object is output using the default format. - - The following table shows the exact operation of certain format specifiers when used with , which differs from their behavior when used with . - -|Existing format specifier|New behavior| -|-------------------------------|------------------| -|"K"|Designed to round-trip a date and time. With , maps to "zzz" (the offset is always displayed with hours and minutes). Note that "K" is a custom format specifier; it cannot appear as the single character in `format`.| -|"U"|Not supported.| -|"r"|Converts the object to Coordinated Universal Time (UTC) and outputs it using the custom format string `ddd, dd MMM yyyy HH:mm:ss GMT`.| -|"u"|Converts the value to UTC and outputs it using the format `yyyy-MM-dd HH:mm:ssZ`.| - - The remaining standard date and time format specifiers behave the same with the method as they do with the method. - - The pattern that corresponds to standard format specifiers, as well as the symbols and names of date and time components, is defined by the `formatProvider` parameter. The `formatProvider` parameter can be either of the following: - -- A object that represents the culture whose formatting is used in `input`. The object returned by the property defines the formatting used in `input`. - -- A object that defines the format of date and time data. - - If `formatProvider` is `null`, the object associated with the current culture is used (see ). - - - -## Examples - The following example uses the method to display a object using a custom format string for several different cultures. - - :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/ToString/ToString.cs" interactive="try-dotnet-method" id="Snippet4"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.ToString/fs/ToString.fs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.ToString/vb/ToString.vb" id="Snippet4"::: - + object is output using the default format. + + The following table shows the exact operation of certain format specifiers when used with , which differs from their behavior when used with . + +|Existing format specifier|New behavior| +|-------------------------------|------------------| +|"K"|Designed to round-trip a date and time. With , maps to "zzz" (the offset is always displayed with hours and minutes). Note that "K" is a custom format specifier; it cannot appear as the single character in `format`.| +|"U"|Not supported.| +|"r"|Converts the object to Coordinated Universal Time (UTC) and outputs it using the custom format string `ddd, dd MMM yyyy HH:mm:ss GMT`.| +|"u"|Converts the value to UTC and outputs it using the format `yyyy-MM-dd HH:mm:ssZ`.| + + The remaining standard date and time format specifiers behave the same with the method as they do with the method. + + The pattern that corresponds to standard format specifiers, as well as the symbols and names of date and time components, is defined by the `formatProvider` parameter. The `formatProvider` parameter can be either of the following: + +- A object that represents the culture whose formatting is used in `input`. The object returned by the property defines the formatting used in `input`. + +- A object that defines the format of date and time data. + + If `formatProvider` is `null`, the object associated with the current culture is used (see ). + + + +## Examples + The following example uses the method to display a object using a custom format string for several different cultures. + + :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/ToString/ToString.cs" interactive="try-dotnet-method" id="Snippet4"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.ToString/fs/ToString.fs" id="Snippet4"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.ToString/vb/ToString.vb" id="Snippet4"::: + ]]> - The length of is one, and it is not one of the standard format specifier characters defined for . - - -or- - + The length of is one, and it is not one of the standard format specifier characters defined for . + + -or- + does not contain a valid custom format pattern. The date and time is outside the range of dates supported by the calendar used by . - The method returns the string representation of the date and time in the calendar used by the parameter. Its calendar is defined by the property. If the value of the current instance is earlier than or later than , the method throws an . The following example provides an illustration. It attempts to format a date that is outside the range of the class. - - :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/ToString/datetimeoffset.tostring.argumentoutofrangeexception4.cs" id="Snippet4"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.datetimeoffset.tostring.argumentoutofrangeexception/fs/datetimeoffset.tostring.argumentoutofrangeexception4.fs" id="Snippet4"::: + The method returns the string representation of the date and time in the calendar used by the parameter. Its calendar is defined by the property. If the value of the current instance is earlier than or later than , the method throws an . The following example provides an illustration. It attempts to format a date that is outside the range of the class. + + :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/ToString/datetimeoffset.tostring.argumentoutofrangeexception4.cs" id="Snippet4"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.datetimeoffset.tostring.argumentoutofrangeexception/fs/datetimeoffset.tostring.argumentoutofrangeexception4.fs" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.datetimeoffset.tostring.argumentoutofrangeexception/vb/datetimeoffset.tostring.argumentoutofrangeexception4.vb" id="Snippet4"::: Standard Date and Time Format Strings @@ -6479,22 +6479,22 @@ Me.ToUtcDateTime().ToFileTime() Converts the current object to a value that represents the Coordinated Universal Time (UTC). An object that represents the date and time of the current object converted to Coordinated Universal Time (UTC). - object whose property is set to zero. - - Both the value of the current object and the value of the object returned by the method call represent the same point in time. That is, if both are passed to the method, the method will return `true`. - - - -## Examples - The following example calls the method to convert a local time and several other times to Coordinated Universal Time (UTC). - - :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Add/Methods.cs" id="Snippet16"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Methods/fs/Methods.fs" id="Snippet16"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Methods/vb/Methods.vb" id="Snippet16"::: - + object whose property is set to zero. + + Both the value of the current object and the value of the object returned by the method call represent the same point in time. That is, if both are passed to the method, the method will return `true`. + + + +## Examples + The following example calls the method to convert a local time and several other times to Coordinated Universal Time (UTC). + + :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Add/Methods.cs" id="Snippet16"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Methods/fs/Methods.fs" id="Snippet16"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Methods/vb/Methods.vb" id="Snippet16"::: + ]]> @@ -6540,13 +6540,13 @@ Me.ToUtcDateTime().ToFileTime() Returns the number of milliseconds that have elapsed since 1970-01-01T00:00:00.000Z. The number of milliseconds that have elapsed since 1970-01-01T00:00:00.000Z. - @@ -6592,22 +6592,22 @@ Me.ToUtcDateTime().ToFileTime() Returns the number of seconds that have elapsed since 1970-01-01T00:00:00Z. The number of seconds that have elapsed since 1970-01-01T00:00:00Z. - method to return the Unix time of values that are equal to, shortly before, and shortly after 1970-01-01T00:00:00Z. - - :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/ToUnixTimeSeconds/tounixtimeseconds1.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.datetimeoffset.tounixtimeseconds/fs/tounixtimeseconds1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.datetimeoffset.tounixtimeseconds/vb/tounixtimeseconds1.vb" id="Snippet1"::: - + method to return the Unix time of values that are equal to, shortly before, and shortly after 1970-01-01T00:00:00Z. + + :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/ToUnixTimeSeconds/tounixtimeseconds1.cs" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.datetimeoffset.tounixtimeseconds/fs/tounixtimeseconds1.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.datetimeoffset.tounixtimeseconds/vb/tounixtimeseconds1.vb" id="Snippet1"::: + ]]> @@ -6744,10 +6744,10 @@ Me.ToUtcDateTime().ToFileTime() Converts a specified string representation of a date and time to its equivalent. - @@ -6858,30 +6858,30 @@ Me.ToUtcDateTime().ToFileTime() if the parameter is successfully converted; otherwise, . - method is like the method, except that it does not throw an exception if the conversion fails. It parses a string with three elements that can appear in any order and are delimited by white space. These three elements are shown in the following table. - -|Element|Example| -|-------------|-------------| -|\|"2/10/2007"| -|\ @@ -7110,67 +7110,67 @@ Me.ToUtcDateTime().ToFileTime() if the parameter is successfully converted; otherwise, . - method is like the method, except that it does not throw an exception if the conversion fails. The method parses a string with three elements that can appear in any order and are delimited by white space. These three elements are shown in the following table. - -|Element|Example| -|-------------|-------------| -|\|"2/10/2007"| -|\ - includes an undefined value. - - -or- - - is not supported. - - -or- - + includes an undefined value. + + -or- + + is not supported. + + -or- + includes mutually exclusive values. @@ -7186,10 +7186,10 @@ Me.ToUtcDateTime().ToFileTime() Converts the specified string representation of a date and time to its equivalent. The format of the string representation must match a specified format exactly. - @@ -7253,45 +7253,45 @@ Me.ToUtcDateTime().ToFileTime() if the parameter is successfully converted; otherwise, . - method, except that this method does not throw an exception if the conversion fails. It parses the representation of a date and time that must exactly match the pattern specified by the `format` parameter. If `input` does not match this pattern, with some possible variations in white space defined by the `styles` parameter, the parsing operation fails and the method returns `false`. - -The `format` parameter is a character span that contains either a single standard format specifier or one or more custom format specifiers that define the required pattern of `input`. For details about valid formatting codes, see [Standard Date and Time Format Strings](/dotnet/standard/base-types/standard-date-and-time-format-strings) and [Custom Date and Time Format Strings](/dotnet/standard/base-types/custom-date-and-time-format-strings). If `format` includes the `z`, `zz`, or `zzz` custom format specifiers to indicate that an offset must be present in `input`, that offset must include either a negative sign or a positive sign. If the sign is missing, the parsing operation fails and the method returns `false`. - -If `format` requires that `input` contain a date but not a time, the resulting object is assigned a time of midnight (0:00:00). If `format` requires that `input` contain a time but not a date, the resulting object is assigned the current date on the local system. If `format` does not require that `input` contain an offset, the offset of the resulting object depends on the value of the `styles` parameter. If `styles` includes , the offset of the local time zone is assigned to the object. If `styles` includes , the Coordinated Universal Time (UTC) offset, or +00:00, is assigned to the object. If neither value is specified, the offset of the local time zone is used. - -The particular date and time symbols and strings used in `input` are defined by the `formatProvider` parameter. The same is true for the precise pattern of `input` if `format` is a standard format specifier string. The `formatProvider` parameter can be either of the following: - -- A object that represents the culture based on which `input` is interpreted. The object returned by the property defines the symbols and standard formats allowed in `input`. - -- A object that defines the format of date and time data. - - If `formatprovider` is `null`, the object that corresponds to the current culture is used. - - The `styles` parameter defines whether white space is allowed in the input string, indicates how strings without an explicit offset component are parsed, and supports UTC conversion as part of the parsing operation. All members of the enumeration are supported except . The following table lists the effect of each supported member. - -|`DateTimeStyles` member|Behavior| -|-----------------------------|--------------| -||Parses `input` and, if necessary, converts it to UTC. It is equivalent to parsing a date and time representation, and then calling the method of the returned object.| -||If `format` does not require that `input` contain an offset value, the returned object is given the offset of the local time zone. This is the default behavior.| -||If `format` does not require that `input` contain an offset value, the returned object is given the UTC offset (+00:00).| -||Allows `input` to include inner white space not specified by format. Extra white space can appear between date and time components and within individual components, other than the offset, and is ignored when parsing the string.| -||Allows `input` to include leading spaces not specified by `format`. These are ignored when parsing the string.| -||Allows `input` to include trailing spaces not specified by `format`. These are ignored when parsing the string.| -||Allows `input` to include leading, trailing, and inner spaces not specified by `format`. All extra white-space characters not specified in `format` are ignored when parsing the string.| -||Indicates that additional white space is not permitted in `input`. White space must appear exactly as specified in `format`. This is the default behavior.| -||Has no effect, because the structure does not include a `Kind` property.| - + method, except that this method does not throw an exception if the conversion fails. It parses the representation of a date and time that must exactly match the pattern specified by the `format` parameter. If `input` does not match this pattern, with some possible variations in white space defined by the `styles` parameter, the parsing operation fails and the method returns `false`. + +The `format` parameter is a character span that contains either a single standard format specifier or one or more custom format specifiers that define the required pattern of `input`. For details about valid formatting codes, see [Standard Date and Time Format Strings](/dotnet/standard/base-types/standard-date-and-time-format-strings) and [Custom Date and Time Format Strings](/dotnet/standard/base-types/custom-date-and-time-format-strings). If `format` includes the `z`, `zz`, or `zzz` custom format specifiers to indicate that an offset must be present in `input`, that offset must include either a negative sign or a positive sign. If the sign is missing, the parsing operation fails and the method returns `false`. + +If `format` requires that `input` contain a date but not a time, the resulting object is assigned a time of midnight (0:00:00). If `format` requires that `input` contain a time but not a date, the resulting object is assigned the current date on the local system. If `format` does not require that `input` contain an offset, the offset of the resulting object depends on the value of the `styles` parameter. If `styles` includes , the offset of the local time zone is assigned to the object. If `styles` includes , the Coordinated Universal Time (UTC) offset, or +00:00, is assigned to the object. If neither value is specified, the offset of the local time zone is used. + +The particular date and time symbols and strings used in `input` are defined by the `formatProvider` parameter. The same is true for the precise pattern of `input` if `format` is a standard format specifier string. The `formatProvider` parameter can be either of the following: + +- A object that represents the culture based on which `input` is interpreted. The object returned by the property defines the symbols and standard formats allowed in `input`. + +- A object that defines the format of date and time data. + + If `formatprovider` is `null`, the object that corresponds to the current culture is used. + + The `styles` parameter defines whether white space is allowed in the input string, indicates how strings without an explicit offset component are parsed, and supports UTC conversion as part of the parsing operation. All members of the enumeration are supported except . The following table lists the effect of each supported member. + +|`DateTimeStyles` member|Behavior| +|-----------------------------|--------------| +||Parses `input` and, if necessary, converts it to UTC. It is equivalent to parsing a date and time representation, and then calling the method of the returned object.| +||If `format` does not require that `input` contain an offset value, the returned object is given the offset of the local time zone. This is the default behavior.| +||If `format` does not require that `input` contain an offset value, the returned object is given the UTC offset (+00:00).| +||Allows `input` to include inner white space not specified by format. Extra white space can appear between date and time components and within individual components, other than the offset, and is ignored when parsing the string.| +||Allows `input` to include leading spaces not specified by `format`. These are ignored when parsing the string.| +||Allows `input` to include trailing spaces not specified by `format`. These are ignored when parsing the string.| +||Allows `input` to include leading, trailing, and inner spaces not specified by `format`. All extra white-space characters not specified in `format` are ignored when parsing the string.| +||Indicates that additional white space is not permitted in `input`. White space must appear exactly as specified in `format`. This is the default behavior.| +||Has no effect, because the structure does not include a `Kind` property.| + ]]> - includes an undefined value. --or- - is not supported. --or- + includes an undefined value. +-or- + is not supported. +-or- includes mutually exclusive values. @@ -7365,48 +7365,48 @@ The particular date and time symbols and strings used in `input` are defined by if the parameter is successfully converted; otherwise, . - method. - - The `formats` parameter is a string array whose elements contain either a single standard format specifier or one or more custom format specifiers that define the possible pattern of `input`. For details about valid formatting codes, see [Standard Date and Time Format Strings](/dotnet/standard/base-types/standard-date-and-time-format-strings) and [Custom Date and Time Format Strings](/dotnet/standard/base-types/custom-date-and-time-format-strings). If the matched element in `formats` includes the `z`, `zz`, or `zzz` custom format specifiers to indicate that an offset must be present in `input`, that offset must include either a negative sign or a positive sign. If the sign is missing, the parse operation fails and the method returns `false`. - -> [!IMPORTANT] -> Using the `formats` parameter of this overload to specify multiple formats can help reduce the frustration many users experience when they enter dates and times. In particular, the ability to define multiple input patterns enables an application to handle date and time representations that can either include or lack leading zeros in months, days, hours, minutes, and seconds. The example provides an illustration of this. - - If the matched element in `formats` requires that `input` contain a date but not a time, the resulting object is assigned a time of midnight (0:00:00). If the matched element in `formats` requires that input contain a time but not a date, the resulting object is assigned the current date on the local system. If the matched element in `formats` does not require that `input` contain an offset, the offset of the resulting object depends on the value of the `styles` parameter. If `styles` includes , the offset of the local time zone is assigned to the object. If `styles` includes , the Coordinated Universal Time (UTC) offset, or +00:00, is assigned to the object. If neither value is specified, the offset of the local time zone is used. - - The particular date and time symbols used in `input` are defined by the `formatProvider` parameter. The same is true for the precise pattern of `input` if the matching element of `formats` is a standard format specifier string. The `formatProvider` parameter can be either of the following: - -- A object that represents the culture based on which `input` is interpreted. The object returned by the property defines the symbols and formatting in `input`. - -- A object that defines the format of date and time data. - - If `formatprovider` is `null`, the object that corresponds to the current culture is used. - - The `styles` parameter defines whether white space is permitted in the input string, indicates how strings without an explicit offset component are parsed, and supports UTC conversion as part of the parsing operation. All members of the enumeration are supported except . The following table lists the effect of each supported member. - -|`DateTimeStyles` member|Behavior| -|-----------------------------|--------------| -||Parses `input` and, if necessary, converts it to UTC. It is equivalent to parsing a string, and then calling the method of the returned object.| -||If the matched element in `formats` does not require that `input` contain an offset value, the returned object is given the offset of the local time zone. This is the default value.| -||If the matched element in `formats` does not require that `input` contain an offset value, the returned object is given the UTC offset (+00:00).| -||Allows `input` to include inner white space not specified by the elements in `formats`. Extra white space can appear between date and time components and within individual components (except for the offset) and is ignored when parsing the string.| -||Allows `input` to include leading spaces not specified by the elements in `formats`. These are ignored when parsing the string.| -||Allows `input` to include trailing spaces not specified by the elements in `formats`. These are ignored when parsing the string.| -||Allows `input` to include leading, trailing, and inner spaces not specified by the elements in `formats`. All extra white-space characters not specified in the matched element in `formats` are ignored when parsing the string.| -||Indicates that additional white space is not permitted in `input`. White space must appear exactly as specified in a particular element in `formats` for a successful match to occur. This is the default behavior.| -||Has no effect because the structure does not include a `Kind` property.| - + method. + + The `formats` parameter is a string array whose elements contain either a single standard format specifier or one or more custom format specifiers that define the possible pattern of `input`. For details about valid formatting codes, see [Standard Date and Time Format Strings](/dotnet/standard/base-types/standard-date-and-time-format-strings) and [Custom Date and Time Format Strings](/dotnet/standard/base-types/custom-date-and-time-format-strings). If the matched element in `formats` includes the `z`, `zz`, or `zzz` custom format specifiers to indicate that an offset must be present in `input`, that offset must include either a negative sign or a positive sign. If the sign is missing, the parse operation fails and the method returns `false`. + +> [!IMPORTANT] +> Using the `formats` parameter of this overload to specify multiple formats can help reduce the frustration many users experience when they enter dates and times. In particular, the ability to define multiple input patterns enables an application to handle date and time representations that can either include or lack leading zeros in months, days, hours, minutes, and seconds. The example provides an illustration of this. + + If the matched element in `formats` requires that `input` contain a date but not a time, the resulting object is assigned a time of midnight (0:00:00). If the matched element in `formats` requires that input contain a time but not a date, the resulting object is assigned the current date on the local system. If the matched element in `formats` does not require that `input` contain an offset, the offset of the resulting object depends on the value of the `styles` parameter. If `styles` includes , the offset of the local time zone is assigned to the object. If `styles` includes , the Coordinated Universal Time (UTC) offset, or +00:00, is assigned to the object. If neither value is specified, the offset of the local time zone is used. + + The particular date and time symbols used in `input` are defined by the `formatProvider` parameter. The same is true for the precise pattern of `input` if the matching element of `formats` is a standard format specifier string. The `formatProvider` parameter can be either of the following: + +- A object that represents the culture based on which `input` is interpreted. The object returned by the property defines the symbols and formatting in `input`. + +- A object that defines the format of date and time data. + + If `formatprovider` is `null`, the object that corresponds to the current culture is used. + + The `styles` parameter defines whether white space is permitted in the input string, indicates how strings without an explicit offset component are parsed, and supports UTC conversion as part of the parsing operation. All members of the enumeration are supported except . The following table lists the effect of each supported member. + +|`DateTimeStyles` member|Behavior| +|-----------------------------|--------------| +||Parses `input` and, if necessary, converts it to UTC. It is equivalent to parsing a string, and then calling the method of the returned object.| +||If the matched element in `formats` does not require that `input` contain an offset value, the returned object is given the offset of the local time zone. This is the default value.| +||If the matched element in `formats` does not require that `input` contain an offset value, the returned object is given the UTC offset (+00:00).| +||Allows `input` to include inner white space not specified by the elements in `formats`. Extra white space can appear between date and time components and within individual components (except for the offset) and is ignored when parsing the string.| +||Allows `input` to include leading spaces not specified by the elements in `formats`. These are ignored when parsing the string.| +||Allows `input` to include trailing spaces not specified by the elements in `formats`. These are ignored when parsing the string.| +||Allows `input` to include leading, trailing, and inner spaces not specified by the elements in `formats`. All extra white-space characters not specified in the matched element in `formats` are ignored when parsing the string.| +||Indicates that additional white space is not permitted in `input`. White space must appear exactly as specified in a particular element in `formats` for a successful match to occur. This is the default behavior.| +||Has no effect because the structure does not include a `Kind` property.| + ]]> - includes an undefined value. --or- - is not supported. --or- + includes an undefined value. +-or- + is not supported. +-or- includes mutually exclusive values. @@ -7489,68 +7489,68 @@ This method parses the string representation of a date that matches any one of t if the parameter is successfully converted; otherwise, . - method is like the method, except that this method does not throw an exception if the conversion fails. It parses the string representation of a date and time that must exactly match the pattern specified by the `format` parameter. If the `input` string does not match this pattern, with some possible variations in white space defined by the `styles` parameter, the parsing operation fails and the method returns `false`. - - The `format` parameter is a string that contains either a single standard format specifier or one or more custom format specifiers that define the required pattern of `input`. For details about valid formatting codes, see [Standard Date and Time Format Strings](/dotnet/standard/base-types/standard-date-and-time-format-strings) and [Custom Date and Time Format Strings](/dotnet/standard/base-types/custom-date-and-time-format-strings). If `format` includes the `z`, `zz`, or `zzz` custom format specifiers to indicate that an offset must be present in `input`, that offset must include either a negative sign or a positive sign. If the sign is missing, the parsing operation fails and the method returns `false`. - - If `format` requires that `input` contain a date but not a time, the resulting object is assigned a time of midnight (0:00:00). If `format` requires that `input` contain a time but not a date, the resulting object is assigned the current date on the local system. If `format` does not require that `input` contain an offset, the offset of the resulting object depends on the value of the `styles` parameter. If `styles` includes , the offset of the local time zone is assigned to the object. If `styles` includes , the Coordinated Universal Time (UTC) offset, or +00:00, is assigned to the object. If neither value is specified, the offset of the local time zone is used. - - The particular date and time symbols and strings used in `input` are defined by the `formatProvider` parameter. The same is true for the precise pattern of `input` if `format` is a standard format specifier string. The `formatProvider` parameter can be either of the following: - -- A object that represents the culture based on which `input` is interpreted. The object returned by the property defines the symbols and standard formats allowed in `input`. - -- A object that defines the format of date and time data. - - If `formatprovider` is `null`, the object that corresponds to the current culture is used. - - The `styles` parameter defines whether white space is allowed in the input string, indicates how strings without an explicit offset component are parsed, and supports UTC conversion as part of the parsing operation. All members of the enumeration are supported except . The following table lists the effect of each supported member. - -|`DateTimeStyles` member|Behavior| -|-----------------------------|--------------| -||Parses `input` and, if necessary, converts it to UTC. It is equivalent to parsing a string, and then calling the method of the returned object.| -||If `format` does not require that `input` contain an offset value, the returned object is given the offset of the local time zone. This is the default behavior.| -||If `format` does not require that `input` contain an offset value, the returned object is given the UTC offset (+00:00).| -||Allows `input` to include inner white space not specified by format. Extra white space can appear between date and time components and within individual components, other than the offset, and is ignored when parsing the string.| -||Allows `input` to include leading spaces not specified by `format`. These are ignored when parsing the string.| -||Allows `input` to include trailing spaces not specified by `format`. These are ignored when parsing the string.| -||Allows `input` to include leading, trailing, and inner spaces not specified by `format`. All extra white-space characters not specified in `format` are ignored when parsing the string.| -||Indicates that additional white space is not permitted in `input`. White space must appear exactly as specified in `format`. This is the default behavior.| -||Has no effect, because the structure does not include a `Kind` property.| - -## Examples - - The following example uses the method with standard and custom format specifiers, the invariant culture, and various values to parse several date and time strings. - - :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/TryParseExact/TryParseExact.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.TryParseExact/fs/TryParseExact.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.TryParseExact/vb/TryParseExact.vb" id="Snippet1"::: - -The following example uses a variety of values to parse an array of strings that are expected to conform to [ISO 8601](/dotnet/standard/base-types/standard-date-and-time-format-strings#the-round-trip-o-o-format-specifier). As the output from the example shows, strings that are in the proper format fail to parse if: - -- they contain white space, and an appropriate flag (such as has not been supplied in the method call. - -- they contain date and time elements that are out of range. - -Strings that do not specify a UTC offset are assumed to have the offset of the local time zone (in this case, -07:00, which reflects the offset of the Pacific Daylight Time zone) unless the flag is supplied in the method call. In that case, they are assumed to be Universal Coordinated Time. - -:::code language="fsharp" source="~/snippets/fsharp/System/DateTimeOffset.TryParseExact/tryparseexacto8601-2.fs"::: -:::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/TryParseExact/tryparseexacto8601-2.cs"::: -:::code language="vb" source="~/snippets/visualbasic/api/system/datetimeoffset/tryparseexact/tryparseexacto8601-2.vb"::: - + method is like the method, except that this method does not throw an exception if the conversion fails. It parses the string representation of a date and time that must exactly match the pattern specified by the `format` parameter. If the `input` string does not match this pattern, with some possible variations in white space defined by the `styles` parameter, the parsing operation fails and the method returns `false`. + + The `format` parameter is a string that contains either a single standard format specifier or one or more custom format specifiers that define the required pattern of `input`. For details about valid formatting codes, see [Standard Date and Time Format Strings](/dotnet/standard/base-types/standard-date-and-time-format-strings) and [Custom Date and Time Format Strings](/dotnet/standard/base-types/custom-date-and-time-format-strings). If `format` includes the `z`, `zz`, or `zzz` custom format specifiers to indicate that an offset must be present in `input`, that offset must include either a negative sign or a positive sign. If the sign is missing, the parsing operation fails and the method returns `false`. + + If `format` requires that `input` contain a date but not a time, the resulting object is assigned a time of midnight (0:00:00). If `format` requires that `input` contain a time but not a date, the resulting object is assigned the current date on the local system. If `format` does not require that `input` contain an offset, the offset of the resulting object depends on the value of the `styles` parameter. If `styles` includes , the offset of the local time zone is assigned to the object. If `styles` includes , the Coordinated Universal Time (UTC) offset, or +00:00, is assigned to the object. If neither value is specified, the offset of the local time zone is used. + + The particular date and time symbols and strings used in `input` are defined by the `formatProvider` parameter. The same is true for the precise pattern of `input` if `format` is a standard format specifier string. The `formatProvider` parameter can be either of the following: + +- A object that represents the culture based on which `input` is interpreted. The object returned by the property defines the symbols and standard formats allowed in `input`. + +- A object that defines the format of date and time data. + + If `formatprovider` is `null`, the object that corresponds to the current culture is used. + + The `styles` parameter defines whether white space is allowed in the input string, indicates how strings without an explicit offset component are parsed, and supports UTC conversion as part of the parsing operation. All members of the enumeration are supported except . The following table lists the effect of each supported member. + +|`DateTimeStyles` member|Behavior| +|-----------------------------|--------------| +||Parses `input` and, if necessary, converts it to UTC. It is equivalent to parsing a string, and then calling the method of the returned object.| +||If `format` does not require that `input` contain an offset value, the returned object is given the offset of the local time zone. This is the default behavior.| +||If `format` does not require that `input` contain an offset value, the returned object is given the UTC offset (+00:00).| +||Allows `input` to include inner white space not specified by format. Extra white space can appear between date and time components and within individual components, other than the offset, and is ignored when parsing the string.| +||Allows `input` to include leading spaces not specified by `format`. These are ignored when parsing the string.| +||Allows `input` to include trailing spaces not specified by `format`. These are ignored when parsing the string.| +||Allows `input` to include leading, trailing, and inner spaces not specified by `format`. All extra white-space characters not specified in `format` are ignored when parsing the string.| +||Indicates that additional white space is not permitted in `input`. White space must appear exactly as specified in `format`. This is the default behavior.| +||Has no effect, because the structure does not include a `Kind` property.| + +## Examples + + The following example uses the method with standard and custom format specifiers, the invariant culture, and various values to parse several date and time strings. + + :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/TryParseExact/TryParseExact.cs" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.TryParseExact/fs/TryParseExact.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.TryParseExact/vb/TryParseExact.vb" id="Snippet1"::: + +The following example uses a variety of values to parse an array of strings that are expected to conform to [ISO 8601](/dotnet/standard/base-types/standard-date-and-time-format-strings#the-round-trip-o-o-format-specifier). As the output from the example shows, strings that are in the proper format fail to parse if: + +- they contain white space, and an appropriate flag (such as has not been supplied in the method call. + +- they contain date and time elements that are out of range. + +Strings that do not specify a UTC offset are assumed to have the offset of the local time zone (in this case, -07:00, which reflects the offset of the Pacific Daylight Time zone) unless the flag is supplied in the method call. In that case, they are assumed to be Universal Coordinated Time. + +:::code language="fsharp" source="~/snippets/fsharp/System/DateTimeOffset.TryParseExact/tryparseexacto8601-2.fs"::: +:::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/TryParseExact/tryparseexacto8601-2.cs"::: +:::code language="vb" source="~/snippets/visualbasic/api/system/datetimeoffset/tryparseexact/tryparseexacto8601-2.vb"::: + ]]> - includes an undefined value. - - -or- - - is not supported. - - -or- - + includes an undefined value. + + -or- + + is not supported. + + -or- + includes mutually exclusive values. In the .NET Framework 4, the returns if the string to be parsed contains an hour component and an AM/PM designator that are not in agreement. In the .NET Framework 3.5 and earlier versions, the AM/PM designator is ignored. @@ -7637,60 +7637,60 @@ Strings that do not specify a UTC offset are assumed to have the offset of the l if the parameter is successfully converted; otherwise, . - method parses the string representation of a date that matches any one of the patterns assigned to the `formats` array. If the `input` string does not match any one of these patterns with any variations defined by the `styles` parameter, the parsing operation fails and the method returns `false`. Aside from comparing `input` to multiple strings that contain format specifiers, this overload behaves identically to the method. - - The `formats` parameter is a string array whose elements contain either a single standard format specifier or one or more custom format specifiers that define the possible pattern of `input`. For details about valid formatting codes, see [Standard Date and Time Format Strings](/dotnet/standard/base-types/standard-date-and-time-format-strings) and [Custom Date and Time Format Strings](/dotnet/standard/base-types/custom-date-and-time-format-strings). If the matched element in `formats` includes the `z`, `zz`, or `zzz` custom format specifiers to indicate that an offset must be present in `input`, that offset must include either a negative sign or a positive sign. If the sign is missing, the parse operation fails and the method returns `false`. - -> [!IMPORTANT] -> Using the `formats` parameter of this overload to specify multiple formats can help reduce the frustration many users experience when they enter dates and times. In particular, the ability to define multiple input patterns enables an application to handle date and time representations that can either include or lack leading zeros in months, days, hours, minutes, and seconds. The example provides an illustration of this. - - If the matched element in `formats` requires that `input` contain a date but not a time, the resulting object is assigned a time of midnight (0:00:00). If the matched element in `formats` requires that input contain a time but not a date, the resulting object is assigned the current date on the local system. If the matched element in `formats` does not require that `input` contain an offset, the offset of the resulting object depends on the value of the `styles` parameter. If `styles` includes , the offset of the local time zone is assigned to the object. If `styles` includes , the Coordinated Universal Time (UTC) offset, or +00:00, is assigned to the object. If neither value is specified, the offset of the local time zone is used. - - The particular date and time symbols and strings used in `input` are defined by the `formatProvider` parameter. The same is true for the precise pattern of `input` if the matching element of `formats` is a standard format specifier string. The `formatProvider` parameter can be either of the following: - -- A object that represents the culture based on which `input` is interpreted. The object returned by the property defines the symbols and formatting in `input`. - -- A object that defines the format of date and time data. - - If `formatprovider` is `null`, the object that corresponds to the current culture is used. - - The `styles` parameter defines whether white space is permitted in the input string, indicates how strings without an explicit offset component are parsed, and supports UTC conversion as part of the parsing operation. All members of the enumeration are supported except . The following table lists the effect of each supported member. - -|`DateTimeStyles` member|Behavior| -|-----------------------------|--------------| -||Parses `input` and, if necessary, converts it to UTC. It is equivalent to parsing a string, and then calling the method of the returned object.| -||If the matched element in `formats` does not require that `input` contain an offset value, the returned object is given the offset of the local time zone. This is the default value.| -||If the matched element in `formats` does not require that `input` contain an offset value, the returned object is given the UTC offset (+00:00).| -||Allows `input` to include inner white space not specified by the elements in `formats`. Extra white space can appear between date and time components and within individual components (except for the offset) and is ignored when parsing the string.| -||Allows `input` to include leading spaces not specified by the elements in `formats`. These are ignored when parsing the string.| -||Allows `input` to include trailing spaces not specified by the elements in `formats`. These are ignored when parsing the string.| -||Allows `input` to include leading, trailing, and inner spaces not specified by the elements in `formats`. All extra white-space characters not specified in the matched element in `formats` are ignored when parsing the string.| -||Indicates that additional white space is not permitted in `input`. White space must appear exactly as specified in a particular element in `formats` for a successful match to occur. This is the default behavior.| -||Has no effect because the structure does not include a `Kind` property.| - - - -## Examples - The following example defines multiple input formats for the string representation of a date and time and offset value, and then passes the string that is entered by the user to the method. - - :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/TryParseExact/TryParseExact.cs" id="Snippet2"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.TryParseExact/fs/TryParseExact.fs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.TryParseExact/vb/TryParseExact.vb" id="Snippet2"::: - + method parses the string representation of a date that matches any one of the patterns assigned to the `formats` array. If the `input` string does not match any one of these patterns with any variations defined by the `styles` parameter, the parsing operation fails and the method returns `false`. Aside from comparing `input` to multiple strings that contain format specifiers, this overload behaves identically to the method. + + The `formats` parameter is a string array whose elements contain either a single standard format specifier or one or more custom format specifiers that define the possible pattern of `input`. For details about valid formatting codes, see [Standard Date and Time Format Strings](/dotnet/standard/base-types/standard-date-and-time-format-strings) and [Custom Date and Time Format Strings](/dotnet/standard/base-types/custom-date-and-time-format-strings). If the matched element in `formats` includes the `z`, `zz`, or `zzz` custom format specifiers to indicate that an offset must be present in `input`, that offset must include either a negative sign or a positive sign. If the sign is missing, the parse operation fails and the method returns `false`. + +> [!IMPORTANT] +> Using the `formats` parameter of this overload to specify multiple formats can help reduce the frustration many users experience when they enter dates and times. In particular, the ability to define multiple input patterns enables an application to handle date and time representations that can either include or lack leading zeros in months, days, hours, minutes, and seconds. The example provides an illustration of this. + + If the matched element in `formats` requires that `input` contain a date but not a time, the resulting object is assigned a time of midnight (0:00:00). If the matched element in `formats` requires that input contain a time but not a date, the resulting object is assigned the current date on the local system. If the matched element in `formats` does not require that `input` contain an offset, the offset of the resulting object depends on the value of the `styles` parameter. If `styles` includes , the offset of the local time zone is assigned to the object. If `styles` includes , the Coordinated Universal Time (UTC) offset, or +00:00, is assigned to the object. If neither value is specified, the offset of the local time zone is used. + + The particular date and time symbols and strings used in `input` are defined by the `formatProvider` parameter. The same is true for the precise pattern of `input` if the matching element of `formats` is a standard format specifier string. The `formatProvider` parameter can be either of the following: + +- A object that represents the culture based on which `input` is interpreted. The object returned by the property defines the symbols and formatting in `input`. + +- A object that defines the format of date and time data. + + If `formatprovider` is `null`, the object that corresponds to the current culture is used. + + The `styles` parameter defines whether white space is permitted in the input string, indicates how strings without an explicit offset component are parsed, and supports UTC conversion as part of the parsing operation. All members of the enumeration are supported except . The following table lists the effect of each supported member. + +|`DateTimeStyles` member|Behavior| +|-----------------------------|--------------| +||Parses `input` and, if necessary, converts it to UTC. It is equivalent to parsing a string, and then calling the method of the returned object.| +||If the matched element in `formats` does not require that `input` contain an offset value, the returned object is given the offset of the local time zone. This is the default value.| +||If the matched element in `formats` does not require that `input` contain an offset value, the returned object is given the UTC offset (+00:00).| +||Allows `input` to include inner white space not specified by the elements in `formats`. Extra white space can appear between date and time components and within individual components (except for the offset) and is ignored when parsing the string.| +||Allows `input` to include leading spaces not specified by the elements in `formats`. These are ignored when parsing the string.| +||Allows `input` to include trailing spaces not specified by the elements in `formats`. These are ignored when parsing the string.| +||Allows `input` to include leading, trailing, and inner spaces not specified by the elements in `formats`. All extra white-space characters not specified in the matched element in `formats` are ignored when parsing the string.| +||Indicates that additional white space is not permitted in `input`. White space must appear exactly as specified in a particular element in `formats` for a successful match to occur. This is the default behavior.| +||Has no effect because the structure does not include a `Kind` property.| + + + +## Examples + The following example defines multiple input formats for the string representation of a date and time and offset value, and then passes the string that is entered by the user to the method. + + :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/TryParseExact/TryParseExact.cs" id="Snippet2"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.TryParseExact/fs/TryParseExact.fs" id="Snippet2"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.TryParseExact/vb/TryParseExact.vb" id="Snippet2"::: + ]]> - includes an undefined value. - - -or- - - is not supported. - - -or- - + includes an undefined value. + + -or- + + is not supported. + + -or- + includes mutually exclusive values. In the .NET Framework 4, the returns if the string to be parsed contains an hour component and an AM/PM designator that are not in agreement. In the .NET Framework 3.5 and earlier versions, the AM/PM designator is ignored. @@ -7771,28 +7771,28 @@ Strings that do not specify a UTC offset are assumed to have the offset of the l Gets a value that represents the Coordinated Universal Time (UTC) date and time of the current object. The Coordinated Universal Time (UTC) date and time of the current object. - property performs a dual conversion: - -- It converts the date and time of the current object to Coordinated Universal Time (UTC). The conversion is performed by subtracting the value of the property from the date and time of the current object. - -- It converts the value to a value. - - The property of the returned value is set to . - - Retrieving the value of the property is equivalent to calling the current object's `ToUniversalTime.DateTime` property, except that the property of the latter value is . - - - -## Examples - The following example shows how to use of the property to display a value and its corresponding UTC time. - - :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Date/Properties.cs" id="Snippet17"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Properties/fs/Properties.fs" id="Snippet17"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Properties/vb/Properties.vb" id="Snippet17"::: - + property performs a dual conversion: + +- It converts the date and time of the current object to Coordinated Universal Time (UTC). The conversion is performed by subtracting the value of the property from the date and time of the current object. + +- It converts the value to a value. + + The property of the returned value is set to . + + Retrieving the value of the property is equivalent to calling the current object's `ToUniversalTime.DateTime` property, except that the property of the latter value is . + + + +## Examples + The following example shows how to use of the property to display a value and its corresponding UTC time. + + :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Date/Properties.cs" id="Snippet17"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Properties/fs/Properties.fs" id="Snippet17"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Properties/vb/Properties.vb" id="Snippet17"::: + ]]> @@ -7838,22 +7838,22 @@ Strings that do not specify a UTC offset are assumed to have the offset of the l Gets a object whose date and time are set to the current Coordinated Universal Time (UTC) date and time and whose offset is . An object whose date and time is the current Coordinated Universal Time (UTC) and whose offset is . - property computes the current Universal Coordinated Time (UTC) based on the local system's clock time and an offset defined by the local system's time zone. - - The precision of the current UTC time's millisecond component depends on the resolution of the system clock. On Windows NT 3.5 and later, and Windows Vista operating systems, the clock's resolution is approximately 10-15 milliseconds. - - - -## Examples - The following example illustrates the relationship between Coordinated Universal Time (UTC) and local time. - - :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Date/Properties.cs" id="Snippet18"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Properties/fs/Properties.fs" id="Snippet18"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Properties/vb/Properties.vb" id="Snippet18"::: - + property computes the current Universal Coordinated Time (UTC) based on the local system's clock time and an offset defined by the local system's time zone. + + The precision of the current UTC time's millisecond component depends on the resolution of the system clock. On Windows NT 3.5 and later, and Windows Vista operating systems, the clock's resolution is approximately 10-15 milliseconds. + + + +## Examples + The following example illustrates the relationship between Coordinated Universal Time (UTC) and local time. + + :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Date/Properties.cs" id="Snippet18"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Properties/fs/Properties.fs" id="Snippet18"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Properties/vb/Properties.vb" id="Snippet18"::: + ]]> @@ -7900,11 +7900,11 @@ Strings that do not specify a UTC offset are assumed to have the offset of the l Gets the number of ticks that represents the date and time of the current object in Coordinated Universal Time (UTC). The number of ticks in the object's Coordinated Universal Time (UTC). - property represents the number of 100-nanosecond intervals that have elapsed since 12:00:00 midnight on January 1, 0001 (the value of ). It does not include ticks that would be added by leap seconds. A nanosecond is one billionth of a second; there are ten million ticks in a second. The value of the property ranges from `DateTimeOffset.MinValue.Ticks` to `DateTimeOffset.MaxValue.Ticks`. - + property represents the number of 100-nanosecond intervals that have elapsed since 12:00:00 midnight on January 1, 0001 (the value of ). It does not include ticks that would be added by leap seconds. A nanosecond is one billionth of a second; there are ten million ticks in a second. The value of the property ranges from `DateTimeOffset.MinValue.Ticks` to `DateTimeOffset.MaxValue.Ticks`. + ]]> @@ -7950,30 +7950,30 @@ Strings that do not specify a UTC offset are assumed to have the offset of the l Gets the year component of the date represented by the current object. The year component of the current object, expressed as an integer value between 0 and 9999. - property is not affected by the value of the property. - - You can also create a string representation of a object's year component by calling the method with the "y", "yy", or "yyyy" custom format specifiers. - - - -## Examples - The following example displays the year component of a value in four different ways: - -- By retrieving the value of the property. - -- By calling the method with the "y" format specifier. - -- By calling the method with the "yy" format specifier. - -- By calling the method with the "yyyy" format specifier. - - :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Date/Properties.cs" id="Snippet19"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Properties/fs/Properties.fs" id="Snippet19"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Properties/vb/Properties.vb" id="Snippet19"::: - + property is not affected by the value of the property. + + You can also create a string representation of a object's year component by calling the method with the "y", "yy", or "yyyy" custom format specifiers. + + + +## Examples + The following example displays the year component of a value in four different ways: + +- By retrieving the value of the property. + +- By calling the method with the "y" format specifier. + +- By calling the method with the "yy" format specifier. + +- By calling the method with the "yyyy" format specifier. + + :::code language="csharp" source="~/snippets/csharp/System/DateTimeOffset/Date/Properties.cs" id="Snippet19"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.DateTimeOffset.Properties/fs/Properties.fs" id="Snippet19"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Properties/vb/Properties.vb" id="Snippet19"::: + ]]> diff --git a/xml/System/Decimal.xml b/xml/System/Decimal.xml index 055e0ca4a00..8931778f29d 100644 --- a/xml/System/Decimal.xml +++ b/xml/System/Decimal.xml @@ -1344,7 +1344,7 @@ System.Int32 - + The object to compare with this instance, or . @@ -2046,7 +2046,7 @@ System.Decimal - + An OLE Automation Currency value. @@ -6643,7 +6643,7 @@ For , this method matches the IE System.Decimal - + A decimal number to round. @@ -6713,8 +6713,8 @@ For , this method matches the IE System.Decimal - - + + A decimal number to round. @@ -6788,8 +6788,8 @@ This method is equivalent to calling the System.Decimal - - + + A decimal number to round. @@ -6863,9 +6863,9 @@ The following example displays values returned by the System.Decimal - - - + + + A decimal number to round. @@ -9572,7 +9572,7 @@ This member is an explicit interface member implementation. It can be used only System.Void - + The object that initiated the callback. The functionality for this parameter is not currently implemented. @@ -10015,7 +10015,7 @@ This member is an explicit interface member implementation. It can be used only System.Int64 - + The decimal number to convert. diff --git a/xml/System/Delegate.xml b/xml/System/Delegate.xml index 6dc0ab3c149..f826e64ee71 100644 --- a/xml/System/Delegate.xml +++ b/xml/System/Delegate.xml @@ -194,8 +194,8 @@ For examples, see [Supplemental API remarks for System.Delegate.CreateDelegate]( - - + + The class instance on which the delegate invokes . @@ -260,7 +260,7 @@ For examples, see [Supplemental API remarks for System.Delegate.CreateDelegate]( - + [System.Diagnostics.CodeAnalysis.DynamicallyAccessedMembers(System.Diagnostics.CodeAnalysis.DynamicallyAccessedMemberTypes.All)] @@ -268,7 +268,7 @@ For examples, see [Supplemental API remarks for System.Delegate.CreateDelegate]( - + The representing the class that defines . @@ -574,7 +574,7 @@ For examples, see [Supplemental API remarks for System.Delegate.CreateDelegate]( System.Delegate - + [System.Runtime.CompilerServices.Nullable(2)] @@ -648,8 +648,8 @@ For examples, see [Supplemental API remarks for System.Delegate.CreateDelegate]( System.Delegate - - + + The of delegate to create. @@ -729,8 +729,8 @@ For more information about this API, see [Supplemental API remarks for System.De System.Delegate - - + + [System.Runtime.CompilerServices.Nullable(2)] @@ -738,7 +738,7 @@ For more information about this API, see [Supplemental API remarks for System.De - + The of delegate to create. @@ -829,9 +829,9 @@ For more information about this API, see [Supplemental API remarks for System.De System.Delegate - - - + + + The of delegate to create. @@ -922,9 +922,9 @@ For more information about this API, see [Supplemental API remarks for System.De System.Delegate - - - + + + The of delegate to create. @@ -1015,8 +1015,8 @@ For examples, see [Supplemental API remarks for System.Delegate.CreateDelegate]( System.Delegate - - + + [System.Diagnostics.CodeAnalysis.DynamicallyAccessedMembers(System.Diagnostics.CodeAnalysis.DynamicallyAccessedMemberTypes.All)] @@ -1024,7 +1024,7 @@ For examples, see [Supplemental API remarks for System.Delegate.CreateDelegate]( - + The of delegate to create. @@ -1123,8 +1123,8 @@ For examples, see [Supplemental API remarks for System.Delegate.CreateDelegate]( System.Delegate - - + + [System.Runtime.CompilerServices.Nullable(2)] @@ -1132,8 +1132,8 @@ For examples, see [Supplemental API remarks for System.Delegate.CreateDelegate]( - - + + A representing the type of delegate to create. @@ -1225,10 +1225,10 @@ For more information and examples, see [Supplemental API remarks for System.Dele System.Delegate - - - - + + + + The of delegate to create. @@ -1319,8 +1319,8 @@ For more information and examples, see [Supplemental API remarks for System.Dele System.Delegate - - + + [System.Diagnostics.CodeAnalysis.DynamicallyAccessedMembers(System.Diagnostics.CodeAnalysis.DynamicallyAccessedMemberTypes.All)] @@ -1328,8 +1328,8 @@ For more information and examples, see [Supplemental API remarks for System.Dele - - + + The of delegate to create. @@ -1433,11 +1433,11 @@ For more information and examples, see [Supplemental API remarks for System.Dele System.Delegate - - - - - + + + + + The of delegate to create. @@ -1533,8 +1533,8 @@ For more information and examples, see [Supplemental API remarks for System.Dele System.Delegate - - + + [System.Diagnostics.CodeAnalysis.DynamicallyAccessedMembers(System.Diagnostics.CodeAnalysis.DynamicallyAccessedMemberTypes.All)] @@ -1542,9 +1542,9 @@ For more information and examples, see [Supplemental API remarks for System.Dele - - - + + + The of delegate to create. @@ -1743,7 +1743,7 @@ The number, order, or type of parameters listed in is i System.Object - + An array of objects that are the arguments to pass to the method represented by the current delegate. @@ -2146,8 +2146,8 @@ The number, order, or type of parameters listed in is i System.Void - - + + Not supported. @@ -2574,7 +2574,7 @@ The number, order, or type of parameters listed in is i System.Delegate - + The delegate that supplies the invocation list to remove from the invocation list of the current delegate. diff --git a/xml/System/DivideByZeroException.xml b/xml/System/DivideByZeroException.xml index 827183fb7a2..dd92cbaf22e 100644 --- a/xml/System/DivideByZeroException.xml +++ b/xml/System/DivideByZeroException.xml @@ -66,38 +66,38 @@ The exception that is thrown when there is an attempt to divide an integral or value by zero. - number by zero throws a exception. To prevent the exception, ensure that the denominator in a division operation with integer or values is non-zero. - - Dividing a floating-point value by zero doesn't throw an exception; it results in positive infinity, negative infinity, or not a number (NaN), according to the rules of IEEE 754 arithmetic. Because the following example uses floating-point division rather than integer division, the operation does not throw a exception. - + number by zero throws a exception. To prevent the exception, ensure that the denominator in a division operation with integer or values is non-zero. + + Dividing a floating-point value by zero doesn't throw an exception; it results in positive infinity, negative infinity, or not a number (NaN), according to the rules of IEEE 754 arithmetic. Because the following example uses floating-point division rather than integer division, the operation does not throw a exception. + :::code language="csharp" source="~/snippets/csharp/System/DivideByZeroException/Overview/exception2.cs" interactive="try-dotnet" id="Snippet2"::: :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.dividebyzeroexception.class/fs/exception2.fs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.dividebyzeroexception.class/vb/exception2.vb" id="Snippet2"::: - For more information, see and . - - The following Microsoft intermediate language (MSIL) instructions throw : - -- div - -- div.un - -- rem - -- rem.un - - uses the HRESULT COR_E_DIVIDEBYZERO, which has the value 0x80020012. - - For a list of initial property values for an instance of , see the constructors. - - - -## Examples - The following example handles a exception in integer division. - + For more information, see and . + + The following Microsoft intermediate language (MSIL) instructions throw : + +- div + +- div.un + +- rem + +- rem.un + + uses the HRESULT COR_E_DIVIDEBYZERO, which has the value 0x80020012. + + For a list of initial property values for an instance of , see the constructors. + + + +## Examples + The following example handles a exception in integer division. + :::code language="csharp" source="~/snippets/csharp/System/DivideByZeroException/Overview/exception1.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR_System/system.dividebyzeroexception.class/fs/exception1.fs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.dividebyzeroexception.class/vb/exception1.vb" id="Snippet1"::: @@ -159,18 +159,18 @@ Initializes a new instance of the class. - property of the new instance to a system-supplied message that describes the error, such as "Attempted to divide by zero." This message takes into account the current system culture. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||A null reference (`Nothing` in Visual Basic).| -||The localized error message string.| - + property of the new instance to a system-supplied message that describes the error, such as "Attempted to divide by zero." This message takes into account the current system culture. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||A null reference (`Nothing` in Visual Basic).| +||The localized error message string.| + ]]> @@ -218,18 +218,18 @@ A that describes the error. Initializes a new instance of the class with a specified error message. - . - -|Property|Value| -|--------------|-----------| -||A null reference (`Nothing` in Visual Basic).| -||The error message string.| - + . + +|Property|Value| +|--------------|-----------| +||A null reference (`Nothing` in Visual Basic).| +||The error message string.| + ]]> @@ -284,19 +284,19 @@ - - + + The object that holds the serialized object data. The contextual information about the source or destination. Initializes a new instance of the class with serialized data. - @@ -346,18 +346,18 @@ The exception that is the cause of the current exception. If the parameter is not , the current exception is raised in a block that handles the inner exception. Initializes a new instance of the class with a specified error message and a reference to the inner exception that is the cause of this exception. - property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. - - The following table shows the initial property values for an instance of . - -|Property Type|Condition| -|-------------------|---------------| -||The inner exception reference.| -||The error message string.| - + property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. + + The following table shows the initial property values for an instance of . + +|Property Type|Condition| +|-------------------|---------------| +||The inner exception reference.| +||The error message string.| + ]]> diff --git a/xml/System/DllNotFoundException.xml b/xml/System/DllNotFoundException.xml index a44fb9e7639..59dbbd41581 100644 --- a/xml/System/DllNotFoundException.xml +++ b/xml/System/DllNotFoundException.xml @@ -67,17 +67,17 @@ The exception that is thrown when a DLL specified in a DLL import cannot be found. - uses the HRESULT COR_E_DLLNOTFOUND, which has the value 0x80131524. - - For a list of initial property values for an instance of , see the constructors. - - The is thrown when a dynamic link library defined by the attribute or a comparable language construct, such as the Visual Basic `Declare` statement, cannot be found. It is not thrown when the common language runtime is unable to load a .NET Framework assembly. - - Note that the can specify the path to the directory in which the DLL resides. If a path is not specified, Windows uses the search order described in [Dynamic-Link Library Search Order](https://go.microsoft.com/fwlink/?LinkId=122531). - + uses the HRESULT COR_E_DLLNOTFOUND, which has the value 0x80131524. + + For a list of initial property values for an instance of , see the constructors. + + The is thrown when a dynamic link library defined by the attribute or a comparable language construct, such as the Visual Basic `Declare` statement, cannot be found. It is not thrown when the common language runtime is unable to load a .NET Framework assembly. + + Note that the can specify the path to the directory in which the DLL resides. If a path is not specified, Windows uses the search order described in [Dynamic-Link Library Search Order](https://go.microsoft.com/fwlink/?LinkId=122531). + ]]> @@ -137,16 +137,16 @@ Initializes a new instance of the class with default properties. - . - -|Property|Value| -|--------------|-----------| -||A null reference (`Nothing` in Visual Basic).| -||The localized error message string.| - + . + +|Property|Value| +|--------------|-----------| +||A null reference (`Nothing` in Visual Basic).| +||The localized error message string.| + ]]> @@ -195,16 +195,16 @@ The error message that explains the reason for the exception. Initializes a new instance of the class with a specified error message. - . - -|Property|Value| -|--------------|-----------| -||A null reference (`Nothing` in Visual Basic).| -||The error message string.| - + . + +|Property|Value| +|--------------|-----------| +||A null reference (`Nothing` in Visual Basic).| +||The error message string.| + ]]> @@ -259,8 +259,8 @@ - - + + The that holds the serialized object data about the exception being thrown. @@ -315,18 +315,18 @@ The exception that is the cause of the current exception. If the parameter is not , the current exception is raised in a block that handles the inner exception. Initializes a new instance of the class with a specified error message and a reference to the inner exception that is the cause of this exception. - property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||The inner exception reference.| -||The error message string.| - + property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||The inner exception reference.| +||The error message string.| + ]]> diff --git a/xml/System/Double.xml b/xml/System/Double.xml index 3eb1714eecd..801bfbaa8cc 100644 --- a/xml/System/Double.xml +++ b/xml/System/Double.xml @@ -1150,7 +1150,7 @@ The following code example demonstrates generic and nongeneric versions of the < System.Int32 - + An object to compare, or . diff --git a/xml/System/Enum.xml b/xml/System/Enum.xml index 742c685031f..f0bdb80cb40 100644 --- a/xml/System/Enum.xml +++ b/xml/System/Enum.xml @@ -3033,8 +3033,8 @@ System.Object - - + + The enumeration type to return. @@ -3104,8 +3104,8 @@ System.Object - - + + The enumeration type to return. @@ -3175,8 +3175,8 @@ System.Object - - + + The enumeration type to return. @@ -3246,8 +3246,8 @@ System.Object - - + + The enumeration type to return. @@ -3396,8 +3396,8 @@ System.Object - - + + The enumeration type to return. @@ -3471,8 +3471,8 @@ System.Object - - + + The enumeration type to return. @@ -3546,8 +3546,8 @@ System.Object - - + + The enumeration type to return. @@ -3621,8 +3621,8 @@ System.Object - - + + The enumeration type to return. @@ -3787,7 +3787,7 @@ System.String - + [System.Runtime.CompilerServices.Nullable(2)] @@ -3961,7 +3961,7 @@ System.String - + [System.Diagnostics.CodeAnalysis.StringSyntax("EnumFormat")] @@ -3969,7 +3969,7 @@ - + A format specification. diff --git a/xml/System/Environment.xml b/xml/System/Environment.xml index 73563fd60e4..0b496911247 100644 --- a/xml/System/Environment.xml +++ b/xml/System/Environment.xml @@ -324,7 +324,7 @@ System.Void - + The exit code to return to the operating system. Use 0 (zero) to indicate that the process completed successfully. @@ -949,8 +949,8 @@ The following example attempts to retrieve the value of an environment variable System.String - - + + The name of an environment variable. @@ -1117,7 +1117,7 @@ On non-Windows systems, the `GetEnvironmentVariables` method retrieves the name System.Collections.IDictionary - + One of the values. Only is supported on .NET running on Unix-based systems. @@ -1211,7 +1211,7 @@ The following example creates environment variables for the System.String - + One of the enumeration values that identifies a system special folder. @@ -1287,8 +1287,8 @@ The following example creates environment variables for the System.String - - + + One of the enumeration values that identifies a system special folder. @@ -2091,8 +2091,8 @@ The following example attempts to retrieve the value of an environment variable System.Void - - + + [System.Runtime.CompilerServices.Nullable(2)] @@ -2100,7 +2100,7 @@ The following example attempts to retrieve the value of an environment variable - + The name of an environment variable. diff --git a/xml/System/Exception.xml b/xml/System/Exception.xml index 9ecadf72e83..65b9d5cc4e4 100644 --- a/xml/System/Exception.xml +++ b/xml/System/Exception.xml @@ -296,8 +296,8 @@ - - + + The that holds the serialized object data about the exception being thrown. @@ -603,8 +603,8 @@ The following example demonstrates how to add and retrieve information using the System.Void - - + + The that holds the serialized object data about the exception being thrown. diff --git a/xml/System/FieldAccessException.xml b/xml/System/FieldAccessException.xml index e8c8e1436c9..95d3612ceaf 100644 --- a/xml/System/FieldAccessException.xml +++ b/xml/System/FieldAccessException.xml @@ -64,18 +64,18 @@ The exception that is thrown when there is an invalid attempt to access a private or protected field inside a class. - uses the HRESULT COR_E_FIELDACCESS, which has the value 0x80131507. - - For a list of initial property values for an instance of , see the constructors. - + uses the HRESULT COR_E_FIELDACCESS, which has the value 0x80131507. + + For a list of initial property values for an instance of , see the constructors. + > [!NOTE] -> This exception is not included in the [.NET for Windows Store apps](https://go.microsoft.com/fwlink/?LinkID=247912) or the [Portable Class Library](/dotnet/standard/cross-platform/cross-platform-development-with-the-portable-class-library), but it is thrown by some members that are. To catch the exception in that case, write a `catch` statement for instead. - +> This exception is not included in the [.NET for Windows Store apps](https://go.microsoft.com/fwlink/?LinkID=247912) or the [Portable Class Library](/dotnet/standard/cross-platform/cross-platform-development-with-the-portable-class-library), but it is thrown by some members that are. To catch the exception in that case, write a `catch` statement for instead. + ]]> @@ -129,18 +129,18 @@ Initializes a new instance of the class. - property of the new instance to a system-supplied message that describes the error, such as "Attempted to access a field that is not accessible by the caller." This message takes the current system culture into account. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||A null reference (`Nothing` in Visual Basic).| -||The localized error message string.| - + property of the new instance to a system-supplied message that describes the error, such as "Attempted to access a field that is not accessible by the caller." This message takes the current system culture into account. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||A null reference (`Nothing` in Visual Basic).| +||The localized error message string.| + ]]> @@ -186,18 +186,18 @@ The error message that explains the reason for the exception. Initializes a new instance of the class with a specified error message. - property of the new instance by using the `message` parameter. The content of `message` is intended to be understood by humans. The caller of this constructor must ensure that this string has been localized for the current system culture. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||A null reference (`Nothing` in Visual Basic).| -||The localized error message string.| - + property of the new instance by using the `message` parameter. The content of `message` is intended to be understood by humans. The caller of this constructor must ensure that this string has been localized for the current system culture. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||A null reference (`Nothing` in Visual Basic).| +||The localized error message string.| + ]]> @@ -252,19 +252,19 @@ - - + + The object that holds the serialized object data. The contextual information about the source or destination. Initializes a new instance of the class with serialized data. - @@ -312,18 +312,18 @@ The exception that is the cause of the current exception. If the parameter is not , the current exception is raised in a block that handles the inner exception. Initializes a new instance of the class with a specified error message and a reference to the inner exception that is the cause of this exception. - property. The property returns the same value that is passed into the constructor, or returns `null` if it does not supply the inner exception value to the constructor. The caller of this constructor must ensure that this string has been localized for the current system culture. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||The inner exception reference.| -||The localized error message string.| - + property. The property returns the same value that is passed into the constructor, or returns `null` if it does not supply the inner exception value to the constructor. The caller of this constructor must ensure that this string has been localized for the current system culture. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||The inner exception reference.| +||The localized error message string.| + ]]> diff --git a/xml/System/FormatException.xml b/xml/System/FormatException.xml index 885605a0d0d..cda1334e6fe 100644 --- a/xml/System/FormatException.xml +++ b/xml/System/FormatException.xml @@ -72,111 +72,111 @@ The exception that is thrown when the format of an argument is invalid, or when a composite format string is not well formed. - exception can be thrown for one of the following reasons: - -- In a call to a method that converts a string to some other data type, the string doesn't conform to the required pattern. This typically occurs when calling some methods of the class and the `Parse` and `ParseExact` methods of some types. - - In most cases, particularly if the string that you're converting is input by a user or read from a file, you should use a `try/catch` (`try/with` in F#) block and handle the exception if the conversion is unsuccessful. You can also replace the call to the conversion method with a call to a `TryParse` or `TryParseExact` method, if one exists. However, a exception that is thrown when you're trying to parse a predefined or hard-coded string indicates a program error. In this case, you should correct the error rather than handle the exception. - - The conversion of a string to the following types in the namespace can throw a exception: - - - . The and methods require the string to be converted to be "True", "true", "False", or "false". Any other value throws a exception. - - - and . All date and time data is interpreted based on the formatting conventions of a particular culture: either the current culture (or, in some cases, the current application domain culture), the invariant culture, or a specified culture. When you call the and methods, date and time data must also conform *exactly* to a pattern specified by one or more [standard format strings](/dotnet/standard/base-types/standard-date-and-time-format-strings) or [custom format strings](/dotnet/standard/base-types/custom-date-and-time-format-strings) that are provided as arguments in the method call. If it doesn't conform to an expected culture-specific pattern, a exception is thrown. This means that date and time data saved in a culture-specific format on one system might not parse successfully on another system. - - For more information about parsing dates and times, see [Parsing Date and Time Strings](/dotnet/standard/base-types/parsing-datetime) and the documentation for the method that threw the exception. - - - **GUIDs.** The string representation of a GUID must consist of 32 hexadecimal digits (0-F), and must be in one of the five formats output by the method. For more information, see the method. - - - **Numeric types, including all signed integers, unsigned integers, and floating-point types.** The string to be parsed must consist of the Latin digits 0-9. A positive or negative sign, decimal separator, group separators, and currency symbol may also be permitted. Trying to parse a string that contains any other character always throws a exception. - - All numeric strings are interpreted based on the formatting conventions of a particular culture: either the current culture, the invariant culture, or a specified culture. As a result, a numeric string that is parsed by using the conventions of one culture might fail when using the conventions of another. - - For more information about parsing numeric strings, see [Parsing Numeric Strings](/dotnet/standard/base-types/parsing-numeric) and the documentation for the specific method that threw the exception. - - - **Time intervals.** The string to be parsed must be either in fixed culture-insensitive format or in a culture-sensitive format defined by the current culture, the invariant culture, or a specified culture. If the string isn't in an appropriate format, or if, at the minimum, the days, hours, and minutes components of the time interval aren't present, the parsing method throws a exception. For more information, see the documentation for the parsing method that threw the exception. - -- A type implements the interface, which supports format strings that define how an object is converted to its string representation, and an invalid format string is used. This is most common in a formatting operation. In the following example, the "Q" standard format string is used in a composite format string to format a number. However, "Q" is not a valid [standard format string](/dotnet/standard/base-types/standard-numeric-format-strings). - + exception can be thrown for one of the following reasons: + +- In a call to a method that converts a string to some other data type, the string doesn't conform to the required pattern. This typically occurs when calling some methods of the class and the `Parse` and `ParseExact` methods of some types. + + In most cases, particularly if the string that you're converting is input by a user or read from a file, you should use a `try/catch` (`try/with` in F#) block and handle the exception if the conversion is unsuccessful. You can also replace the call to the conversion method with a call to a `TryParse` or `TryParseExact` method, if one exists. However, a exception that is thrown when you're trying to parse a predefined or hard-coded string indicates a program error. In this case, you should correct the error rather than handle the exception. + + The conversion of a string to the following types in the namespace can throw a exception: + + - . The and methods require the string to be converted to be "True", "true", "False", or "false". Any other value throws a exception. + + - and . All date and time data is interpreted based on the formatting conventions of a particular culture: either the current culture (or, in some cases, the current application domain culture), the invariant culture, or a specified culture. When you call the and methods, date and time data must also conform *exactly* to a pattern specified by one or more [standard format strings](/dotnet/standard/base-types/standard-date-and-time-format-strings) or [custom format strings](/dotnet/standard/base-types/custom-date-and-time-format-strings) that are provided as arguments in the method call. If it doesn't conform to an expected culture-specific pattern, a exception is thrown. This means that date and time data saved in a culture-specific format on one system might not parse successfully on another system. + + For more information about parsing dates and times, see [Parsing Date and Time Strings](/dotnet/standard/base-types/parsing-datetime) and the documentation for the method that threw the exception. + + - **GUIDs.** The string representation of a GUID must consist of 32 hexadecimal digits (0-F), and must be in one of the five formats output by the method. For more information, see the method. + + - **Numeric types, including all signed integers, unsigned integers, and floating-point types.** The string to be parsed must consist of the Latin digits 0-9. A positive or negative sign, decimal separator, group separators, and currency symbol may also be permitted. Trying to parse a string that contains any other character always throws a exception. + + All numeric strings are interpreted based on the formatting conventions of a particular culture: either the current culture, the invariant culture, or a specified culture. As a result, a numeric string that is parsed by using the conventions of one culture might fail when using the conventions of another. + + For more information about parsing numeric strings, see [Parsing Numeric Strings](/dotnet/standard/base-types/parsing-numeric) and the documentation for the specific method that threw the exception. + + - **Time intervals.** The string to be parsed must be either in fixed culture-insensitive format or in a culture-sensitive format defined by the current culture, the invariant culture, or a specified culture. If the string isn't in an appropriate format, or if, at the minimum, the days, hours, and minutes components of the time interval aren't present, the parsing method throws a exception. For more information, see the documentation for the parsing method that threw the exception. + +- A type implements the interface, which supports format strings that define how an object is converted to its string representation, and an invalid format string is used. This is most common in a formatting operation. In the following example, the "Q" standard format string is used in a composite format string to format a number. However, "Q" is not a valid [standard format string](/dotnet/standard/base-types/standard-numeric-format-strings). + :::code language="csharp" source="~/snippets/csharp/System/FormatException/Overview/iformattable1.cs" id="Snippet7"::: :::code language="fsharp" source="~/snippets/fsharp/System/FormatException/Overview/iformattable1.fs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.formatexception/vb/iformattable1.vb" id="Snippet7"::: - - This exception results from a coding error. To correct the error, either remove the format string or substitute a valid one. The following example corrects the error by replacing the invalid format string with the "C" (currency) format string. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.formatexception/vb/iformattable1.vb" id="Snippet7"::: + + This exception results from a coding error. To correct the error, either remove the format string or substitute a valid one. The following example corrects the error by replacing the invalid format string with the "C" (currency) format string. + :::code language="csharp" source="~/snippets/csharp/System/FormatException/Overview/iformattable2.cs" id="Snippet8"::: :::code language="fsharp" source="~/snippets/fsharp/System/FormatException/Overview/iformattable2.fs" id="Snippet8"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.formatexception/vb/iformattable2.vb" id="Snippet8"::: - - A exception can also be thrown by parsing methods, such as and , that require the string to be parsed to conform exactly to the pattern specified by a format string. In the following example, the string representation of a GUID is expected to conform to the pattern specified by the "G" standard format string. However, the structure's implementation of does not support the "G" format string. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.formatexception/vb/iformattable2.vb" id="Snippet8"::: + + A exception can also be thrown by parsing methods, such as and , that require the string to be parsed to conform exactly to the pattern specified by a format string. In the following example, the string representation of a GUID is expected to conform to the pattern specified by the "G" standard format string. However, the structure's implementation of does not support the "G" format string. + :::code language="csharp" source="~/snippets/csharp/System/FormatException/Overview/iformattable3.cs" id="Snippet9"::: :::code language="fsharp" source="~/snippets/fsharp/System/FormatException/Overview/iformattable3.fs" id="Snippet9"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.formatexception/vb/iformattable3.vb" id="Snippet9"::: - - This exception also results from a coding error. To correct it, call a parsing method that doesn't require a precise format, such as or , or substitute a valid format string. The following example corrects the error by calling the method. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.formatexception/vb/iformattable3.vb" id="Snippet9"::: + + This exception also results from a coding error. To correct it, call a parsing method that doesn't require a precise format, such as or , or substitute a valid format string. The following example corrects the error by calling the method. + :::code language="csharp" source="~/snippets/csharp/System/FormatException/Overview/iformattable4.cs" interactive="try-dotnet" id="Snippet10"::: :::code language="fsharp" source="~/snippets/fsharp/System/FormatException/Overview/iformattable4.fs" id="Snippet10"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.formatexception/vb/iformattable4.vb" id="Snippet10"::: - -- One or more of the indexes of the format items in a [composite format string](/dotnet/standard/base-types/composite-formatting) is greater than the indexes of the items in the object list or parameter array. In the following example, the largest index of a format item in the format string is 3. Because the indexes of items in the object list are zero-based, this format string would require the object list to have four items. Instead, it has only three, `dat`, `temp`, and `scale`, so the code results in a exception at run time:. - + +- One or more of the indexes of the format items in a [composite format string](/dotnet/standard/base-types/composite-formatting) is greater than the indexes of the items in the object list or parameter array. In the following example, the largest index of a format item in the format string is 3. Because the indexes of items in the object list are zero-based, this format string would require the object list to have four items. Instead, it has only three, `dat`, `temp`, and `scale`, so the code results in a exception at run time:. + :::code language="csharp" source="~/snippets/csharp/System/FormatException/Overview/example1.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System/FormatException/Overview/example1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.formatexception/vb/example1.vb" id="Snippet1"::: - - In this case, the exception is a result of developer error. It should be corrected rather than handled in a `try/catch` block by making sure that each item in the object list corresponds to the index of a format item. To correct this example, change the index of the second format item to refer to the `dat` variable, and decrement the index of each subsequent format item by one. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.formatexception/vb/example1.vb" id="Snippet1"::: + + In this case, the exception is a result of developer error. It should be corrected rather than handled in a `try/catch` block by making sure that each item in the object list corresponds to the index of a format item. To correct this example, change the index of the second format item to refer to the `dat` variable, and decrement the index of each subsequent format item by one. + :::code language="csharp" source="~/snippets/csharp/System/FormatException/Overview/example2.cs" id="Snippet2"::: :::code language="fsharp" source="~/snippets/fsharp/System/FormatException/Overview/example2.fs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.formatexception/vb/example2.vb" id="Snippet2"::: - -- The composite format string isn't well-formed. When this happens, the exception is always a result of developer error. It should be corrected rather than handled in a `try/catch` block. - - Trying to include literal braces in a string, as the following example does, will throw the exception. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.formatexception/vb/example2.vb" id="Snippet2"::: + +- The composite format string isn't well-formed. When this happens, the exception is always a result of developer error. It should be corrected rather than handled in a `try/catch` block. + + Trying to include literal braces in a string, as the following example does, will throw the exception. + :::code language="csharp" source="~/snippets/csharp/System/FormatException/Overview/qa3.cs" id="Snippet23"::: :::code language="fsharp" source="~/snippets/fsharp/System/FormatException/Overview/qa3.fs" id="Snippet23"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/qa3.vb" id="Snippet23"::: - - The recommended technique for including literal braces in a composite format string is to include them in the object list and use format items to insert them into the result string. For example, you can modify the previous composite format string as shown here. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/qa3.vb" id="Snippet23"::: + + The recommended technique for including literal braces in a composite format string is to include them in the object list and use format items to insert them into the result string. For example, you can modify the previous composite format string as shown here. + :::code language="csharp" source="~/snippets/csharp/System/FormatException/Overview/qa3.cs" interactive="try-dotnet-method" id="Snippet24"::: :::code language="fsharp" source="~/snippets/fsharp/System/FormatException/Overview/qa3.fs" id="Snippet24"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/qa3.vb" id="Snippet24"::: - - The exception is also thrown if your format string contains a typo. The following call to the method omits a closing brace and pairs an opening brace with a closing bracket. - + + The exception is also thrown if your format string contains a typo. The following call to the method omits a closing brace and pairs an opening brace with a closing bracket. + :::code language="csharp" source="~/snippets/csharp/System/FormatException/Overview/example3.cs" id="Snippet3"::: :::code language="fsharp" source="~/snippets/fsharp/System/FormatException/Overview/example3.fs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.formatexception/vb/example3.vb" id="Snippet3"::: - - To correct the error, ensure that all opening and closing braces correspond. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.formatexception/vb/example3.vb" id="Snippet3"::: + + To correct the error, ensure that all opening and closing braces correspond. + :::code language="csharp" source="~/snippets/csharp/System/FormatException/Overview/example3.cs" id="Snippet4"::: :::code language="fsharp" source="~/snippets/fsharp/System/FormatException/Overview/example3.fs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.formatexception/vb/example3.vb" id="Snippet4"::: - -- You've supplied the object list in a composite formatting method as a strongly typed parameter array, and the exception indicates that the index of one or more format items exceeds the number of arguments in the object list. This occurs because no explicit conversion between array types exists, so instead the compiler treats the array as a single argument rather than as a parameter array. For example, the following call to the method throws a exception, although the highest index of the format items is 3, and the parameter array of type has four elements. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.formatexception/vb/example3.vb" id="Snippet4"::: + +- You've supplied the object list in a composite formatting method as a strongly typed parameter array, and the exception indicates that the index of one or more format items exceeds the number of arguments in the object list. This occurs because no explicit conversion between array types exists, so instead the compiler treats the array as a single argument rather than as a parameter array. For example, the following call to the method throws a exception, although the highest index of the format items is 3, and the parameter array of type has four elements. + :::code language="csharp" source="~/snippets/csharp/System/FormatException/Overview/qa1.cs" id="Snippet5"::: :::code language="fsharp" source="~/snippets/fsharp/System/FormatException/Overview/qa1.fs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.formatexception/vb/qa1.vb" id="Snippet5"::: - - Instead of handling this exception, you should eliminate its cause. Because neither Visual Basic nor C# can convert an integer array to an object array, you have to perform the conversion yourself before calling the composite formatting method. The following example provides one implementation. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.formatexception/vb/qa1.vb" id="Snippet5"::: + + Instead of handling this exception, you should eliminate its cause. Because neither Visual Basic nor C# can convert an integer array to an object array, you have to perform the conversion yourself before calling the composite formatting method. The following example provides one implementation. + :::code language="csharp" source="~/snippets/csharp/System/FormatException/Overview/qa2.cs" interactive="try-dotnet" id="Snippet6"::: :::code language="fsharp" source="~/snippets/fsharp/System/FormatException/Overview/qa2.fs" id="Snippet6"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.formatexception/vb/qa2.vb" id="Snippet6"::: - - uses the HRESULT COR_E_FORMAT, which has the value 0x80131537. - - The class derives from and adds no unique members. For a list of initial property values for an instance of , see the constructors. - + + uses the HRESULT COR_E_FORMAT, which has the value 0x80131537. + + The class derives from and adds no unique members. For a list of initial property values for an instance of , see the constructors. + ]]> @@ -234,18 +234,18 @@ Initializes a new instance of the class. - property of the new instance to a system-supplied message that describes the error, such as "Invalid format." This message takes into account the current system culture. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||A null reference (`Nothing` in Visual Basic).| -||The localized error message string.| - + property of the new instance to a system-supplied message that describes the error, such as "Invalid format." This message takes into account the current system culture. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||A null reference (`Nothing` in Visual Basic).| +||The localized error message string.| + ]]> @@ -293,18 +293,18 @@ The message that describes the error. Initializes a new instance of the class with a specified error message. - property of the new exception using the `message` parameter. The content of `message` is intended to be understood by humans. The caller of this constructor is required to ensure that this string has been localized for the current system culture. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||A null reference (`Nothing` in Visual Basic).| -||The error message string.| - + property of the new exception using the `message` parameter. The content of `message` is intended to be understood by humans. The caller of this constructor is required to ensure that this string has been localized for the current system culture. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||A null reference (`Nothing` in Visual Basic).| +||The error message string.| + ]]> @@ -359,19 +359,19 @@ - - + + The object that holds the serialized object data. The contextual information about the source or destination. Initializes a new instance of the class with serialized data. - @@ -421,18 +421,18 @@ The exception that is the cause of the current exception. If the parameter is not a null reference ( in Visual Basic), the current exception is raised in a block that handles the inner exception. Initializes a new instance of the class with a specified error message and a reference to the inner exception that is the cause of this exception. - property. The property returns the same value that is passed into the constructor, or a null reference (`Nothing` in Visual Basic) if the property does not supply the inner exception value to the constructor. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||The inner exception reference.| -||The error message string.| - + property. The property returns the same value that is passed into the constructor, or a null reference (`Nothing` in Visual Basic) if the property does not supply the inner exception value to the constructor. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||The inner exception reference.| +||The error message string.| + ]]> diff --git a/xml/System/GC.xml b/xml/System/GC.xml index 9624419cff5..ddfa77a1266 100644 --- a/xml/System/GC.xml +++ b/xml/System/GC.xml @@ -691,10 +691,10 @@ Skipping zero-initialization using this API only has a material performance bene System.Void - - - - + + + + The number of the oldest generation to be garbage collected. @@ -1141,7 +1141,7 @@ The following example demonstrates how to use the System.Int32 - + A that refers to the target object whose generation number is to be determined. @@ -1559,8 +1559,8 @@ The following example demonstrates the use of the System.Void - - + + A number between 1 and 99 that specifies when the notification should be raised based on the objects allocated in generation 2. @@ -1954,7 +1954,7 @@ If `obj` does not have a finalizer or the GC has already signaled the finalizer System.Boolean - + The amount of memory in bytes to allocate without triggering a garbage collection. It must be less than or equal to the size of an ephemeral segment. For information on the size of an ephemeral segment, see the "Ephemeral generations and segments" section in the [Fundamentals of Garbage Collection](/dotnet/standard/garbage-collection/fundamentals) article. @@ -2023,8 +2023,8 @@ If `obj` does not have a finalizer or the GC has already signaled the finalizer System.Boolean - - + + The amount of memory in bytes to allocate without triggering a garbage collection. It must be less than or equal to the size of an ephemeral segment. For information on the size of an ephemeral segment, see the "Ephemeral generations and segments" section in the [Fundamentals of Garbage Collection](/dotnet/standard/garbage-collection/fundamentals) article. @@ -2097,8 +2097,8 @@ If `obj` does not have a finalizer or the GC has already signaled the finalizer System.Boolean - - + + The amount of memory in bytes to allocate without triggering a garbage collection. - must be less than or equal to the size of an ephemeral segment. For information on the size of an ephemeral segment, see the "Ephemeral generations and segments" section in the [Fundamentals of Garbage Collection](/dotnet/standard/garbage-collection/fundamentals) article. @@ -2168,9 +2168,9 @@ If `obj` does not have a finalizer or the GC has already signaled the finalizer System.Boolean - - - + + + The amount of memory in bytes to allocate without triggering a garbage collection. - must be less than or equal to the size of an ephemeral segment. For information on the size of an ephemeral segment, see the "Ephemeral generations and segments" section in the [Fundamentals of Garbage Collection](/dotnet/standard/garbage-collection/fundamentals) article. @@ -2325,7 +2325,7 @@ If `obj` does not have a finalizer or the GC has already signaled the finalizer System.GCNotificationStatus - + The length of time to wait before a notification status can be obtained. Specify -1 to wait indefinitely. @@ -2505,7 +2505,7 @@ If `obj` does not have a finalizer or the GC has already signaled the finalizer System.GCNotificationStatus - + The length of time to wait before a notification status can be obtained. Specify -1 to wait indefinitely. diff --git a/xml/System/Guid.xml b/xml/System/Guid.xml index 500292f411c..206fa7552a8 100644 --- a/xml/System/Guid.xml +++ b/xml/System/Guid.xml @@ -109,11 +109,11 @@ Represents a globally unique identifier (GUID). - @@ -265,61 +265,61 @@ - A string that contains a GUID in one of the following formats ("d" represents a hexadecimal digit whose case is ignored): - - 32 contiguous hexadecimal digits: - - dddddddddddddddddddddddddddddddd - - -or- - - Groups of 8, 4, 4, 4, and 12 hexadecimal digits with hyphens between the groups. The entire GUID can optionally be enclosed in matching braces or parentheses: - - dddddddd-dddd-dddd-dddd-dddddddddddd - - -or- - - {dddddddd-dddd-dddd-dddd-dddddddddddd} - - -or- - - (dddddddd-dddd-dddd-dddd-dddddddddddd) - - -or- - - Groups of 8, 4, and 4 hexadecimal digits, and a subset of eight groups of 2 hexadecimal digits, with each group prefixed by "0x" or "0X", and separated by commas. The entire GUID, as well as the subset, is enclosed in matching braces: - - {0xdddddddd, 0xdddd, 0xdddd,{0xdd,0xdd,0xdd,0xdd,0xdd,0xdd,0xdd,0xdd}} - - All braces, commas, and "0x" prefixes are required. All embedded spaces are ignored. All leading zeros in a group are ignored. - + A string that contains a GUID in one of the following formats ("d" represents a hexadecimal digit whose case is ignored): + + 32 contiguous hexadecimal digits: + + dddddddddddddddddddddddddddddddd + + -or- + + Groups of 8, 4, 4, 4, and 12 hexadecimal digits with hyphens between the groups. The entire GUID can optionally be enclosed in matching braces or parentheses: + + dddddddd-dddd-dddd-dddd-dddddddddddd + + -or- + + {dddddddd-dddd-dddd-dddd-dddddddddddd} + + -or- + + (dddddddd-dddd-dddd-dddd-dddddddddddd) + + -or- + + Groups of 8, 4, and 4 hexadecimal digits, and a subset of eight groups of 2 hexadecimal digits, with each group prefixed by "0x" or "0X", and separated by commas. The entire GUID, as well as the subset, is enclosed in matching braces: + + {0xdddddddd, 0xdddd, 0xdddd,{0xdd,0xdd,0xdd,0xdd,0xdd,0xdd,0xdd,0xdd}} + + All braces, commas, and "0x" prefixes are required. All embedded spaces are ignored. All leading zeros in a group are ignored. + The hexadecimal digits shown in a group are the maximum number of meaningful hexadecimal digits that can appear in that group. You can specify from 1 to the number of hexadecimal digits shown for a group. The specified digits are assumed to be the low-order digits of the group. Initializes a new instance of the structure by using the value represented by the specified string. - constructor. - - :::code language="csharp" source="~/snippets/csharp/System/Guid/.ctor/ctor1.cs" interactive="try-dotnet-method" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/Guid/.ctor/ctor1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.guid.ctor/vb/ctor1.vb" id="Snippet1"::: - + constructor. + + :::code language="csharp" source="~/snippets/csharp/System/Guid/.ctor/ctor1.cs" interactive="try-dotnet-method" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/System/Guid/.ctor/ctor1.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.guid.ctor/vb/ctor1.vb" id="Snippet1"::: + ]]> @@ -412,11 +412,11 @@ The remaining 8 bytes of the GUID. Initializes a new instance of the structure by using the specified integers and byte array. - that corresponds to "00000001-0002-0003-0001-020304050607". - + that corresponds to "00000001-0002-0003-0001-020304050607". + ]]> @@ -487,20 +487,20 @@ The next byte of the GUID. Initializes a new instance of the structure by using the specified integers and bytes. - @@ -571,11 +571,11 @@ The next byte of the GUID. Initializes a new instance of the structure by using the specified unsigned integers and bytes. - @@ -639,54 +639,54 @@ An object to compare to this instance. Compares this instance to a specified object and returns an indication of their relative values. - A signed number indicating the relative values of this instance and . - - Return value - - Description - - A negative integer - - This instance is less than . - - Zero - - This instance is equal to . - - A positive integer - - This instance is greater than . - + A signed number indicating the relative values of this instance and . + + Return value + + Description + + A negative integer + + This instance is less than . + + Zero + + This instance is equal to . + + A positive integer + + This instance is greater than . + - method compares the GUIDs as if they were values provided to the constructor, as follows: - -- It compares the values, and returns a result if they are unequal. If they are equal, it performs the next comparison. - -- It compares the first values, and returns a result if they are unequal. If they are equal, it performs the next comparison. - -- It compares the second values, and returns a result if they are unequal. If they are equal, it performs the next comparison. - -- If performs a byte-by-byte comparison of the next eight values. When it encounters the first unequal pair, it returns the result. Otherwise, it returns 0 to indicate that the two values are equal. - - Note that the final eight bytes appear in the string representation of a in reverse order, from low byte to high byte. For example, in the string representation of the value "01e75c83-c6f5-4192-b57e-7427cec5560d", the final eight bytes are "b57e-7427cec5560d." In other words, the final eight bytes are compared on a byte-by-byte basis from left to right starting with 0xb5. - - If two GUIDs have equal values for a component, the method compares the next component. When it finds a component whose values are unequal, it returns the result. - - This method implements the interface and performs slightly better than the method because it does not have to convert the `value` parameter to a value. - - - -## Examples - The following example calls the method to compare a GUID value with two similar GUID values. - - :::code language="csharp" source="~/snippets/csharp/System/Guid/CompareTo/compareto2.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/Guid/CompareTo/compareto2.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.guid.compareto/vb/compareto2.vb" id="Snippet1"::: - + method compares the GUIDs as if they were values provided to the constructor, as follows: + +- It compares the values, and returns a result if they are unequal. If they are equal, it performs the next comparison. + +- It compares the first values, and returns a result if they are unequal. If they are equal, it performs the next comparison. + +- It compares the second values, and returns a result if they are unequal. If they are equal, it performs the next comparison. + +- If performs a byte-by-byte comparison of the next eight values. When it encounters the first unequal pair, it returns the result. Otherwise, it returns 0 to indicate that the two values are equal. + + Note that the final eight bytes appear in the string representation of a in reverse order, from low byte to high byte. For example, in the string representation of the value "01e75c83-c6f5-4192-b57e-7427cec5560d", the final eight bytes are "b57e-7427cec5560d." In other words, the final eight bytes are compared on a byte-by-byte basis from left to right starting with 0xb5. + + If two GUIDs have equal values for a component, the method compares the next component. When it finds a component whose values are unequal, it returns the result. + + This method implements the interface and performs slightly better than the method because it does not have to convert the `value` parameter to a value. + + + +## Examples + The following example calls the method to compare a GUID value with two similar GUID values. + + :::code language="csharp" source="~/snippets/csharp/System/Guid/CompareTo/compareto2.cs" interactive="try-dotnet" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/System/Guid/CompareTo/compareto2.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.guid.compareto/vb/compareto2.vb" id="Snippet1"::: + ]]> @@ -736,59 +736,59 @@ System.Int32 - + An object to compare, or . Compares this instance to a specified object and returns an indication of their relative values. - A signed number indicating the relative values of this instance and . - - Return 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 signed number indicating the relative values of this instance and . + + Return 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 . + - ; otherwise, an exception is thrown. Any instance of , regardless of its value, is considered greater than `null`. - - The method compares the GUIDs as if they were values provided to the constructor, as follows: - -- It compares the values, and returns a result if they are unequal. If they are equal, it performs the next comparison. - -- It compares the first values, and returns a result if they are unequal. If they are equal, it performs the next comparison. - -- It compares the second values, and returns a result if they are unequal. If they are equal, it performs the next comparison. - -- If performs a byte-by-byte comparison of the next eight values. When it encounters the first unequal pair, it returns the result. Otherwise, it returns 0 to indicate that the two values are equal. - - If two GUIDs have equal values for a component, the method compares the next component. When it finds a component whose values are unequal, it returns the result. - - Note that the final eight bytes appear in the string representation of a in reverse order, from low byte to high byte. For example, in the string representation of the value "01e75c83-c6f5-4192-b57e-7427cec5560d", the final eight bytes are "b57e-7427cec5560d." - - - -## Examples - The following example uses the attribute to assign a GUID to a class. It retrieves the value of this GUID by calling the method and passing the property of the returned object to the method. Then it compares that GUID with an array of values. - - :::code language="csharp" source="~/snippets/csharp/System/Guid/CompareTo/compareto1.cs" interactive="try-dotnet" id="Snippet2"::: - :::code language="fsharp" source="~/snippets/fsharp/System/Guid/CompareTo/compareto1.fs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.guid.compareto/vb/compareto1.vb" id="Snippet2"::: - + ; otherwise, an exception is thrown. Any instance of , regardless of its value, is considered greater than `null`. + + The method compares the GUIDs as if they were values provided to the constructor, as follows: + +- It compares the values, and returns a result if they are unequal. If they are equal, it performs the next comparison. + +- It compares the first values, and returns a result if they are unequal. If they are equal, it performs the next comparison. + +- It compares the second values, and returns a result if they are unequal. If they are equal, it performs the next comparison. + +- If performs a byte-by-byte comparison of the next eight values. When it encounters the first unequal pair, it returns the result. Otherwise, it returns 0 to indicate that the two values are equal. + + If two GUIDs have equal values for a component, the method compares the next component. When it finds a component whose values are unequal, it returns the result. + + Note that the final eight bytes appear in the string representation of a in reverse order, from low byte to high byte. For example, in the string representation of the value "01e75c83-c6f5-4192-b57e-7427cec5560d", the final eight bytes are "b57e-7427cec5560d." + + + +## Examples + The following example uses the attribute to assign a GUID to a class. It retrieves the value of this GUID by calling the method and passing the property of the returned object to the method. Then it compares that GUID with an array of values. + + :::code language="csharp" source="~/snippets/csharp/System/Guid/CompareTo/compareto1.cs" interactive="try-dotnet" id="Snippet2"::: + :::code language="fsharp" source="~/snippets/fsharp/System/Guid/CompareTo/compareto1.fs" id="Snippet2"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.guid.compareto/vb/compareto1.vb" id="Snippet2"::: + ]]> @@ -836,15 +836,15 @@ A read-only instance of the structure whose value is all zeros. - field to determine whether a GUID is non-zero. The following example uses the operator to compare two GUID values with to determine whether they consist exclusively of zeros. - - :::code language="csharp" source="~/snippets/csharp/System/Guid/Empty/empty.cs" interactive="try-dotnet-method" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/Guid/Empty/empty.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.guid.empty/vb/empty.vb" id="Snippet1"::: - + field to determine whether a GUID is non-zero. The following example uses the operator to compare two GUID values with to determine whether they consist exclusively of zeros. + + :::code language="csharp" source="~/snippets/csharp/System/Guid/Empty/empty.cs" interactive="try-dotnet-method" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/System/Guid/Empty/empty.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.guid.empty/vb/empty.vb" id="Snippet1"::: + ]]> @@ -911,13 +911,13 @@ if is equal to this instance; otherwise, . - objects are equal if they have identical byte values. - - This method performs slightly better than the method because it does not have to box the `g` parameter. - + objects are equal if they have identical byte values. + + This method performs slightly better than the method because it does not have to box the `g` parameter. + ]]> @@ -985,11 +985,11 @@ if is a that has the same value as this instance; otherwise, . - objects are equal if they have identical byte values. - + objects are equal if they have identical byte values. + ]]> @@ -1088,26 +1088,26 @@ Initializes a new instance of the structure. A new GUID object. - . The method creates a Version 4 Universally Unique Identifier (UUID) as described in [RFC 4122, Sec. 4.4](https://datatracker.ietf.org/doc/html/rfc4122#section-4.4). The returned is guaranteed to not equal . - - On Windows, this function wraps a call to the [CoCreateGuid](/windows/win32/api/combaseapi/nf-combaseapi-cocreateguid) function. The generated GUID contains 122 bits of strong entropy. - - On non-Windows platforms, starting with .NET 6, this function calls the OS's underlying cryptographically secure pseudo-random number generator (CSPRNG) to generate 122 bits of strong entropy. In previous versions of .NET, the entropy is not guaranteed to be generated by a CSPRNG. - - It is recommended that applications __not__ use the _NewGuid_ method for cryptographic purposes. First, since a Version 4 UUID has a partially predictable bit pattern, the _NewGuid_ function cannot serve as a proper cryptographic pseudo-random function (PRF). If the output of _NewGuid_ is given to a cryptographic component which requires its input to be generated by a proper PRF, the cryptographic component may not be able to maintain its security properties. Second, _NewGuid_ utilizes at most 122 bits of entropy, regardless of platform. Some cryptographic components set a minimum entropy level on their inputs as a matter of policy. Such policies often set the minimum entropy level at 128 bits or higher. Passing the output of _NewGuid_ to such a routine may violate its policy. - - If an application requires random data for cryptographic purposes, consider using a static method on the class. That class provides a random number generator suitable for cryptographic use. - -## Examples - The following code example creates and displays the values of two objects. - - :::code language="csharp" source="~/snippets/csharp/System/Guid/NewGuid/ng.cs" interactive="try-dotnet-method" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/Guid/NewGuid/ng.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.guid.newguid/vb/ng.vb" id="Snippet1"::: - + . The method creates a Version 4 Universally Unique Identifier (UUID) as described in [RFC 4122, Sec. 4.4](https://datatracker.ietf.org/doc/html/rfc4122#section-4.4). The returned is guaranteed to not equal . + + On Windows, this function wraps a call to the [CoCreateGuid](/windows/win32/api/combaseapi/nf-combaseapi-cocreateguid) function. The generated GUID contains 122 bits of strong entropy. + + On non-Windows platforms, starting with .NET 6, this function calls the OS's underlying cryptographically secure pseudo-random number generator (CSPRNG) to generate 122 bits of strong entropy. In previous versions of .NET, the entropy is not guaranteed to be generated by a CSPRNG. + + It is recommended that applications __not__ use the _NewGuid_ method for cryptographic purposes. First, since a Version 4 UUID has a partially predictable bit pattern, the _NewGuid_ function cannot serve as a proper cryptographic pseudo-random function (PRF). If the output of _NewGuid_ is given to a cryptographic component which requires its input to be generated by a proper PRF, the cryptographic component may not be able to maintain its security properties. Second, _NewGuid_ utilizes at most 122 bits of entropy, regardless of platform. Some cryptographic components set a minimum entropy level on their inputs as a matter of policy. Such policies often set the minimum entropy level at 128 bits or higher. Passing the output of _NewGuid_ to such a routine may violate its policy. + + If an application requires random data for cryptographic purposes, consider using a static method on the class. That class provides a random number generator suitable for cryptographic use. + +## Examples + The following code example creates and displays the values of two objects. + + :::code language="csharp" source="~/snippets/csharp/System/Guid/NewGuid/ng.cs" interactive="try-dotnet-method" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/System/Guid/NewGuid/ng.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.guid.newguid/vb/ng.vb" id="Snippet1"::: + ]]> @@ -1161,15 +1161,15 @@ if and are equal; otherwise, . - - -## Examples - The following example uses the operator to compare two GUID values with to determine whether they consist exclusively of zeros. - - :::code language="csharp" source="~/snippets/csharp/System/Guid/Empty/empty.cs" interactive="try-dotnet-method" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/Guid/Empty/empty.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.guid.empty/vb/empty.vb" id="Snippet1"::: - + + +## Examples + The following example uses the operator to compare two GUID values with to determine whether they consist exclusively of zeros. + + :::code language="csharp" source="~/snippets/csharp/System/Guid/Empty/empty.cs" interactive="try-dotnet-method" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/System/Guid/Empty/empty.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.guid.empty/vb/empty.vb" id="Snippet1"::: + ]]> @@ -1411,37 +1411,37 @@ Converts a read-only character span that represents a GUID to the equivalent structure. A structure that contains the value that was parsed. - method trims any leading or trailing white space characters from `input` and converts the remaining characters in `input` to a value. This method can convert a character span that represents any of the five formats produced by the methods, as shown in the following table. - -|Specifier|Description|Format| -|---------------|-----------------|------------| -|`N`|32 hexadecimal digits|00000000000000000000000000000000| -|`D`|32 hexadecimal digits separated by hyphens|00000000-0000-0000-0000-000000000000| -|`B`|32 hexadecimal digits separated by hyphens, enclosed in braces|{00000000-0000-0000-0000-000000000000}| -|`P`|32 hexadecimal digits separated by hyphens, enclosed in parentheses|(00000000-0000-0000-0000-000000000000)| -|`X`|Four hexadecimal values enclosed in braces, where the fourth value is a subset of eight hexadecimal values that is also enclosed in braces|{0x00000000,0x0000,0x0000,{0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00}}| - -The method throws a if it is unable to successfully parse the string. Some of the reasons why this might occur include: - -- `input` contains characters that are not part of the hexadecimal character set. - -- `input` has too many or too few characters. - -- `input` is not in one of the formats recognized by the method and listed in the previous table. - -Use the method to catch any unsuccessful parse operations without having to handle an exception. - + method trims any leading or trailing white space characters from `input` and converts the remaining characters in `input` to a value. This method can convert a character span that represents any of the five formats produced by the methods, as shown in the following table. + +|Specifier|Description|Format| +|---------------|-----------------|------------| +|`N`|32 hexadecimal digits|00000000000000000000000000000000| +|`D`|32 hexadecimal digits separated by hyphens|00000000-0000-0000-0000-000000000000| +|`B`|32 hexadecimal digits separated by hyphens, enclosed in braces|{00000000-0000-0000-0000-000000000000}| +|`P`|32 hexadecimal digits separated by hyphens, enclosed in parentheses|(00000000-0000-0000-0000-000000000000)| +|`X`|Four hexadecimal values enclosed in braces, where the fourth value is a subset of eight hexadecimal values that is also enclosed in braces|{0x00000000,0x0000,0x0000,{0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00}}| + +The method throws a if it is unable to successfully parse the string. Some of the reasons why this might occur include: + +- `input` contains characters that are not part of the hexadecimal character set. + +- `input` has too many or too few characters. + +- `input` is not in one of the formats recognized by the method and listed in the previous table. + +Use the method to catch any unsuccessful parse operations without having to handle an exception. + ]]> - is not in a recognized format. - --or- - + is not in a recognized format. + +-or- + After trimming, the length of the read-only character span is 0. @@ -1495,36 +1495,36 @@ After trimming, the length of the read-only character span is 0. Converts the string representation of a GUID to the equivalent structure. A structure that contains the value that was parsed. - method trims any leading or trailing white space from `input` and converts the string representation of a GUID to a value. This method can convert strings in any of the five formats produced by the and methods, as shown in the following table. - -|Specifier|Description|Format| -|---------------|-----------------|------------| -|`N`|32 hexadecimal digits|00000000000000000000000000000000| -|`D`|32 hexadecimal digits separated by hyphens|00000000-0000-0000-0000-000000000000| -|`B`|32 hexadecimal digits separated by hyphens, enclosed in braces|{00000000-0000-0000-0000-000000000000}| -|`P`|32 hexadecimal digits separated by hyphens, enclosed in parentheses|(00000000-0000-0000-0000-000000000000)| -|`X`|Four hexadecimal values enclosed in braces, where the fourth value is a subset of eight hexadecimal values that is also enclosed in braces|{0x00000000,0x0000,0x0000,{0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00}}| - - The method throws a if it is unable to successfully parse the string. Some of the reasons why this might occur include: - -- `input` contains characters that are not part of the hexadecimal character set. - -- `input` has too many or too few characters. - -- `input` is not in one of the formats recognized by the method and listed in the previous table. - - Use the method to catch any unsuccessful parse operations without having to handle an exception. - -## Examples - The following example creates a new GUID, converts it to three separate string representations by calling the method with the "B", "D", and "X" format specifiers, and then calls the method to convert the strings back to values. - - :::code language="csharp" source="~/snippets/csharp/System/Guid/Parse/parseex1.cs" interactive="try-dotnet-method" id="Snippet3"::: - :::code language="fsharp" source="~/snippets/fsharp/System/Guid/Parse/parseex1.fs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.guid.parse/vb/parseex1.vb" id="Snippet3"::: - + method trims any leading or trailing white space from `input` and converts the string representation of a GUID to a value. This method can convert strings in any of the five formats produced by the and methods, as shown in the following table. + +|Specifier|Description|Format| +|---------------|-----------------|------------| +|`N`|32 hexadecimal digits|00000000000000000000000000000000| +|`D`|32 hexadecimal digits separated by hyphens|00000000-0000-0000-0000-000000000000| +|`B`|32 hexadecimal digits separated by hyphens, enclosed in braces|{00000000-0000-0000-0000-000000000000}| +|`P`|32 hexadecimal digits separated by hyphens, enclosed in parentheses|(00000000-0000-0000-0000-000000000000)| +|`X`|Four hexadecimal values enclosed in braces, where the fourth value is a subset of eight hexadecimal values that is also enclosed in braces|{0x00000000,0x0000,0x0000,{0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00}}| + + The method throws a if it is unable to successfully parse the string. Some of the reasons why this might occur include: + +- `input` contains characters that are not part of the hexadecimal character set. + +- `input` has too many or too few characters. + +- `input` is not in one of the formats recognized by the method and listed in the previous table. + + Use the method to catch any unsuccessful parse operations without having to handle an exception. + +## Examples + The following example creates a new GUID, converts it to three separate string representations by calling the method with the "B", "D", and "X" format specifiers, and then calls the method to convert the strings back to values. + + :::code language="csharp" source="~/snippets/csharp/System/Guid/Parse/parseex1.cs" interactive="try-dotnet-method" id="Snippet3"::: + :::code language="fsharp" source="~/snippets/fsharp/System/Guid/Parse/parseex1.fs" id="Snippet3"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.guid.parse/vb/parseex1.vb" id="Snippet3"::: + ]]> @@ -1678,20 +1678,20 @@ After trimming, the length of the read-only character span is 0. Converts the character span representation of a GUID to the equivalent structure, provided that the string is in the specified format. A structure that contains the value that was parsed. - method requires the read-only character span to convert to be exactly in the format specified by the `format` parameter, after leading and trailing white-space characters are removed. The following table shows the accepted format specifiers for the `format` parameter. "0" represents a digit; hyphens ("-"), braces ("{", "}"), and parentheses ("(", ")") appear as shown. - -|Specifier|Format of the `input` parameter| -|---------------|-------------------------------------| -|N|32 hexadecimal digits:

00000000000000000000000000000000| -|D|32 hexadecimal digits separated by hyphens:

00000000-0000-0000-0000-000000000000| -|B|32 hexadecimal digits separated by hyphens, enclosed in braces:

{00000000-0000-0000-0000-000000000000}| -|P|32 hexadecimal digits separated by hyphens, enclosed in parentheses:

(00000000-0000-0000-0000-000000000000)| -|X|Four hexadecimal values enclosed in braces, where the fourth value is a subset of eight hexadecimal values that is also enclosed in braces:

{0x00000000,0x0000,0x0000,{0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00}}| - + method requires the read-only character span to convert to be exactly in the format specified by the `format` parameter, after leading and trailing white-space characters are removed. The following table shows the accepted format specifiers for the `format` parameter. "0" represents a digit; hyphens ("-"), braces ("{", "}"), and parentheses ("(", ")") appear as shown. + +|Specifier|Format of the `input` parameter| +|---------------|-------------------------------------| +|N|32 hexadecimal digits:

00000000000000000000000000000000| +|D|32 hexadecimal digits separated by hyphens:

00000000-0000-0000-0000-000000000000| +|B|32 hexadecimal digits separated by hyphens, enclosed in braces:

{00000000-0000-0000-0000-000000000000}| +|P|32 hexadecimal digits separated by hyphens, enclosed in parentheses:

(00000000-0000-0000-0000-000000000000)| +|X|Four hexadecimal values enclosed in braces, where the fourth value is a subset of eight hexadecimal values that is also enclosed in braces:

{0x00000000,0x0000,0x0000,{0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00}}| + ]]>
@@ -1755,26 +1755,26 @@ The method requires the read-only character spa Converts the string representation of a GUID to the equivalent structure, provided that the string is in the specified format. A structure that contains the value that was parsed. - method requires the string to convert to be exactly in the format specified by the `format` parameter, after leading and trailing white-space characters are removed. The following table shows the accepted format specifiers for the `format` parameter. "0" represents a digit; hyphens ("-"), braces ("{", "}"), and parentheses ("(", ")") appear as shown. - -|Specifier|Format of the `input` parameter| -|---------------|-------------------------------------| -|N|32 hexadecimal digits:

00000000000000000000000000000000| -|D|32 hexadecimal digits separated by hyphens:

00000000-0000-0000-0000-000000000000| -|B|32 hexadecimal digits separated by hyphens, enclosed in braces:

{00000000-0000-0000-0000-000000000000}| -|P|32 hexadecimal digits separated by hyphens, enclosed in parentheses:

(00000000-0000-0000-0000-000000000000)| -|X|Four hexadecimal values enclosed in braces, where the fourth value is a subset of eight hexadecimal values that is also enclosed in braces:

{0x00000000,0x0000,0x0000,{0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00}}| - -## Examples - The following example calls the method with each of the supported format specifiers to generate an array of strings that represent a single GUID. These are then passed to the method, which successfully parses only the string that conforms to the "B" format specifier. - - :::code language="csharp" source="~/snippets/csharp/System/Guid/Parse/parseexactex1.cs" interactive="try-dotnet-method" id="Snippet4"::: - :::code language="fsharp" source="~/snippets/fsharp/System/Guid/Parse/parseexactex1.fs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.guid.parse/vb/parseexactex1.vb" id="Snippet4"::: - + method requires the string to convert to be exactly in the format specified by the `format` parameter, after leading and trailing white-space characters are removed. The following table shows the accepted format specifiers for the `format` parameter. "0" represents a digit; hyphens ("-"), braces ("{", "}"), and parentheses ("(", ")") appear as shown. + +|Specifier|Format of the `input` parameter| +|---------------|-------------------------------------| +|N|32 hexadecimal digits:

00000000000000000000000000000000| +|D|32 hexadecimal digits separated by hyphens:

00000000-0000-0000-0000-000000000000| +|B|32 hexadecimal digits separated by hyphens, enclosed in braces:

{00000000-0000-0000-0000-000000000000}| +|P|32 hexadecimal digits separated by hyphens, enclosed in parentheses:

(00000000-0000-0000-0000-000000000000)| +|X|Four hexadecimal values enclosed in braces, where the fourth value is a subset of eight hexadecimal values that is also enclosed in braces:

{0x00000000,0x0000,0x0000,{0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00}}| + +## Examples + The following example calls the method with each of the supported format specifiers to generate an array of strings that represent a single GUID. These are then passed to the method, which successfully parses only the string that conforms to the "B" format specifier. + + :::code language="csharp" source="~/snippets/csharp/System/Guid/Parse/parseexactex1.cs" interactive="try-dotnet-method" id="Snippet4"::: + :::code language="fsharp" source="~/snippets/fsharp/System/Guid/Parse/parseexactex1.fs" id="Snippet4"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.guid.parse/vb/parseexactex1.vb" id="Snippet4"::: + ]]>
@@ -1817,28 +1817,28 @@ The method requires the read-only character spa An object to compare to this instance. Compares this instance to a specified object and returns an indication of their relative values. - A signed number indicating the relative values of this instance and . + A signed number indicating the relative values of this instance and . Return valueDescriptionA negative integerThis instance is less than .ZeroThis instance is equal to .A positive integerThis instance is greater than . - instance is cast to an interface. - -The `CompareTo` method compares the GUIDs as if they were values provided to the constructor, as follows: - -- It compares the values, and returns a result if they are unequal. If they are equal, it performs the next comparison. -- It compares the first values, and returns a result if they are unequal. If they are equal, it performs the next comparison. -- It compares the second values, and returns a result if they are unequal. If they are equal, it performs the next comparison. -- If performs a byte-by-byte comparison of the next eight values. When it encounters the first unequal pair, it returns the result. Otherwise, it returns 0 to indicate that the two values are equal. - -Note that the final eight bytes appear in the string representation of a in reverse order, from low byte to high byte. For example, in the string representation of the value "01e75c83-c6f5-4192-b57e-7427cec5560d", the final eight bytes are "b57e-7427cec5560d." In other words, the final eight bytes are compared on a byte-by-byte basis from left to right starting with 0xb5. - -If two GUIDs have equal values for a component, the method compares the next component. When it finds a component whose values are unequal, it returns the result. - -This method implements the interface and performs slightly better than the method because it does not have to convert the `value` parameter to a value. - + instance is cast to an interface. + +The `CompareTo` method compares the GUIDs as if they were values provided to the constructor, as follows: + +- It compares the values, and returns a result if they are unequal. If they are equal, it performs the next comparison. +- It compares the first values, and returns a result if they are unequal. If they are equal, it performs the next comparison. +- It compares the second values, and returns a result if they are unequal. If they are equal, it performs the next comparison. +- If performs a byte-by-byte comparison of the next eight values. When it encounters the first unequal pair, it returns the result. Otherwise, it returns 0 to indicate that the two values are equal. + +Note that the final eight bytes appear in the string representation of a in reverse order, from low byte to high byte. For example, in the string representation of the value "01e75c83-c6f5-4192-b57e-7427cec5560d", the final eight bytes are "b57e-7427cec5560d." In other words, the final eight bytes are compared on a byte-by-byte basis from left to right starting with 0xb5. + +If two GUIDs have equal values for a component, the method compares the next component. When it finds a component whose values are unequal, it returns the result. + +This method implements the interface and performs slightly better than the method because it does not have to convert the `value` parameter to a value. + ]]> @@ -1880,26 +1880,26 @@ This method implements the Returns a string representation of the value of this instance, according to the provided format specifier and culture-specific format information. The value of this represented as a series of lowercase hexadecimal digits in the specified format. -
00000000000000000000000000000000| -|`D`|32 digits separated by hyphens:

00000000-0000-0000-0000-000000000000| -|`B`|32 digits separated by hyphens, enclosed in braces:

{00000000-0000-0000-0000-000000000000}| -|`P`|32 digits separated by hyphens, enclosed in parentheses:

(00000000-0000-0000-0000-000000000000)| -|`X`|Four hexadecimal values enclosed in braces, where the fourth value is a subset of eight hexadecimal values that is also enclosed in braces:

{0x00000000,0x0000,0x0000,{0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00}}| - -The hexadecimal digits a through f are lowercase in the returned string. To convert them to uppercase, call the method on the returned string. - -Because the `provider` parameter is ignored, you cannot use it to provide a custom formatting solution. To represent a value as a string in a format that isn't supported by the standard GUID format strings, call the method with a `provider` object that implements both the and interfaces. For more information, see the ["Custom Formatting with ICustomFormatter"](/dotnet/standard/base-types/formatting-types#custom-formatting-with-icustomformatter) section in the [Formatting Types](/dotnet/standard/base-types/formatting-types) article. - +
00000000000000000000000000000000| +|`D`|32 digits separated by hyphens:

00000000-0000-0000-0000-000000000000| +|`B`|32 digits separated by hyphens, enclosed in braces:

{00000000-0000-0000-0000-000000000000}| +|`P`|32 digits separated by hyphens, enclosed in parentheses:

(00000000-0000-0000-0000-000000000000)| +|`X`|Four hexadecimal values enclosed in braces, where the fourth value is a subset of eight hexadecimal values that is also enclosed in braces:

{0x00000000,0x0000,0x0000,{0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00}}| + +The hexadecimal digits a through f are lowercase in the returned string. To convert them to uppercase, call the method on the returned string. + +Because the `provider` parameter is ignored, you cannot use it to provide a custom formatting solution. To represent a value as a string in a format that isn't supported by the standard GUID format strings, call the method with a `provider` object that implements both the and interfaces. For more information, see the ["Custom Formatting with ICustomFormatter"](/dotnet/standard/base-types/formatting-types#custom-formatting-with-icustomformatter) section in the [Formatting Types](/dotnet/standard/base-types/formatting-types) article. + ]]>
The value of is not null, an empty string (""), or one of the following single format specifiers:"N", "D", "B", "P", or "X". @@ -2054,22 +2054,22 @@ Because the `provider` parameter is ignored, you cannot use it to provide a cust Returns a 16-element byte array that contains the value of this instance. A 16-element byte array. - value by calling the constructor. - - Note that the order of bytes in the returned byte array is different from the string representation of a value. The order of the beginning four-byte group and the next two two-byte groups is reversed, whereas the order of the last two-byte group and the closing six-byte group is the same. The example provides an illustration. - - - -## Examples - The following example calls the method to create a value, and then calls the method to represent the value as a byte array. It then displays both values to the console. Finally, it instantiates a new value from the byte array and calls its method to show that the two values are identical. - - :::code language="csharp" source="~/snippets/csharp/System/Guid/ToByteArray/tobytearray3.cs" interactive="try-dotnet-method" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/Guid/ToByteArray/tobytearray3.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.guid.tobytearray/vb/tobytearray3.vb" id="Snippet1"::: - + value by calling the constructor. + + Note that the order of bytes in the returned byte array is different from the string representation of a value. The order of the beginning four-byte group and the next two two-byte groups is reversed, whereas the order of the last two-byte group and the closing six-byte group is the same. The example provides an illustration. + + + +## Examples + The following example calls the method to create a value, and then calls the method to represent the value as a byte array. It then displays both values to the console. Finally, it instantiates a new value from the byte array and calls its method to show that the two values are identical. + + :::code language="csharp" source="~/snippets/csharp/System/Guid/ToByteArray/tobytearray3.cs" interactive="try-dotnet-method" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/System/Guid/ToByteArray/tobytearray3.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.guid.tobytearray/vb/tobytearray3.vb" id="Snippet1"::: + ]]> @@ -2172,17 +2172,17 @@ Because the `provider` parameter is ignored, you cannot use it to provide a cust Returns a string representation of the value of this instance in registry format. - The value of this , formatted by using the "D" format specifier as follows: - - xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx - + The value of this , formatted by using the "D" format specifier as follows: + + xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx + where the value of the GUID is represented as a series of lowercase hexadecimal digits in groups of 8, 4, 4, 4, and 12 digits and separated by hyphens. An example of a return value is "382c74c3-721d-4f34-80e5-57657b6cbc27". To convert the hexadecimal digits from a through f to uppercase, call the method on the returned string. - @@ -2251,21 +2251,21 @@ Because the `provider` parameter is ignored, you cannot use it to provide a cust Returns a string representation of the value of this instance, according to the provided format specifier. The value of this , represented as a series of lowercase hexadecimal digits in the specified format. -
00000000000000000000000000000000| -|`D`|32 digits separated by hyphens:

00000000-0000-0000-0000-000000000000| -|`B`|32 digits separated by hyphens, enclosed in braces:

{00000000-0000-0000-0000-000000000000}| -|`P`|32 digits separated by hyphens, enclosed in parentheses:

(00000000-0000-0000-0000-000000000000)| -|`X`|Four hexadecimal values enclosed in braces, where the fourth value is a subset of eight hexadecimal values that is also enclosed in braces:

{0x00000000,0x0000,0x0000,{0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00}}| - - The hexadecimal digits a through f are lowercase in the returned string. To convert them to uppercase, call the method on the returned string. - +
00000000000000000000000000000000| +|`D`|32 digits separated by hyphens:

00000000-0000-0000-0000-000000000000| +|`B`|32 digits separated by hyphens, enclosed in braces:

{00000000-0000-0000-0000-000000000000}| +|`P`|32 digits separated by hyphens, enclosed in parentheses:

(00000000-0000-0000-0000-000000000000)| +|`X`|Four hexadecimal values enclosed in braces, where the fourth value is a subset of eight hexadecimal values that is also enclosed in braces:

{0x00000000,0x0000,0x0000,{0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00}}| + + The hexadecimal digits a through f are lowercase in the returned string. To convert them to uppercase, call the method on the returned string. + ]]>
The value of is not , an empty string (""), "N", "D", "B", "P", or "X". @@ -2320,7 +2320,7 @@ Because the `provider` parameter is ignored, you cannot use it to provide a cust System.String - + [System.Diagnostics.CodeAnalysis.StringSyntax("GuidFormat")] @@ -2328,7 +2328,7 @@ Because the `provider` parameter is ignored, you cannot use it to provide a cust - + A single format specifier that indicates how to format the value of this . The parameter can be "N", "D", "B", "P", or "X". If is or an empty string (""), "D" is used. @@ -2336,25 +2336,25 @@ Because the `provider` parameter is ignored, you cannot use it to provide a cust Returns a string representation of the value of this instance of the class, according to the provided format specifier and culture-specific format information. The value of this , represented as a series of lowercase hexadecimal digits in the specified format. -
00000000000000000000000000000000| -|`D`|32 digits separated by hyphens:

00000000-0000-0000-0000-000000000000| -|`B`|32 digits separated by hyphens, enclosed in braces:

{00000000-0000-0000-0000-000000000000}| -|`P`|32 digits separated by hyphens, enclosed in parentheses:

(00000000-0000-0000-0000-000000000000)| -|`X`|Four hexadecimal values enclosed in braces, where the fourth value is a subset of eight hexadecimal values that is also enclosed in braces:

{0x00000000,0x0000,0x0000,{0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00}}| - - The hexadecimal digits a through f are lowercase in the returned string. To convert them to uppercase, call the method on the returned string. - - Because the `provider` parameter is ignored, you cannot use it to provide a custom formatting solution. To represent a value as a string in a format that isn't supported by the standard GUID format strings, call the method with a `provider` object that implements both the and interfaces. For more information, see the "Custom Formatting with ICustomFormatter" section in the [Formatting Types](/dotnet/standard/base-types/formatting-types) article. - +
00000000000000000000000000000000| +|`D`|32 digits separated by hyphens:

00000000-0000-0000-0000-000000000000| +|`B`|32 digits separated by hyphens, enclosed in braces:

{00000000-0000-0000-0000-000000000000}| +|`P`|32 digits separated by hyphens, enclosed in parentheses:

(00000000-0000-0000-0000-000000000000)| +|`X`|Four hexadecimal values enclosed in braces, where the fourth value is a subset of eight hexadecimal values that is also enclosed in braces:

{0x00000000,0x0000,0x0000,{0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00}}| + + The hexadecimal digits a through f are lowercase in the returned string. To convert them to uppercase, call the method on the returned string. + + Because the `provider` parameter is ignored, you cannot use it to provide a custom formatting solution. To represent a value as a string in a format that isn't supported by the standard GUID format strings, call the method with a `provider` object that implements both the and interfaces. For more information, see the "Custom Formatting with ICustomFormatter" section in the [Formatting Types](/dotnet/standard/base-types/formatting-types) article. + ]]>
The value of is not , an empty string (""), "N", "D", "B", "P", or "X". @@ -2553,26 +2553,26 @@ Because the `provider` parameter is ignored, you cannot use it to provide a cust if the parse operation was successful; otherwise, . - method, except that instead of returning the parsed GUID, it returns `false` if `input` is `null` or not in a recognized format, and doesn't throw an exception. It trims any leading or trailing white space from `input` and converts strings in any of the five formats recognized by the and methods, as shown in the following table. - -|Specifier|Description|Format| -|---------------|-----------------|------------| -|`N`|32 digits|00000000000000000000000000000000| -|`D`|32 digits separated by hyphens|00000000-0000-0000-0000-000000000000| -|`B`|32 digits separated by hyphens, enclosed in braces|{00000000-0000-0000-0000-000000000000}| -|`P`|32 digits separated by hyphens, enclosed in parentheses|(00000000-0000-0000-0000-000000000000)| -|`X`|Four hexadecimal values enclosed in braces, where the fourth value is a subset of eight hexadecimal values that is also enclosed in braces|{0x00000000,0x0000,0x0000,{0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00}}| - -## Examples - The following example creates a new GUID, converts it to three separate string representations by calling the method with the "B", "D", and "X" format specifiers, and then calls the method to convert the strings back to values. - - :::code language="csharp" source="~/snippets/csharp/System/Guid/Parse/tryparseex1.cs" interactive="try-dotnet-method" id="Snippet2"::: - :::code language="fsharp" source="~/snippets/fsharp/System/Guid/Parse/tryparseex1.fs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.guid.parse/vb/tryparseex1.vb" id="Snippet2"::: - + method, except that instead of returning the parsed GUID, it returns `false` if `input` is `null` or not in a recognized format, and doesn't throw an exception. It trims any leading or trailing white space from `input` and converts strings in any of the five formats recognized by the and methods, as shown in the following table. + +|Specifier|Description|Format| +|---------------|-----------------|------------| +|`N`|32 digits|00000000000000000000000000000000| +|`D`|32 digits separated by hyphens|00000000-0000-0000-0000-000000000000| +|`B`|32 digits separated by hyphens, enclosed in braces|{00000000-0000-0000-0000-000000000000}| +|`P`|32 digits separated by hyphens, enclosed in parentheses|(00000000-0000-0000-0000-000000000000)| +|`X`|Four hexadecimal values enclosed in braces, where the fourth value is a subset of eight hexadecimal values that is also enclosed in braces|{0x00000000,0x0000,0x0000,{0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00}}| + +## Examples + The following example creates a new GUID, converts it to three separate string representations by calling the method with the "B", "D", and "X" format specifiers, and then calls the method to convert the strings back to values. + + :::code language="csharp" source="~/snippets/csharp/System/Guid/Parse/tryparseex1.cs" interactive="try-dotnet-method" id="Snippet2"::: + :::code language="fsharp" source="~/snippets/fsharp/System/Guid/Parse/tryparseex1.fs" id="Snippet2"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.guid.parse/vb/tryparseex1.vb" id="Snippet2"::: + ]]> @@ -2800,28 +2800,28 @@ Because the `provider` parameter is ignored, you cannot use it to provide a cust if the parse operation was successful; otherwise, . -
00000000000000000000000000000000| -|D|32 digits separated by hyphens:

00000000-0000-0000-0000-000000000000| -|B|32 digits separated by hyphens, enclosed in braces:

{00000000-0000-0000-0000-000000000000}| -|P|32 digits separated by hyphens, enclosed in parentheses:

(00000000-0000-0000-0000-000000000000)| -|X|Four hexadecimal values enclosed in braces, where the fourth value is a subset of eight hexadecimal values that is also enclosed in braces:

{0x00000000,0x0000,0x0000,{0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00}}| - -## Examples - The following example calls the method with each of the supported format specifiers to generate an array of strings that represent a single GUID. These are then passed to the method, which successfully parses the string that conforms to the "B" format specifier. - - :::code language="csharp" source="~/snippets/csharp/System/Guid/Parse/tryparseexactex1.cs" interactive="try-dotnet-method" id="Snippet5"::: - :::code language="fsharp" source="~/snippets/fsharp/System/Guid/Parse/tryparseexactex1.fs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.guid.parse/vb/tryparseexactex1.vb" id="Snippet5"::: - +
00000000000000000000000000000000| +|D|32 digits separated by hyphens:

00000000-0000-0000-0000-000000000000| +|B|32 digits separated by hyphens, enclosed in braces:

{00000000-0000-0000-0000-000000000000}| +|P|32 digits separated by hyphens, enclosed in parentheses:

(00000000-0000-0000-0000-000000000000)| +|X|Four hexadecimal values enclosed in braces, where the fourth value is a subset of eight hexadecimal values that is also enclosed in braces:

{0x00000000,0x0000,0x0000,{0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00}}| + +## Examples + The following example calls the method with each of the supported format specifiers to generate an array of strings that represent a single GUID. These are then passed to the method, which successfully parses the string that conforms to the "B" format specifier. + + :::code language="csharp" source="~/snippets/csharp/System/Guid/Parse/tryparseexactex1.cs" interactive="try-dotnet-method" id="Snippet5"::: + :::code language="fsharp" source="~/snippets/fsharp/System/Guid/Parse/tryparseexactex1.fs" id="Snippet5"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.guid.parse/vb/tryparseexactex1.vb" id="Snippet5"::: + ]]>
diff --git a/xml/System/Int16.xml b/xml/System/Int16.xml index d38f58f2233..4a2a7eba387 100644 --- a/xml/System/Int16.xml +++ b/xml/System/Int16.xml @@ -502,7 +502,7 @@ System.Int32 - + An object to compare, or . diff --git a/xml/System/Int32.xml b/xml/System/Int32.xml index 043eb961ebe..d55142f0b20 100644 --- a/xml/System/Int32.xml +++ b/xml/System/Int32.xml @@ -495,7 +495,7 @@ System.Int32 - + An object to compare, or . diff --git a/xml/System/Int64.xml b/xml/System/Int64.xml index 7a0ecb6461c..e7fb918c02e 100644 --- a/xml/System/Int64.xml +++ b/xml/System/Int64.xml @@ -489,7 +489,7 @@ System.Int32 - + An object to compare, or . diff --git a/xml/System/IntPtr.xml b/xml/System/IntPtr.xml index 1ce86dc676a..4b5d3d8105a 100644 --- a/xml/System/IntPtr.xml +++ b/xml/System/IntPtr.xml @@ -5642,8 +5642,8 @@ This member is an explicit interface member implementation. It can be used only System.Void - - + + The object to populate with data. diff --git a/xml/System/InvalidCastException.xml b/xml/System/InvalidCastException.xml index 3040ffa3474..f42c7534996 100644 --- a/xml/System/InvalidCastException.xml +++ b/xml/System/InvalidCastException.xml @@ -253,8 +253,8 @@ - - + + The object that holds the serialized object data. diff --git a/xml/System/InvalidOperationException.xml b/xml/System/InvalidOperationException.xml index 2049a8a7050..ad91dbcb9f0 100644 --- a/xml/System/InvalidOperationException.xml +++ b/xml/System/InvalidOperationException.xml @@ -254,8 +254,8 @@ - - + + The object that holds the serialized object data. diff --git a/xml/System/InvalidTimeZoneException.xml b/xml/System/InvalidTimeZoneException.xml index 4d341d75ab9..12c5fa4d175 100644 --- a/xml/System/InvalidTimeZoneException.xml +++ b/xml/System/InvalidTimeZoneException.xml @@ -70,21 +70,21 @@ The exception that is thrown when time zone information is invalid. - object contains invalid, incomplete, or missing data. It is thrown by the method when a time zone is found in the registry but contains corrupted data. It can also be thrown by the method under any of the following conditions: - -- The adjustment rules overlap. - -- The adjustment rules contain one or more null elements. - -- The sum of the Coordinated Universal Time (UTC) offset and daylight delta is out of range. (It is either greater than 14 hours or less than -14 hours.) - -- A single date has multiple adjustment rules applied to it. - - This exception is not thrown to indicate that the time zone is not defined on a particular system; the is used for this purpose. - + object contains invalid, incomplete, or missing data. It is thrown by the method when a time zone is found in the registry but contains corrupted data. It can also be thrown by the method under any of the following conditions: + +- The adjustment rules overlap. + +- The adjustment rules contain one or more null elements. + +- The sum of the Coordinated Universal Time (UTC) offset and daylight delta is out of range. (It is either greater than 14 hours or less than -14 hours.) + +- A single date has multiple adjustment rules applied to it. + + This exception is not thrown to indicate that the time zone is not defined on a particular system; the is used for this purpose. + ]]> @@ -142,11 +142,11 @@ Initializes a new instance of the class with a system-supplied message. - class. It initializes the property of the new instance to a system-supplied message that describes the error, such as "Exception of type 'System.InvalidTimeZoneException' was thrown." This message is localized for the current system culture. - + class. It initializes the property of the new instance to a system-supplied message that describes the error, such as "Exception of type 'System.InvalidTimeZoneException' was thrown." This message is localized for the current system culture. + ]]> @@ -196,11 +196,11 @@ A string that describes the exception. Initializes a new instance of the class with the specified message string. - property. It should be localized for the current culture. - + property. It should be localized for the current culture. + ]]> @@ -257,25 +257,25 @@ - - + + The object that contains the serialized data. The stream that contains the serialized data. Initializes a new instance of the class from serialized data. - object. Instead, it is called by the object's method when deserializing the object from a stream. - + object. Instead, it is called by the object's method when deserializing the object from a stream. + ]]> - The parameter is . - - -or- - + The parameter is . + + -or- + The parameter is . @@ -326,21 +326,21 @@ The exception that is the cause of the current exception. Initializes a new instance of the class with a specified error message and a reference to the inner exception that is the cause of this exception. - class to handle an exception in a `try`…`catch` block. The `innerException` parameter should be a reference to the exception object handled in the `catch` block, or it can be `null`. This value is then assigned to the object's property. - - The `message` string is assigned to the property. The string should be localized for the current culture. - - - -## Examples - The following code tries to retrieve a object that represents the Central Standard Time zone. If an occurs in the `RetrieveTimeZone` method call, the exception handler wraps the exception in a new object, which it returns to the caller. The caller's exception handler then displays information about both the outer and inner exceptions. - + class to handle an exception in a `try`…`catch` block. The `innerException` parameter should be a reference to the exception object handled in the `catch` block, or it can be `null`. This value is then assigned to the object's property. + + The `message` string is assigned to the property. The string should be localized for the current culture. + + + +## Examples + The following code tries to retrieve a object that represents the Central Standard Time zone. If an occurs in the `RetrieveTimeZone` method call, the exception handler wraps the exception in a new object, which it returns to the caller. The caller's exception handler then displays information about both the outer and inner exceptions. + :::code language="csharp" source="~/snippets/csharp/System/InvalidTimeZoneException/.ctor/TimeZoneNotFoundException.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.TimeZoneNotFoundException.Class/vb/TimeZoneNotFoundException.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.TimeZoneNotFoundException.Class/vb/TimeZoneNotFoundException.vb" id="Snippet1"::: + ]]> diff --git a/xml/System/MarshalByRefObject.xml b/xml/System/MarshalByRefObject.xml index 3668eaa5669..05761ade537 100644 --- a/xml/System/MarshalByRefObject.xml +++ b/xml/System/MarshalByRefObject.xml @@ -61,45 +61,45 @@ Enables access to objects across application domain boundaries in applications that support remoting. - is the base class for objects that communicate across application domain boundaries by exchanging messages using a proxy. Objects that do not inherit from are implicitly marshal by value. When a remote application references a marshal by value object, a copy of the object is passed across application domain boundaries. - - objects are accessed directly within the boundaries of the local application domain. The first time an application in a remote application domain accesses a , a proxy is passed to the remote application. Subsequent calls on the proxy are marshaled back to the object residing in the local application domain. - - Types must inherit from when the type is used across application domain boundaries, and the state of the object must not be copied because the members of the object are not usable outside the application domain where they were created. - - When you derive an object from for use across application domain boundaries, you should not override any of its members, nor should you call its methods directly. The runtime recognizes that classes derived from should be marshaled across app domain boundaries. - - - -## Examples - This section contains two code examples. The first code example shows how to create an instance of a class in another application domain. The second code example shows a simple class that can be used for remoting. - - **Example 1** - - The following code example shows the simplest way to execute code in another application domain. The example defines a class named `Worker` that inherits , with a method that displays the name of the application domain in which it is executing. The example creates instances of `Worker` in the default application domain and in a new application domain. - + is the base class for objects that communicate across application domain boundaries by exchanging messages using a proxy. Objects that do not inherit from are implicitly marshal by value. When a remote application references a marshal by value object, a copy of the object is passed across application domain boundaries. + + objects are accessed directly within the boundaries of the local application domain. The first time an application in a remote application domain accesses a , a proxy is passed to the remote application. Subsequent calls on the proxy are marshaled back to the object residing in the local application domain. + + Types must inherit from when the type is used across application domain boundaries, and the state of the object must not be copied because the members of the object are not usable outside the application domain where they were created. + + When you derive an object from for use across application domain boundaries, you should not override any of its members, nor should you call its methods directly. The runtime recognizes that classes derived from should be marshaled across app domain boundaries. + + + +## Examples + This section contains two code examples. The first code example shows how to create an instance of a class in another application domain. The second code example shows a simple class that can be used for remoting. + + **Example 1** + + The following code example shows the simplest way to execute code in another application domain. The example defines a class named `Worker` that inherits , with a method that displays the name of the application domain in which it is executing. The example creates instances of `Worker` in the default application domain and in a new application domain. + > [!NOTE] -> The assembly that contains `Worker` must be loaded into both application domains, but it could load other assemblies that would exist only in the new application domain. - +> The assembly that contains `Worker` must be loaded into both application domains, but it could load other assemblies that would exist only in the new application domain. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/CreateInstanceAndUnwrap2/cpp/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System/AppDomain/CreateInstanceAndUnwrap/source.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System/AppDomain/CreateInstanceAndUnwrap/source.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/CreateInstanceAndUnwrap2/VB/source.vb" id="Snippet1"::: - - **Example 2** - - The following example demonstrates a class derived from that is used later in remoting. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/CreateInstanceAndUnwrap2/VB/source.vb" id="Snippet1"::: + + **Example 2** + + The following example demonstrates a class derived from that is used later in remoting. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/RemotingServices.SetObjectUriForMarshal/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System/MarshalByRefObject/Overview/source.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System/MarshalByRefObject/Overview/source.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/RemotingServices.SetObjectUriForMarshal/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/RemotingServices.SetObjectUriForMarshal/VB/source.vb" id="Snippet1"::: + ]]> @@ -170,18 +170,18 @@ System.Runtime.Remoting.ObjRef - + The of the object that the new will reference. Creates an object that contains all the relevant information required to generate a proxy used to communicate with a remote object. Information required to generate a proxy. - method is called by remote object creation methods such as and . In most cases, there is no need to override this method. - + method is called by remote object creation methods such as and . In most cases, there is no need to override this method. + ]]> This instance is not a valid remoting object. @@ -240,14 +240,14 @@ Retrieves the current lifetime service object that controls the lifetime policy for this instance. An object of type used to control the lifetime policy for this instance. - class. - +For more information about lifetime services, see the class. + ]]> The immediate caller does not have infrastructure permission. @@ -303,22 +303,22 @@ For more information about lifetime services, see the Obtains a lifetime service object to control the lifetime policy for this instance. An object of type used to control the lifetime policy for this instance. This is the current lifetime service object for this instance if one exists; otherwise, a new lifetime service object initialized to the value of the property. - class. -## Examples - The following code example demonstrates creating a lease. - +## Examples + The following code example demonstrates creating a lease. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic MarshalByRefObject.InitializeLifetimeService Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System/MarshalByRefObject/InitializeLifetimeService/source.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System/MarshalByRefObject/InitializeLifetimeService/source.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic MarshalByRefObject.InitializeLifetimeService Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic MarshalByRefObject.InitializeLifetimeService Example/VB/source.vb" id="Snippet1"::: + ]]> The immediate caller does not have infrastructure permission. @@ -377,15 +377,15 @@ For more information about lifetime services, see the Creates a shallow copy of the current object. A shallow copy of the current object. - method creates a shallow copy by creating a new object, and then copying the nonstatic fields of the current object to the new object. If a field is a value type, a bit-by-bit copy of the field is performed. If a field is a reference type, the reference is copied but the referred object is not; therefore, the original object and its clone refer to the same object. - - For example, consider a object called X that references objects A and B. Object B, in turn, references object C. A shallow copy of X creates new object X2 that also references objects A and B. In contrast, a deep copy of X creates a new object X2 that references the new objects A2 and B2, which are copies of A and B. B2, in turn, references the new object C2, which is a copy C. Use a class that implements the interface to perform a deep or shallow copy of an object. - - The identity of a object is defined as the remote server object that is the target of a remoting client call. By default, the memberwise clone of a object has the same identity as the original object, which is typically not the correct behavior for clones of server-side objects that are marshaled across a remoting boundary to the client side. Specify `false`, which is usually appropriate, to delete the identity of the clone and cause a new identity to be assigned when the clone is marshaled across a remoting boundary, or `true` to cause the clone to retain the identity of the original object. The method is intended to be used by developers implementing remote server objects. - + method creates a shallow copy by creating a new object, and then copying the nonstatic fields of the current object to the new object. If a field is a value type, a bit-by-bit copy of the field is performed. If a field is a reference type, the reference is copied but the referred object is not; therefore, the original object and its clone refer to the same object. + + For example, consider a object called X that references objects A and B. Object B, in turn, references object C. A shallow copy of X creates new object X2 that also references objects A and B. In contrast, a deep copy of X creates a new object X2 that references the new objects A2 and B2, which are copies of A and B. B2, in turn, references the new object C2, which is a copy C. Use a class that implements the interface to perform a deep or shallow copy of an object. + + The identity of a object is defined as the remote server object that is the target of a remoting client call. By default, the memberwise clone of a object has the same identity as the original object, which is typically not the correct behavior for clones of server-side objects that are marshaled across a remoting boundary to the client side. Specify `false`, which is usually appropriate, to delete the identity of the clone and cause a new identity to be assigned when the clone is marshaled across a remoting boundary, or `true` to cause the clone to retain the identity of the original object. The method is intended to be used by developers implementing remote server objects. + ]]> diff --git a/xml/System/Math.xml b/xml/System/Math.xml index 70638d2f7b7..62c19d608ce 100644 --- a/xml/System/Math.xml +++ b/xml/System/Math.xml @@ -58,16 +58,16 @@ Provides constants and static methods for trigonometric, logarithmic, and other common mathematical functions. - class to calculate the inner angles of a trapezoid. + class to calculate the inner angles of a trapezoid. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/MathSample/CPP/mathsample.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System/Math/Overview/mathsample.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System/Math/Overview/mathsample.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/MathSample/VB/mathsample.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/MathSample/VB/mathsample.vb" id="Snippet1"::: + ]]> @@ -138,19 +138,19 @@ Returns the absolute value of a number. A decimal number, x, such that 0 ≤ x ≤ Decimal.MaxValue. - is its numeric value without its sign. For example, the absolute value of both 1.2 and -1.2 is 1.2. - - - -## Examples - The following example uses the method to get the absolute value of a number of values. - + is its numeric value without its sign. For example, the absolute value of both 1.2 and -1.2 is 1.2. + + + +## Examples + The following example uses the method to get the absolute value of a number of values. + :::code language="csharp" source="~/snippets/csharp/System/Math/Abs/Abs1.cs" interactive="try-dotnet-method" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System/Math/Abs/Abs1.fs" id="Snippet1"::: - + ]]> @@ -209,22 +209,22 @@ Returns the absolute value of a double-precision floating-point number. A double-precision floating-point number, x, such that 0 ≤ x ≤ Double.MaxValue. - is its numeric value without its sign. For example, the absolute value of both 1.2e03 and -1.2e03 is 1.2e03. - - If `value` is equal to or , the return value is . If `value` is equal to , the return value is . - - - -## Examples - The following example uses the method to get the absolute value of a number of values. - + is its numeric value without its sign. For example, the absolute value of both 1.2e03 and -1.2e03 is 1.2e03. + + If `value` is equal to or , the return value is . If `value` is equal to , the return value is . + + + +## Examples + The following example uses the method to get the absolute value of a number of values. + :::code language="csharp" source="~/snippets/csharp/System/Math/Abs/abs2.cs" interactive="try-dotnet-method" id="Snippet2"::: :::code language="fsharp" source="~/snippets/fsharp/System/Math/Abs/abs2.fs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Math.Abs/vb/abs2.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Math.Abs/vb/abs2.vb" id="Snippet2"::: + ]]> @@ -283,20 +283,20 @@ Returns the absolute value of a 16-bit signed integer. A 16-bit signed integer, x, such that 0 ≤ x ≤ Int16.MaxValue. - is its numeric value without its sign. For example, the absolute value of both 123 and -123 is 123. - - - -## Examples - The following example uses the method to get the absolute value of a number of values. - + is its numeric value without its sign. For example, the absolute value of both 123 and -123 is 123. + + + +## Examples + The following example uses the method to get the absolute value of a number of values. + :::code language="csharp" source="~/snippets/csharp/System/Math/Abs/abs3.cs" interactive="try-dotnet-method" id="Snippet3"::: :::code language="fsharp" source="~/snippets/fsharp/System/Math/Abs/abs3.fs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Math.Abs/vb/abs3.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Math.Abs/vb/abs3.vb" id="Snippet3"::: + ]]> @@ -357,20 +357,20 @@ Returns the absolute value of a 32-bit signed integer. A 32-bit signed integer, x, such that 0 ≤ x ≤ Int32.MaxValue. - is its numeric value without its sign. For example, the absolute value of both 123 and -123 is 123. - - - -## Examples - The following example uses the method to get the absolute value of a number of values. - + is its numeric value without its sign. For example, the absolute value of both 123 and -123 is 123. + + + +## Examples + The following example uses the method to get the absolute value of a number of values. + :::code language="csharp" source="~/snippets/csharp/System/Math/Abs/abs4.cs" interactive="try-dotnet-method" id="Snippet4"::: :::code language="fsharp" source="~/snippets/fsharp/System/Math/Abs/abs4.fs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Math.Abs/vb/abs4.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Math.Abs/vb/abs4.vb" id="Snippet4"::: + ]]> @@ -431,20 +431,20 @@ Returns the absolute value of a 64-bit signed integer. A 64-bit signed integer, x, such that 0 ≤ x ≤ Int64.MaxValue. - is its numeric value without its sign. For example, the absolute value of both 123 and -123 is 123. - - - -## Examples - The following example uses the method to get the absolute value of a number of values. - + is its numeric value without its sign. For example, the absolute value of both 123 and -123 is 123. + + + +## Examples + The following example uses the method to get the absolute value of a number of values. + :::code language="csharp" source="~/snippets/csharp/System/Math/Abs/abs5.cs" interactive="try-dotnet-method" id="Snippet5"::: :::code language="fsharp" source="~/snippets/fsharp/System/Math/Abs/abs5.fs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Math.Abs/vb/abs5.vb" id="Snippet5"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Math.Abs/vb/abs5.vb" id="Snippet5"::: + ]]> @@ -560,20 +560,20 @@ Returns the absolute value of an 8-bit signed integer. An 8-bit signed integer, x, such that 0 ≤ x ≤ SByte.MaxValue. - method to get the absolute value of a number of values. - + method to get the absolute value of a number of values. + :::code language="csharp" source="~/snippets/csharp/System/Math/Abs/abs6.cs" interactive="try-dotnet-method" id="Snippet6"::: :::code language="fsharp" source="~/snippets/fsharp/System/Math/Abs/abs6.fs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Math.Abs/vb/abs6.vb" id="Snippet6"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Math.Abs/vb/abs6.vb" id="Snippet6"::: + ]]> @@ -634,22 +634,22 @@ Returns the absolute value of a single-precision floating-point number. A single-precision floating-point number, x, such that 0 ≤ x ≤ Single.MaxValue. - is its numeric value without its sign. For example, the absolute value of both 1.2e-03 and -1.2e03 is 1.2e03. - - If `value` is equal to or , the return value is . If `value` is equal to , the return value is . - - - -## Examples - The following example uses the method to get the absolute value of a number of values. - + is its numeric value without its sign. For example, the absolute value of both 1.2e-03 and -1.2e03 is 1.2e03. + + If `value` is equal to or , the return value is . If `value` is equal to , the return value is . + + + +## Examples + The following example uses the method to get the absolute value of a number of values. + :::code language="csharp" source="~/snippets/csharp/System/Math/Abs/abs7.cs" interactive="try-dotnet-method" id="Snippet7"::: :::code language="fsharp" source="~/snippets/fsharp/System/Math/Abs/abs7.fs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Math.Abs/vb/abs7.vb" id="Snippet7"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Math.Abs/vb/abs7.vb" id="Snippet7"::: + ]]> @@ -707,26 +707,26 @@ A number representing a cosine, where must be greater than or equal to -1, but less than or equal to 1. Returns the angle whose cosine is the specified number. An angle, θ, measured in radians, such that 0 ≤ θ ≤ π. - - -or- - + + -or- + if < -1 or > 1 or equals . - to convert from radians to degrees. - + to convert from radians to degrees. + This method calls into the underlying C runtime, and the exact result or valid input range may differ between different operating systems or architectures. - -## Examples - The following example uses the method to assist in the computation of the inner angles of a given trapezoid. + +## Examples + The following example uses the method to assist in the computation of the inner angles of a given trapezoid. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/MathSample/CPP/mathsample.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System/Math/Overview/mathsample.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System/Math/Overview/mathsample.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/MathSample/VB/mathsample.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/MathSample/VB/mathsample.vb" id="Snippet1"::: + ]]> @@ -768,19 +768,19 @@ A number representing a hyperbolic cosine, where must be greater than or equal to 1, but less than or equal to . Returns the angle whose hyperbolic cosine is the specified number. - An angle, θ, measured in radians, such that 0 ≤ θ ≤ ∞. - - -or- - + An angle, θ, measured in radians, such that 0 ≤ θ ≤ ∞. + + -or- + if < 1 or equals . - to convert from radians to degrees. - - This method calls into the underlying C runtime, and the exact result or valid input range may differ between different operating systems or architectures. - + to convert from radians to degrees. + + This method calls into the underlying C runtime, and the exact result or valid input range may differ between different operating systems or architectures. + ]]> @@ -838,30 +838,30 @@ A number representing a sine, where must be greater than or equal to -1, but less than or equal to 1. Returns the angle whose sine is the specified number. An angle, θ, measured in radians, such that -π/2 ≤ θ ≤ π/2. - - -or- - + + -or- + if < -1 or > 1 or equals . - to convert from radians to degrees. - - This method calls into the underlying C runtime, and the exact result or valid input range may differ between different operating systems or architectures. - - - -## Examples - The following example uses to assist in the computation of the inner angles of a given trapezoid. + to convert from radians to degrees. + + This method calls into the underlying C runtime, and the exact result or valid input range may differ between different operating systems or architectures. + + + +## Examples + The following example uses to assist in the computation of the inner angles of a given trapezoid. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/MathSample/CPP/mathsample.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System/Math/Overview/mathsample.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System/Math/Overview/mathsample.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/MathSample/VB/mathsample.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/MathSample/VB/mathsample.vb" id="Snippet1"::: + ]]>
@@ -903,19 +903,19 @@ A number representing a hyperbolic sine, where must be greater than or equal to , but less than or equal to . Returns the angle whose hyperbolic sine is the specified number. - An angle, θ, measured in radians. - - -or- - + An angle, θ, measured in radians. + + -or- + if equals . - to convert from radians to degrees. - - This method calls into the underlying C runtime, and the exact result or valid input range may differ between different operating systems or architectures. - + to convert from radians to degrees. + + This method calls into the underlying C runtime, and the exact result or valid input range may differ between different operating systems or architectures. + ]]> @@ -972,31 +972,31 @@ A number representing a tangent. Returns the angle whose tangent is the specified number. - An angle, θ, measured in radians, such that -π/2 ≤ θ ≤ π/2. - - -or- - + An angle, θ, measured in radians, such that -π/2 ≤ θ ≤ π/2. + + -or- + if equals , -π/2 rounded to double precision (-1.5707963267949) if equals , or π/2 rounded to double precision (1.5707963267949) if equals . - to convert from radians to degrees. - - This method calls into the underlying C runtime, and the exact result or valid input range may differ between different operating systems or architectures. - - - -## Examples - The following example demonstrates how to calculate the arctangent of a value and display it to the console. + to convert from radians to degrees. + + This method calls into the underlying C runtime, and the exact result or valid input range may differ between different operating systems or architectures. + + + +## Examples + The following example demonstrates how to calculate the arctangent of a value and display it to the console. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/math.atanx/CPP/atan.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System/Math/Atan/atan.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System/Math/Atan/atan.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/math.atanx/VB/atan.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/math.atanx/VB/atan.vb" id="Snippet1"::: + ]]> @@ -1056,46 +1056,46 @@ The x coordinate of a point. Returns the angle whose tangent is the quotient of two specified numbers. An angle, θ, measured in radians, such that tan(θ) = / , where (, ) is a point in the Cartesian plane. Observe the following: - -- For (, ) in quadrant 1, 0 < θ < π/2. - + +- For (, ) in quadrant 1, 0 < θ < π/2. + - For (, ) in quadrant 2, π/2 < θ ≤ π. - -- For (, ) in quadrant 3, -π ≤ θ < -π/2. - -- For (, ) in quadrant 4, -π/2 < θ < 0. - - For points on the boundaries of the quadrants, the return value is the following: - -- If y is 0 and x is not negative, θ = 0. - -- If y is 0 and x is negative, θ = π. - -- If y is positive and x is 0, θ = π/2. - -- If y is negative and x is 0, θ = -π/2. - -- If y is 0 and x is 0, θ = 0. - + +- For (, ) in quadrant 3, -π ≤ θ < -π/2. + +- For (, ) in quadrant 4, -π/2 < θ < 0. + + For points on the boundaries of the quadrants, the return value is the following: + +- If y is 0 and x is not negative, θ = 0. + +- If y is 0 and x is negative, θ = π. + +- If y is positive and x is 0, θ = π/2. + +- If y is negative and x is 0, θ = -π/2. + +- If y is 0 and x is 0, θ = 0. + If or is , or if and are either or , the method returns . - @@ -1137,19 +1137,19 @@ A number representing a hyperbolic tangent, where must be greater than or equal to -1, but less than or equal to 1. Returns the angle whose hyperbolic tangent is the specified number. - An angle, θ, measured in radians, such that -∞ < θ < -1, or 1 < θ < ∞. - - -or- - + An angle, θ, measured in radians, such that -∞ < θ < -1, or 1 < θ < ∞. + + -or- + if < -1 or > 1 or equals . - to convert from radians to degrees. - - This method calls into the underlying C runtime, and the exact result or valid input range may differ between different operating systems or architectures. - + to convert from radians to degrees. + + This method calls into the underlying C runtime, and the exact result or valid input range may differ between different operating systems or architectures. + ]]> @@ -1198,8 +1198,8 @@ System.Int64 - - + + The first number to multiply. @@ -1207,16 +1207,16 @@ Produces the full product of two 32-bit numbers. The number containing the product of the specified numbers. - method to calculate the product of two integer values. + method to calculate the product of two integer values. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/math.bigmul/CPP/bigmul.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System/Math/BigMul/bigmul.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System/Math/BigMul/bigmul.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/math.bigmul/VB/bigmul.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/math.bigmul/VB/bigmul.vb" id="Snippet1"::: + ]]> @@ -1347,14 +1347,14 @@ The value to decrement. Returns the largest value that compares less than a specified value. - The largest value that compares less than . - - -or- - + The largest value that compares less than . + + -or- + if equals . - - -or- - + + -or- + if equals . To be added. @@ -1395,14 +1395,14 @@ The value to increment. Returns the smallest value that compares greater than a specified value. - The smallest value that compares greater than . - - -or- - + The smallest value that compares greater than . + + -or- + if equals . - - -or- - + + -or- + if equals . To be added. @@ -1444,17 +1444,17 @@ The number whose cube root is to be found. Returns the cube root of a specified number. - The cube root of . - - -or- - + The cube root of . + + -or- + if equals . - @@ -1470,10 +1470,10 @@ Returns the smallest integral value greater than or equal to the specified number. - @@ -1526,18 +1526,18 @@ Returns the smallest integral value that is greater than or equal to the specified decimal number. The smallest integral value that is greater than or equal to . Note that this method returns a instead of an integral type. - method, which supports rounding toward negative infinity. - -## Examples - The following example illustrates the method and contrasts it with the method. - + method, which supports rounding toward negative infinity. + +## Examples + The following example illustrates the method and contrasts it with the method. + :::code language="csharp" source="~/snippets/csharp/System/Math/Ceiling/Ceiling1.cs" interactive="try-dotnet-method" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System/Math/Ceiling/Ceiling1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Math.Ceiling/vb/Ceiling1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Math.Ceiling/vb/Ceiling1.vb" id="Snippet1"::: + ]]> @@ -1598,28 +1598,28 @@ Returns the smallest integral value that is greater than or equal to the specified double-precision floating-point number. The smallest integral value that is greater than or equal to . If is equal to , , or , that value is returned. Note that this method returns a instead of an integral type. - method, which supports rounding toward negative infinity. - + method, which supports rounding toward negative infinity. + Starting with Visual Basic 15.8, the performance of Double-to-integer conversion is optimized if you pass the value returned by the `Ceiling` method to the any of the [integral conversion functions](/dotnet/visual-basic/language-reference/functions/conversion-functions), or if the Double value returned by `Ceiling` is automatically converted to an integer with [Option Strict](/dotnet/visual-basic/language-reference/statements/option-strict-statement) set to Off. This optimization allows code to run faster -- up to twice as fast for code that does a large number of conversions to integer types. The following example illustrates such optimized conversions: - + ```vb Dim d1 As Double = 1043.75133 Dim i1 As Integer = CInt(Math.Ceiling(d1)) ' Result: 1044 Dim d2 As Double = 7968.4136 Dim i2 As Integer = CInt(Math.Ceiling(d2)) ' Result: 7969 -``` +``` + +## Examples + The following example illustrates the method and contrasts it with the method. -## Examples - The following example illustrates the method and contrasts it with the method. - :::code language="csharp" source="~/snippets/csharp/System/Math/Ceiling/Ceiling1.cs" interactive="try-dotnet-method" id="Snippet2"::: :::code language="fsharp" source="~/snippets/fsharp/System/Math/Ceiling/Ceiling1.fs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Math.Ceiling/vb/Ceiling1.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Math.Ceiling/vb/Ceiling1.vb" id="Snippet2"::: + ]]> @@ -1725,13 +1725,13 @@ Dim i2 As Integer = CInt(Math.Ceiling(d2)) ' Result: 7969 Returns clamped to the inclusive range of and . if . - - -or- - + + -or- + if <. - - -or- - + + -or- + if < . To be added. @@ -1780,17 +1780,17 @@ Dim i2 As Integer = CInt(Math.Ceiling(d2)) ' Result: 7969 Returns clamped to the inclusive range of and . if . - - -or- - + + -or- + if < . - - -or- - + + -or- + if < . - - -or- - + + -or- + if equals . To be added. @@ -1839,13 +1839,13 @@ Dim i2 As Integer = CInt(Math.Ceiling(d2)) ' Result: 7969 Returns clamped to the inclusive range of and . if . - - -or- - + + -or- + if < . - - -or- - + + -or- + if < . To be added. @@ -1894,13 +1894,13 @@ Dim i2 As Integer = CInt(Math.Ceiling(d2)) ' Result: 7969 Returns clamped to the inclusive range of and . if . - - -or- - + + -or- + if < . - - -or- - + + -or- + if < . To be added. @@ -1949,13 +1949,13 @@ Dim i2 As Integer = CInt(Math.Ceiling(d2)) ' Result: 7969 Returns clamped to the inclusive range of and . if . - - -or- - + + -or- + if < . - - -or- - + + -or- + if < . To be added. @@ -2088,13 +2088,13 @@ Dim i2 As Integer = CInt(Math.Ceiling(d2)) ' Result: 7969 Returns clamped to the inclusive range of and . if . - - -or- - + + -or- + if < . - - -or- - + + -or- + if < . To be added. @@ -2142,18 +2142,18 @@ Dim i2 As Integer = CInt(Math.Ceiling(d2)) ' Result: 7969 The upper bound of the result. Returns clamped to the inclusive range of and . - if . - - -or- - + if . + + -or- + if < . - - -or- - + + -or- + if < . - - -or- - + + -or- + if equals . To be added. @@ -2207,14 +2207,14 @@ Dim i2 As Integer = CInt(Math.Ceiling(d2)) ' Result: 7969 The upper bound of the result. Returns clamped to the inclusive range of and . - if . - - -or- - + if . + + -or- + if < . - - -or- - + + -or- + if < . To be added. @@ -2268,14 +2268,14 @@ Dim i2 As Integer = CInt(Math.Ceiling(d2)) ' Result: 7969 The upper bound of the result. Returns clamped to the inclusive range of and . - if . - - -or- - + if . + + -or- + if < . - - -or- - + + -or- + if < . To be added. @@ -2330,13 +2330,13 @@ Dim i2 As Integer = CInt(Math.Ceiling(d2)) ' Result: 7969 Returns clamped to the inclusive range of and . if . - - -or- - + + -or- + if < . - - -or- - + + -or- + if < . To be added. @@ -2521,23 +2521,23 @@ Dim i2 As Integer = CInt(Math.Ceiling(d2)) ' Result: 7969 Returns the cosine of the specified angle. The cosine of . If is equal to , , or , this method returns . - /180 to convert degrees to radians. - - This method calls into the underlying C runtime, and the exact result or valid input range may differ between different operating systems or architectures. - - - -## Examples - The following example uses to evaluate certain trigonometric identities for selected angles. + /180 to convert degrees to radians. + + This method calls into the underlying C runtime, and the exact result or valid input range may differ between different operating systems or architectures. + + + +## Examples + The following example uses to evaluate certain trigonometric identities for selected angles. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Math.SinCos/CPP/sincos.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System/Math/Cos/sincos.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System/Math/Cos/sincos.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Math.SinCos/VB/sincos.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Math.SinCos/VB/sincos.vb" id="Snippet1"::: + ]]> @@ -2596,23 +2596,23 @@ Dim i2 As Integer = CInt(Math.Ceiling(d2)) ' Result: 7969 Returns the hyperbolic cosine of the specified angle. The hyperbolic cosine of . If is equal to or , is returned. If is equal to , is returned. - /180 to convert degrees to radians. - - This method calls into the underlying C runtime, and the exact result or valid input range may differ between different operating systems or architectures. - - - -## Examples - The following example uses to evaluate certain hyperbolic identities for selected values. - + /180 to convert degrees to radians. + + This method calls into the underlying C runtime, and the exact result or valid input range may differ between different operating systems or architectures. + + + +## Examples + The following example uses to evaluate certain hyperbolic identities for selected values. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Math.SinhCosh/CPP/sinhcosh.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System/Math/Cosh/sinhcosh.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System/Math/Cosh/sinhcosh.fs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Math.SinhCosh/VB/sinhcosh.vb" id="Snippet1"::: - + ]]> @@ -3189,9 +3189,9 @@ Dim i2 As Integer = CInt(Math.Ceiling(d2)) ' Result: 7969 System.Int32 - - - + + + The dividend. @@ -3200,18 +3200,18 @@ Dim i2 As Integer = CInt(Math.Ceiling(d2)) ' Result: 7969 Calculates the quotient of two 32-bit signed integers and also returns the remainder in an output parameter. The quotient of the specified numbers. - method. + method. :::code language="csharp" source="~/snippets/csharp/System/Math/DivRem/divrem1.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System/Math/DivRem/divrem1.fs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.math.divrem/vb/divrem1.vb" id="Snippet1"::: - + ]]> @@ -3263,9 +3263,9 @@ Dim i2 As Integer = CInt(Math.Ceiling(d2)) ' Result: 7969 System.Int64 - - - + + + The dividend. @@ -3274,18 +3274,18 @@ Dim i2 As Integer = CInt(Math.Ceiling(d2)) ' Result: 7969 Calculates the quotient of two 64-bit signed integers and also returns the remainder in an output parameter. The quotient of the specified numbers. - method. + +## Examples + The following example demonstrates the method. :::code language="csharp" source="~/snippets/csharp/System/Math/DivRem/divrem2.cs" interactive="try-dotnet" id="Snippet2"::: :::code language="fsharp" source="~/snippets/fsharp/System/Math/DivRem/divrem2.fs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.math.divrem/vb/divrem2.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.math.divrem/vb/divrem2.vb" id="Snippet2"::: + ]]> @@ -3337,21 +3337,21 @@ Dim i2 As Integer = CInt(Math.Ceiling(d2)) ' Result: 7969 Represents the natural logarithmic base, specified by the constant, . - with the value calculated from a power series. + with the value calculated from a power series. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Math.E/CPP/efield.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System/Math/E/efield.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System/Math/E/efield.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Math.E/VB/efield.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Math.E/VB/efield.vb" id="Snippet1"::: + ]]> @@ -3410,27 +3410,27 @@ Dim i2 As Integer = CInt(Math.Ceiling(d2)) ' Result: 7969 Returns raised to the specified power. The number raised to the power . If equals or , that value is returned. If equals , 0 is returned. - method to calculate powers of other bases. - - is the inverse of . - - This method calls into the underlying C runtime, and the exact result or valid input range may differ between different operating systems or architectures. - - - -## Examples - The following example uses to evaluate certain exponential and logarithmic identities for selected values. + method to calculate powers of other bases. + + is the inverse of . + + This method calls into the underlying C runtime, and the exact result or valid input range may differ between different operating systems or architectures. + + + +## Examples + The following example uses to evaluate certain exponential and logarithmic identities for selected values. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Math.Exp/CPP/exp.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System/Math/Exp/exp.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System/Math/Exp/exp.fs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Math.Exp/VB/exp.vb" id="Snippet1"::: - + ]]> @@ -3448,10 +3448,10 @@ Dim i2 As Integer = CInt(Math.Ceiling(d2)) ' Result: 7969 Returns the largest integral value less than or equal to the specified number. - @@ -3504,18 +3504,18 @@ Dim i2 As Integer = CInt(Math.Ceiling(d2)) ' Result: 7969 Returns the largest integral value less than or equal to the specified decimal number. The largest integral value less than or equal to . Note that the method returns an integral value of type . - method, which supports rounding toward positive infinity. - -## Examples - The following example illustrates the method and contrasts it with the method. - + method, which supports rounding toward positive infinity. + +## Examples + The following example illustrates the method and contrasts it with the method. + :::code language="csharp" source="~/snippets/csharp/System/Math/Ceiling/Ceiling1.cs" interactive="try-dotnet-method" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System/Math/Ceiling/Ceiling1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Math.Ceiling/vb/Ceiling1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Math.Ceiling/vb/Ceiling1.vb" id="Snippet1"::: + ]]> @@ -3577,13 +3577,13 @@ Dim i2 As Integer = CInt(Math.Ceiling(d2)) ' Result: 7969 Returns the largest integral value less than or equal to the specified double-precision floating-point number. The largest integral value less than or equal to . If is equal to , , or , that value is returned. - method, which supports rounding toward positive infinity. + method, which supports rounding toward positive infinity. Starting with Visual Basic 15.8, the performance of Double-to-integer conversion is optimized if you pass the value returned by the `Floor` method to the any of the [integral conversion functions](/dotnet/visual-basic/language-reference/functions/conversion-functions), or if the Double value returned by `Floor` is automatically converted to an integer with [Option Strict](/dotnet/visual-basic/language-reference/statements/option-strict-statement) set to Off. This optimization allows code to run faster -- up to twice as fast for code that does a large number of conversions to integer types. The following example illustrates such optimized conversions: - + ```vb Dim d1 As Double = 1043.75133 Dim i1 As Integer = CInt(Math.Floor(d1)) ' Result: 1043 @@ -3592,13 +3592,13 @@ Dim d2 As Double = 7968.4136 Dim i2 As Integer = CInt(Math.Floor(d2)) ' Result: 7968 ``` -## Examples - The following example illustrates the method and contrasts it with the method. - +## Examples + The following example illustrates the method and contrasts it with the method. + :::code language="csharp" source="~/snippets/csharp/System/Math/Ceiling/Ceiling1.cs" interactive="try-dotnet-method" id="Snippet2"::: :::code language="fsharp" source="~/snippets/fsharp/System/Math/Ceiling/Ceiling1.fs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Math.Ceiling/vb/Ceiling1.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Math.Ceiling/vb/Ceiling1.vb" id="Snippet2"::: + ]]> @@ -3647,13 +3647,13 @@ Dim i2 As Integer = CInt(Math.Floor(d2)) ' Result: 7968 Returns (x * y) + z, rounded as one ternary operation. (x * y) + z, rounded as one ternary operation. - @@ -3712,40 +3712,40 @@ Dim i2 As Integer = CInt(Math.Floor(d2)) ' Result: 7968 A dividend. A divisor. Returns the remainder resulting from the division of a specified number by another specified number. - A number equal to - ( Q), where Q is the quotient of / rounded to the nearest integer (if / falls halfway between two integers, the even integer is returned). - - If - ( Q) is zero, the value +0 is returned if is positive, or -0 if is negative. - + A number equal to - ( Q), where Q is the quotient of / rounded to the nearest integer (if / falls halfway between two integers, the even integer is returned). + + If - ( Q) is zero, the value +0 is returned if is positive, or -0 if is negative. + If = 0, is returned. - method is not the same as the [remainder operator](/dotnet/csharp/language-reference/operators/remainder-operator). Although both return the remainder after division, the formulas they use are different. The formula for the method is: - -``` -IEEERemainder = dividend - (divisor * Math.Round(dividend / divisor)) -``` - - In contrast, the formula for the remainder operator is: - -``` -Remainder = (Math.Abs(dividend) - (Math.Abs(divisor) * - (Math.Floor(Math.Abs(dividend) / Math.Abs(divisor))))) * - Math.Sign(dividend) -``` - - - -## Examples - The following example contrasts the remainder returned by the method with the remainder returned by the [remainder operator](/dotnet/csharp/language-reference/operators/remainder-operator). - + method is not the same as the [remainder operator](/dotnet/csharp/language-reference/operators/remainder-operator). Although both return the remainder after division, the formulas they use are different. The formula for the method is: + +``` +IEEERemainder = dividend - (divisor * Math.Round(dividend / divisor)) +``` + + In contrast, the formula for the remainder operator is: + +``` +Remainder = (Math.Abs(dividend) - (Math.Abs(divisor) * + (Math.Floor(Math.Abs(dividend) / Math.Abs(divisor))))) * + Math.Sign(dividend) +``` + + + +## Examples + The following example contrasts the remainder returned by the method with the remainder returned by the [remainder operator](/dotnet/csharp/language-reference/operators/remainder-operator). + :::code language="csharp" source="~/snippets/csharp/System/Math/IEEERemainder/ieeeremainder1.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System/Math/IEEERemainder/ieeeremainder1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.math.ieeeremainder/vb/ieeeremainder1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.math.ieeeremainder/vb/ieeeremainder1.vb" id="Snippet1"::: + ]]> @@ -3786,27 +3786,27 @@ Remainder = (Math.Abs(dividend) - (Math.Abs(divisor) * The number whose logarithm is to be found. Returns the base 2 integer logarithm of a specified number. - One of the values in the following table. - - parameter - - Return value - + One of the values in the following table. + + parameter + + Return value + Default - - The base 2 integer log of ; that is, (int)log2(). - - Zero - + + The base 2 integer log of ; that is, (int)log2(). + + Zero + Int32.MinValue Equal to or or Int32.MaxValue - @@ -3875,38 +3875,38 @@ Remainder = (Math.Abs(dividend) - (Math.Abs(divisor) * The number whose logarithm is to be found. Returns the natural (base ) logarithm of a specified number. - One of the values in the following table. - - parameter - - Return value - - Positive - - The natural logarithm of ; that is, ln , or log e Zero - - Negative - + One of the values in the following table. + + parameter + + Return value + + Positive + + The natural logarithm of ; that is, ln , or log e Zero + + Negative + Equal to Equal to - method. + method. :::code language="csharp" source="~/snippets/csharp/System/Math/LogMethod/log1.cs" interactive="try-dotnet" id="Snippet2"::: :::code language="fsharp" source="~/snippets/fsharp/System/Math/LogMethod/log1.fs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Math.Log_Overloads/VB/log1.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Math.Log_Overloads/VB/log1.vb" id="Snippet2"::: + ]]> @@ -3961,111 +3961,111 @@ Remainder = (Math.Abs(dividend) - (Math.Abs(divisor) * The number whose logarithm is to be found. The base of the logarithm. Returns the logarithm of a specified number in a specified base. - One of the values in the following table. (+Infinity denotes , -Infinity denotes , and NaN denotes .) - - Return value - - > 0 - - (0 << 1) -or- (> 1) - - lognewBase(a) - - < 0 - - (any value) - - NaN - - (any value) - - < 0 - - NaN - - != 1 - - = 0 - - NaN - - != 1 - - = +Infinity - - NaN - - = NaN - - (any value) - - NaN - - (any value) - - = NaN - - NaN - - (any value) - - = 1 - - NaN - - = 0 - - 0 << 1 - - +Infinity - - = 0 - - > 1 - - -Infinity - - = +Infinity - - 0 << 1 - - -Infinity - - = +Infinity - - > 1 - - +Infinity - - = 1 - - = 0 - - 0 - - = 1 - - = +Infinity - - 0 - + One of the values in the following table. (+Infinity denotes , -Infinity denotes , and NaN denotes .) + + Return value + + > 0 + + (0 << 1) -or- (> 1) + + lognewBase(a) + + < 0 + + (any value) + + NaN + + (any value) + + < 0 + + NaN + + != 1 + + = 0 + + NaN + + != 1 + + = +Infinity + + NaN + + = NaN + + (any value) + + NaN + + (any value) + + = NaN + + NaN + + (any value) + + = 1 + + NaN + + = 0 + + 0 << 1 + + +Infinity + + = 0 + + > 1 + + -Infinity + + = +Infinity + + 0 << 1 + + -Infinity + + = +Infinity + + > 1 + + +Infinity + + = 1 + + = 0 + + 0 + + = 1 + + = +Infinity + + 0 + - to evaluate certain logarithmic identities for selected values. + to evaluate certain logarithmic identities for selected values. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Math.Log_Overloads/CPP/loggen.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System/Math/LogMethod/loggen.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System/Math/LogMethod/loggen.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Math.Log_Overloads/VB/loggen.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Math.Log_Overloads/VB/loggen.vb" id="Snippet1"::: + ]]> @@ -4122,38 +4122,38 @@ Remainder = (Math.Abs(dividend) - (Math.Abs(divisor) * A number whose logarithm is to be found. Returns the base 10 logarithm of a specified number. - One of the values in the following table. - - parameter - - Return value - - Positive - - The base 10 log of ; that is, log 10. - - Zero - - Negative - + One of the values in the following table. + + parameter + + Return value + + Positive + + The base 10 log of ; that is, log 10. + + Zero + + Negative + Equal to Equal to - method to return the base 10 logarithm for selected values. + method to return the base 10 logarithm for selected values. :::code language="csharp" source="~/snippets/csharp/System/Math/Log10/log10.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System/Math/Log10/log10.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Math.Log10/VB/log10.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Math.Log10/VB/log10.vb" id="Snippet1"::: + ]]> @@ -4194,29 +4194,29 @@ Remainder = (Math.Abs(dividend) - (Math.Abs(divisor) * A number whose logarithm is to be found. Returns the base 2 logarithm of a specified number. - One of the values in the following table. - - parameter - - Return value - - Positive - - The base 2 log of ; that is, log 2. - - Zero - - Negative - + One of the values in the following table. + + parameter + + Return value + + Positive + + The base 2 log of ; that is, log 2. + + Zero + + Negative + Equal to Equal to - @@ -4232,8 +4232,8 @@ Remainder = (Math.Abs(dividend) - (Math.Abs(divisor) * Returns the larger of two specified numbers. - method to return and display the greater of two variables: @@ -4241,8 +4241,8 @@ The following example demonstrates how to use the meth :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/math.max/CPP/max.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System/Math/Max/max.cs" interactive="try-dotnet-method" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System/Math/Max/max.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/math.max/VB/max.vb" id="Snippet1"::: - +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/math.max/VB/max.vb" id="Snippet1"::: + ]]> @@ -5124,7 +5124,7 @@ The following example demonstrates how to use the meth Returns the smaller of two numbers. - meth :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/math.min/CPP/min.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System/Math/Min/min.cs" interactive="try-dotnet-method" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System/Math/Min/min.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/math.min/VB/min.vb" id="Snippet1"::: - +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/math.min/VB/min.vb" id="Snippet1"::: + ]]> @@ -6049,21 +6049,21 @@ The following example demonstrates how to use the meth Represents the ratio of the circumference of a circle to its diameter, specified by the constant, π. - to assist in the computation of the inner angles of a given trapezoid. + to assist in the computation of the inner angles of a given trapezoid. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/MathSample/CPP/mathsample.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System/Math/Overview/mathsample.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System/Math/Overview/mathsample.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/MathSample/VB/mathsample.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/MathSample/VB/mathsample.vb" id="Snippet1"::: + ]]> @@ -6124,10 +6124,10 @@ The following example demonstrates how to use the meth Returns a specified number raised to the specified power. The number raised to the power . - , , and . + , , and . | x | y | Return value | |--------------------------------|-----------------------------------------------------------|--------------------------------| @@ -6150,19 +6150,19 @@ The following example demonstrates how to use the meth | 0 | > 0 | 0 | | `PositiveInfinity` | < 0 | 0 | | `PositiveInfinity` | > 0 | `PositiveInfinity` | - - This method calls into the underlying C runtime, and the exact result or valid input range may differ between different operating systems or architectures. - - - -## Examples - - The following example uses the method to calculate the value that results from raising 2 to a power ranging from 0 to 32. - + + This method calls into the underlying C runtime, and the exact result or valid input range may differ between different operating systems or architectures. + + + +## Examples + + The following example uses the method to calculate the value that results from raising 2 to a power ranging from 0 to 32. + :::code language="csharp" source="~/snippets/csharp/System/Math/Pow/pow1.cs" interactive="try-dotnet-method" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System/Math/Pow/pow1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.math.pow/vb/pow1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.math.pow/vb/pow1.vb" id="Snippet1"::: + ]]> @@ -6276,16 +6276,16 @@ On hardware without specialized support, this may just return `1.0 / Sqrt(d)`. Rounds a value to the nearest integer or to the specified number of fractional digits. - -## Remarks + +## Remarks In this section: - [Which method do I call?](#which-method-do-i-call) -- [Midpoint values and rounding conventions](#midpoint-values-and-rounding-conventions) -- [Rounding and precision](#rounding-and-precision) +- [Midpoint values and rounding conventions](#midpoint-values-and-rounding-conventions) +- [Rounding and precision](#rounding-and-precision) - [Rounding and single-precision floating point values](#rounding-and-single-precision-floating-point-values) - [Examples of individual overloads](#round-examples) @@ -6293,111 +6293,111 @@ In this section: You can use the following table to select an appropriate rounding method. In addition to the `Math.Round` methods, it also includes and . -|To|Call| -|--------|----------| -|Round a number to an integer by using the rounding-to-nearest convention.|
-or-
| -|Round a number to an integer by using a specified rounding convention.|
-or-
| -|Round a number to a specified number of fractional digits by using the rounding to nearest convention.|
-or-
| -|Round a number to a specified number of fractional digits by using a specified rounding convention.|
-or-
| -|Round a value to a specified number of fractional digits by using a specified rounding convention and minimizing the loss of precision.|Convert the to a and call .| -|Round a number to a specified number of fractional digits while minimizing problems of precision in rounding midpoint values.|Call a rounding method that implements a "greater than or approximately equal to" comparison. See [Rounding and precision](#precision).| -|Round a fractional value to an integer that is greater than the fractional value. For example, round 3.1 to 4.|| -|Round a fractional value to an integer that is less than the fractional value. For example, round 3.9 to 3.|| - -### Midpoint values and rounding conventions - -Rounding involves converting a numeric value with a specified precision to a value with less precision. For example, you can use the method to round a value of 3.4 to 3.0, and the method to round a value of 3.579 to 3.58. - +|To|Call| +|--------|----------| +|Round a number to an integer by using the rounding-to-nearest convention.|
-or-
| +|Round a number to an integer by using a specified rounding convention.|
-or-
| +|Round a number to a specified number of fractional digits by using the rounding to nearest convention.|
-or-
| +|Round a number to a specified number of fractional digits by using a specified rounding convention.|
-or-
| +|Round a value to a specified number of fractional digits by using a specified rounding convention and minimizing the loss of precision.|Convert the to a and call .| +|Round a number to a specified number of fractional digits while minimizing problems of precision in rounding midpoint values.|Call a rounding method that implements a "greater than or approximately equal to" comparison. See [Rounding and precision](#precision).| +|Round a fractional value to an integer that is greater than the fractional value. For example, round 3.1 to 4.|| +|Round a fractional value to an integer that is less than the fractional value. For example, round 3.9 to 3.|| + +### Midpoint values and rounding conventions + +Rounding involves converting a numeric value with a specified precision to a value with less precision. For example, you can use the method to round a value of 3.4 to 3.0, and the method to round a value of 3.579 to 3.58. + In a midpoint value, the value after the least significant digit in the result is precisely half way between two numbers. For example, 3.47500 is a midpoint value if it is to be rounded to two decimal places, and 7.500 is a midpoint value if it is to be rounded to an integer. In these cases, if the round-to-nearest strategy is used, the nearest value can't be easily identified without a rounding convention. -The method supports two rounding conventions for handling midpoint values: - -- **Rounding away from zero** +The method supports two rounding conventions for handling midpoint values: + +- **Rounding away from zero** Midpoint values are rounded to the next number away from zero. For example, 3.75 rounds to 3.8, 3.85 rounds to 3.9, -3.75 rounds to -3.8, and -3.85 rounds to -3.9. This form of rounding is represented by the enumeration member. -- **Rounding to nearest even, or banker's rounding** +- **Rounding to nearest even, or banker's rounding** Midpoint values are rounded to the nearest even number. For example, both 3.75 and 3.85 round to 3.8, and both -3.75 and -3.85 round to -3.8. This form of rounding is represented by the enumeration member. > [!NOTE] > In .NET Core 3.0 and later versions, three additional rounding strategies are available through the enumeration. These strategies are used in all cases, not just for midpoint values as and are. -Rounding away from zero is the most widely known form of rounding, while rounding to nearest even is the standard in financial and statistical operations. It conforms to IEEE Standard 754, section 4. When used in multiple rounding operations, rounding to nearest even reduces the rounding error that is caused by consistently rounding midpoint values in a single direction. In some cases, this rounding error can be significant. - -The following example illustrates the bias that can result from consistently rounding midpoint values in a single direction. The example computes the true mean of an array of values, and then computes the mean when the values in the array are rounded by using the two conventions. In this example, the true mean and the mean that results when rounding to nearest are the same. However, the mean that results when rounding away from zero differs by .05 (or by 3.6%) from the true mean. - +Rounding away from zero is the most widely known form of rounding, while rounding to nearest even is the standard in financial and statistical operations. It conforms to IEEE Standard 754, section 4. When used in multiple rounding operations, rounding to nearest even reduces the rounding error that is caused by consistently rounding midpoint values in a single direction. In some cases, this rounding error can be significant. + +The following example illustrates the bias that can result from consistently rounding midpoint values in a single direction. The example computes the true mean of an array of values, and then computes the mean when the values in the array are rounded by using the two conventions. In this example, the true mean and the mean that results when rounding to nearest are the same. However, the mean that results when rounding away from zero differs by .05 (or by 3.6%) from the true mean. + :::code language="csharp" source="~/snippets/csharp/System/Decimal/Round/mean1.cs" interactive="try-dotnet-method" id="Snippet2"::: :::code language="fsharp" source="~/snippets/fsharp/System/Decimal/Round/mean1.fs" id="Snippet2"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.math.round.overload/vb/mean1.vb" id="Snippet2"::: - -By default, the method uses the round to nearest even convention. The following table lists the overloads of the method and the rounding convention that each uses. - -|Overload|Rounding convention| -|--------------|-------------------------| -||| -||| -||| -||| -||Determined by `mode` parameter.| -||Determined by `mode` parameter| -||Determined by `mode` parameter| -||Determined by `mode` parameter| +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.math.round.overload/vb/mean1.vb" id="Snippet2"::: + +By default, the method uses the round to nearest even convention. The following table lists the overloads of the method and the rounding convention that each uses. + +|Overload|Rounding convention| +|--------------|-------------------------| +||| +||| +||| +||| +||Determined by `mode` parameter.| +||Determined by `mode` parameter| +||Determined by `mode` parameter| +||Determined by `mode` parameter| -### Rounding and precision +### Rounding and precision In order to determine whether a rounding operation involves a midpoint value, the method multiplies the original value to be rounded by 10n, where *n* is the desired number of fractional digits in the return value, and then determines whether the remaining fractional portion of the value is greater than or equal to .5. This is a slight variation on a test for equality, and as discussed in the "Testing for Equality" section of the reference topic, tests for equality with floating-point values are problematic because of the floating-point format's issues with binary representation and precision. This means that any fractional portion of a number that is slightly less than .5 (because of a loss of precision) will not be rounded upward. -The following example illustrates the problem. It repeatedly adds .1 to 11.0 and rounds the result to the nearest integer. 11.5 should round to 12 using either of the midpoint-rounding conventions (`ToEven` or `AwayFromZero`). However, as the output from the example shows, it does not. The example uses the "R" [standard numeric format string](/dotnet/standard/base-types/standard-numeric-format-strings) to display the floating point value's full precision, and shows that the value to be rounded has lost precision during repeated additions, and its value is actually 11.499999999999998. Because .499999999999998 is less than .5, the midpoint-rounding conventions don't come into play and the value is rounded down. As the example also shows, this problem does not occur if you assign the constant value 11.5 to a variable. - +The following example illustrates the problem. It repeatedly adds .1 to 11.0 and rounds the result to the nearest integer. 11.5 should round to 12 using either of the midpoint-rounding conventions (`ToEven` or `AwayFromZero`). However, as the output from the example shows, it does not. The example uses the "R" [standard numeric format string](/dotnet/standard/base-types/standard-numeric-format-strings) to display the floating point value's full precision, and shows that the value to be rounded has lost precision during repeated additions, and its value is actually 11.499999999999998. Because .499999999999998 is less than .5, the midpoint-rounding conventions don't come into play and the value is rounded down. As the example also shows, this problem does not occur if you assign the constant value 11.5 to a variable. + :::code language="csharp" source="~/snippets/csharp/System/Decimal/Round/precision1.cs" interactive="try-dotnet" id="Snippet7"::: :::code language="fsharp" source="~/snippets/fsharp/System/Decimal/Round/precision1.fs" id="Snippet7"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.math.round.overload/vb/precision1.vb" id="Snippet7"::: - -Problems of precision in rounding midpoint values are most likely to arise in the following conditions: - -- When a fractional value cannot be expressed precisely in the floating-point type's binary format. - -- When the value to be rounded is calculated from one or more floating-point operations. - -- When the value to be rounded is a rather than a or . For more information, see the next section, [Rounding and single-precision floating-point values](#rounding-and-single-precision-floating-point-values). - - In cases where the lack of precision in rounding operations is problematic, you can do the following: - -- If the rounding operation calls an overload that rounds a value, you can change the to a value and call an overload that rounds a value instead. Although the data type also has problems of representation and loss of precision, these issues are far less common. - -- Define a custom rounding algorithm that performs a "nearly equal" test to determine whether the value to be rounded is acceptably close to a midpoint value. The following example defines a `RoundApproximate` method that examines whether a fractional value is sufficiently near to a midpoint value to be subject to midpoint rounding. As the output from the example shows, it corrects the rounding problem shown in the previous example. - + +Problems of precision in rounding midpoint values are most likely to arise in the following conditions: + +- When a fractional value cannot be expressed precisely in the floating-point type's binary format. + +- When the value to be rounded is calculated from one or more floating-point operations. + +- When the value to be rounded is a rather than a or . For more information, see the next section, [Rounding and single-precision floating-point values](#rounding-and-single-precision-floating-point-values). + + In cases where the lack of precision in rounding operations is problematic, you can do the following: + +- If the rounding operation calls an overload that rounds a value, you can change the to a value and call an overload that rounds a value instead. Although the data type also has problems of representation and loss of precision, these issues are far less common. + +- Define a custom rounding algorithm that performs a "nearly equal" test to determine whether the value to be rounded is acceptably close to a midpoint value. The following example defines a `RoundApproximate` method that examines whether a fractional value is sufficiently near to a midpoint value to be subject to midpoint rounding. As the output from the example shows, it corrects the rounding problem shown in the previous example. + :::code language="csharp" source="~/snippets/csharp/System/Decimal/Round/precision2.cs" interactive="try-dotnet" id="Snippet8"::: :::code language="fsharp" source="~/snippets/fsharp/System/Decimal/Round/precision2.fs" id="Snippet8"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.math.round.overload/vb/precision2.vb" id="Snippet8"::: - -#### Rounding and single-precision floating-point values -The method includes overloads that accept arguments of type and . There are no methods that round values of type . If you pass a value to one of the overloads of the method, it is cast (in C#) or converted (in Visual Basic) to a , and the corresponding overload with a parameter is called. Although this is a widening conversion, it often involves a loss of precision, as the following example illustrates. When a value of 16.325 is passed to the method and rounded to two decimal places using the rounding to nearest convention, the result is 16.33 and not the expected result of 16.32. +#### Rounding and single-precision floating-point values + +The method includes overloads that accept arguments of type and . There are no methods that round values of type . If you pass a value to one of the overloads of the method, it is cast (in C#) or converted (in Visual Basic) to a , and the corresponding overload with a parameter is called. Although this is a widening conversion, it often involves a loss of precision, as the following example illustrates. When a value of 16.325 is passed to the method and rounded to two decimal places using the rounding to nearest convention, the result is 16.33 and not the expected result of 16.32. :::code language="csharp" source="~/snippets/csharp/System/Decimal/Round/single1.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System/Decimal/Round/single1.fs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.math.round.overload/vb/single1.vb" id="Snippet1"::: - -This unexpected result is due to a loss of precision in the conversion of the value to a . Because the resulting value of 16.325000762939453 is not a midpoint value and is greater than 16.325, it is always rounded upward. - -In many cases, as the example illustrates, the loss of precision can be minimized or eliminated by casting or converting the value to a . Note that, because this is a narrowing conversion, it requires using a cast operator or calling a conversion method. - -## Examples +This unexpected result is due to a loss of precision in the conversion of the value to a . Because the resulting value of 16.325000762939453 is not a midpoint value and is greater than 16.325, it is always rounded upward. + +In many cases, as the example illustrates, the loss of precision can be minimized or eliminated by casting or converting the value to a . Note that, because this is a narrowing conversion, it requires using a cast operator or calling a conversion method. + + +## Examples In addition to the examples in the [Remarks](#remarks-round) section, this article includes examples that illustrate the following overloads of the `Math.Round` method: -[Math.Round(Decimal)](#Round1_Example) -[Math.Round(Double)](#Round2_Example) -[Math.Round(Decimal, Int32)](#Round3_Example) -[Math.Round(Decimal, MidpointRounding)](#Round4_Example) -[Math.Round(Double, Int32)](#Round5_Example) -[Math.Round(Double, MidpointRounding)](#Round6_Example) -[Math.Round(Decimal, Int32, MidpointRounding)](#Round7_Example) -[Math.Round(Double, Int32, MidpointRounding)](#Round8_Example) +[Math.Round(Decimal)](#Round1_Example) +[Math.Round(Double)](#Round2_Example) +[Math.Round(Decimal, Int32)](#Round3_Example) +[Math.Round(Decimal, MidpointRounding)](#Round4_Example) +[Math.Round(Double, Int32)](#Round5_Example) +[Math.Round(Double, MidpointRounding)](#Round6_Example) +[Math.Round(Decimal, Int32, MidpointRounding)](#Round7_Example) +[Math.Round(Double, Int32, MidpointRounding)](#Round8_Example) ]]>
@@ -6455,22 +6455,22 @@ In addition to the examples in the [Remarks](#remarks-round) section, this artic Rounds a decimal value to the nearest integral value, and rounds midpoint values to the nearest even number. The integer nearest the parameter. If the fractional component of is halfway between two integers, one of which is even and the other odd, the even number is returned. Note that this method returns a instead of an integral type. - . For information about rounding numbers with midpoint values, see [Midpoint values and rounding conventions](#midpoint-values-and-rounding-conventions). [!INCLUDE[midpoint-rounding](~/includes/floating-point-equality.md)] - + ## Examples -The following example demonstrates the method. The value of 4.5 rounds to 4 rather than 5, because this overload uses the default convention. - +The following example demonstrates the method. The value of 4.5 rounds to 4 rather than 5, because this overload uses the default convention. + :::code language="csharp" source="~/snippets/csharp/System/Math/Round/rounddecimal1.cs" interactive="try-dotnet-method" id="Snippet6"::: :::code language="fsharp" source="~/snippets/fsharp/System/Math/Round/rounddecimal1.fs" id="Snippet6"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.math.round/vb/rounddecimal1.vb" id="Snippet6"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.math.round/vb/rounddecimal1.vb" id="Snippet6"::: ]]> @@ -6534,18 +6534,18 @@ The following example demonstrates the Rounds a double-precision floating-point value to the nearest integral value, and rounds midpoint values to the nearest even number. The integer nearest . If the fractional component of is halfway between two integers, one of which is even and the other odd, then the even number is returned. Note that this method returns a instead of an integral type. - . For information about rounding numbers with midpoint values, see [Midpoint values and rounding conventions](#midpoint-values-and-rounding-conventions). [!INCLUDE[midpoint-rounding](~/includes/floating-point-equality.md)] -If the value of the `a` argument is , the method returns . If `a` is or , the method returns or , respectively. +If the value of the `a` argument is , the method returns . If `a` is or , the method returns or , respectively. Starting with Visual Basic 15.8, the performance of Double-to-integer conversion is optimized if you pass the value returned by the `Round` method to the any of the [integral conversion functions](/dotnet/visual-basic/language-reference/functions/conversion-functions), or if the Double value returned by `Round` is automatically converted to an integer with [Option Strict](/dotnet/visual-basic/language-reference/statements/option-strict-statement) set to Off. This optimization allows code to run faster -- up to twice as fast for code that does a large number of conversions to integer types. The following example illustrates such optimized conversions: - + ```vb Dim d1 As Double = 1043.75133 Dim i1 As Integer = CInt(Math.Ceiling(d1)) ' Result: 1044 @@ -6554,25 +6554,25 @@ Dim d2 As Double = 7968.4136 Dim i2 As Integer = CInt(Math.Ceiling(d2)) ' Result: 7968 ``` - -## Example + +## Example + +The following example demonstrates rounding to the nearest integer value. -The following example demonstrates rounding to the nearest integer value. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Math.Round Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System/Math/Round/source.cs" interactive="try-dotnet-method" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System/Math/Round/source.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Math.Round Example/VB/source.vb" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Math.Round Example/VB/source.vb" id="Snippet1"::: ]]> - Because of the loss of precision that can result from representing decimal values as floating-point numbers or performing arithmetic operations on floating-point values, in some cases the method may not appear to round midpoint values to the nearest even integer. In the following example, because the floating-point value .1 has no finite binary representation, the first call to the method with a value of 11.5 returns 11 instead of 12. + Because of the loss of precision that can result from representing decimal values as floating-point numbers or performing arithmetic operations on floating-point values, in some cases the method may not appear to round midpoint values to the nearest even integer. In the following example, because the floating-point value .1 has no finite binary representation, the first call to the method with a value of 11.5 returns 11 instead of 12. :::code language="csharp" source="~/snippets/csharp/System/Math/Round/round2.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System/Math/Round/round2.fs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.math.round/vb/round2.vb" id="Snippet1"::: - + @@ -6630,25 +6630,25 @@ The following example demonstrates rounding to the nearest integer value. Rounds a decimal value to a specified number of fractional digits, and rounds midpoint values to the nearest even number. The number nearest to that contains a number of fractional digits equal to . - . For information about rounding numbers with midpoint values, see [Midpoint values and rounding conventions](#midpoint-values-and-rounding-conventions). [!INCLUDE[midpoint-rounding](~/includes/floating-point-equality.md)] - -## Example + +## Example + +The following example rounds decimal values with two fractional digits to values that have a single fractional digit. -The following example rounds decimal values with two fractional digits to values that have a single fractional digit. - :::code language="csharp" source="~/snippets/csharp/System/Decimal/Round/source.cs" interactive="try-dotnet-method" id="Snippet3"::: :::code language="fsharp" source="~/snippets/fsharp/System/Decimal/Round/source.fs" id="Snippet3"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.math.round.overload/vb/source.vb" id="Snippet3"::: - +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.math.round.overload/vb/source.vb" id="Snippet3"::: + ]]> @@ -6714,23 +6714,23 @@ The following example rounds decimal values with two fractional digits to values Rounds a decimal value an integer using the specified rounding convention. The integer that is rounded to. This method returns a instead of an integral type. - -## Example + +## Example The following example displays values returned by the method with different `mode` values. :::code language="csharp" source="~/snippets/csharp/System/Decimal/Round/midpoint1.cs" interactive="try-dotnet" id="Snippet5"::: :::code language="fsharp" source="~/snippets/fsharp/System/Decimal/Round/midpoint1.fs" id="Snippet5"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.math.round.overload/vb/midpoint1.vb" id="Snippet5"::: - + ]]> @@ -6791,39 +6791,39 @@ The following example displays values returned by the Rounds a double-precision floating-point value to a specified number of fractional digits, and rounds midpoint values to the nearest even number. The number nearest to that contains a number of fractional digits equal to . - type is 15. This method uses the default rounding convention of . See [Midpoint values and rounding conventions](#midpoint-values-and-rounding-conventions) for information about rounding numbers with midpoint values. [!INCLUDE[midpoint-rounding](~/includes/floating-point-equality.md)] -If the value of the `value` argument is , the method returns . If `value` is or , the method returns or , respectively. +If the value of the `value` argument is , the method returns . If `value` is or , the method returns or , respectively. - -## Example + +## Example + +The following example rounds double values with two fractional digits to doubles that have a single fractional digit. -The following example rounds double values with two fractional digits to doubles that have a single fractional digit. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic Math.Round2 Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System/Math/Round/source1.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System/Math/Round/source1.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Math.Round2 Example/VB/source.vb" id="Snippet1"::: - +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic Math.Round2 Example/VB/source.vb" id="Snippet1"::: + ]]> is less than 0 or greater than 15. - Because of the loss of precision that can result from representing decimal values as floating-point numbers or performing arithmetic operations on floating-point values, in some cases the method may not appear to round midpoint values to the nearest even value in the decimal position. This is illustrated in the following example, where 2.135 is rounded to 2.13 instead of 2.14. This occurs because internally the method multiplies by 10digits, and the multiplication operation in this case suffers from a loss of precision. + Because of the loss of precision that can result from representing decimal values as floating-point numbers or performing arithmetic operations on floating-point values, in some cases the method may not appear to round midpoint values to the nearest even value in the decimal position. This is illustrated in the following example, where 2.135 is rounded to 2.13 instead of 2.14. This occurs because internally the method multiplies by 10digits, and the multiplication operation in this case suffers from a loss of precision. :::code language="csharp" source="~/snippets/csharp/System/Math/Round/round3.cs" interactive="try-dotnet" id="Snippet2"::: :::code language="fsharp" source="~/snippets/fsharp/System/Math/Round/round3.fs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.math.round/vb/round3.vb" id="Snippet2"::: - + @@ -6880,32 +6880,32 @@ The following example rounds double values with two fractional digits to doubles Rounds a double-precision floating-point value to an integer using the specified rounding convention. The integer that is rounded to. This method returns a instead of an integral type. - , the method returns . If `value` is or , the method returns or , respectively. +If the value of the `value` argument is , the method returns . If `value` is or , the method returns or , respectively. - + ## Example The following example displays values returned by the method with different `mode` values. - + :::code language="csharp" source="~/snippets/csharp/System/Decimal/Round/midpoint2.cs" interactive="try-dotnet" id="Snippet6"::: :::code language="fsharp" source="~/snippets/fsharp/System/Decimal/Round/midpoint2.fs" id="Snippet6"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.math.round.overload/vb/midpoint2.vb" id="Snippet6"::: - + ]]> is not a valid value of . - Because of the loss of precision that can result from representing decimal values as floating-point numbers or performing arithmetic operations on floating-point values, in some cases the method may not appear to round midpoint values to the nearest even integer. In the following example, because the floating-point value .1 has no finite binary representation, the first call to the method with a value of 11.5 returns 11 instead of 12. - + Because of the loss of precision that can result from representing decimal values as floating-point numbers or performing arithmetic operations on floating-point values, in some cases the method may not appear to round midpoint values to the nearest even integer. In the following example, because the floating-point value .1 has no finite binary representation, the first call to the method with a value of 11.5 returns 11 instead of 12. + :::code language="csharp" source="~/snippets/csharp/System/Math/Round/round5.cs" interactive="try-dotnet" id="Snippet4"::: :::code language="fsharp" source="~/snippets/fsharp/System/Math/Round/round5.fs" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.math.round/vb/round5.vb" id="Snippet4"::: @@ -6980,18 +6980,18 @@ The following example displays values returned by the -## Example + +## Example The following example demonstrates how to use the method with the enumeration. :::code language="csharp" source="~/snippets/csharp/System/Decimal/Round/mpr.cs" interactive="try-dotnet-method" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System/Decimal/Round/mpr.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.math.round.overload/vb/mpr.vb" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.math.round.overload/vb/mpr.vb" id="Snippet1"::: ]]> @@ -7056,9 +7056,9 @@ The following example demonstrates how to use the me Rounds a double-precision floating-point value to a specified number of fractional digits using the specified rounding convention. The number that has fractional digits that is rounded to. If has fewer fractional digits than , is returned unchanged. - type is 15. @@ -7066,17 +7066,17 @@ See [Midpoint values and rounding conventions](#midpoint-values-and-rounding-con [!INCLUDE[midpoint-rounding](~/includes/floating-point-equality.md)] -If the value of the `value` argument is , the method returns . If `value` is or , the method returns or , respectively. +If the value of the `value` argument is , the method returns . If `value` is or , the method returns or , respectively. - -## Example + +## Example + +The following example demonstrates how to use the method with the enumeration. -The following example demonstrates how to use the method with the enumeration. - :::code language="csharp" source="~/snippets/csharp/System/Decimal/Round/mpr.cs" interactive="try-dotnet-method" id="Snippet4"::: :::code language="fsharp" source="~/snippets/fsharp/System/Decimal/Round/mpr.fs" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.math.round.overload/vb/mpr.vb" id="Snippet4"::: - + ]]> @@ -7084,12 +7084,12 @@ The following example demonstrates how to use the is not a valid value of . - Because of the loss of precision that can result from representing decimal values as floating-point numbers or performing arithmetic operations on floating-point values, in some cases the method may not appear to round midpoint values as specified by the parameter. This is illustrated in the following example, where 2.135 is rounded to 2.13 instead of 2.14. This occurs because internally the method multiplies by 10digits, and the multiplication operation in this case suffers from a loss of precision. + Because of the loss of precision that can result from representing decimal values as floating-point numbers or performing arithmetic operations on floating-point values, in some cases the method may not appear to round midpoint values as specified by the parameter. This is illustrated in the following example, where 2.135 is rounded to 2.13 instead of 2.14. This occurs because internally the method multiplies by 10digits, and the multiplication operation in this case suffers from a loss of precision. :::code language="csharp" source="~/snippets/csharp/System/Math/Round/round4.cs" interactive="try-dotnet-method" id="Snippet3"::: :::code language="fsharp" source="~/snippets/fsharp/System/Math/Round/round4.fs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.math.round/vb/round4.vb" id="Snippet3"::: - + @@ -7137,11 +7137,11 @@ The following example demonstrates how to use the Returns x * 2^n computed efficiently. x * 2^n computed efficiently. -
@@ -7210,36 +7210,36 @@ The following example demonstrates how to use the A signed decimal number. Returns an integer that indicates the sign of a decimal number. - A number that indicates the sign of , as shown in the following table. - - Return value - - Meaning - - -1 - - is less than zero. - - 0 - - is equal to zero. - - 1 - - is greater than zero. - + A number that indicates the sign of , as shown in the following table. + + Return value + + Meaning + + -1 + + is less than zero. + + 0 + + is equal to zero. + + 1 + + is greater than zero. + - method to determine the sign of a value and display it to the console. + method to determine the sign of a value and display it to the console. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/math.sign/CPP/sign.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System/Math/Sign/sign.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System/Math/Sign/sign.fs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/math.sign/VB/sign.vb" id="Snippet1"::: - + ]]>
@@ -7296,36 +7296,36 @@ The following example demonstrates how to use the A signed number. Returns an integer that indicates the sign of a double-precision floating-point number. - A number that indicates the sign of , as shown in the following table. - - Return value - - Meaning - - -1 - - is less than zero. - - 0 - - is equal to zero. - - 1 - - is greater than zero. - + A number that indicates the sign of , as shown in the following table. + + Return value + + Meaning + + -1 + + is less than zero. + + 0 + + is equal to zero. + + 1 + + is greater than zero. + - method to determine the sign of a value and display it to the console. + method to determine the sign of a value and display it to the console. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/math.sign/CPP/sign.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System/Math/Sign/sign.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System/Math/Sign/sign.fs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/math.sign/VB/sign.vb" id="Snippet1"::: - + ]]> @@ -7384,36 +7384,36 @@ The following example demonstrates how to use the A signed number. Returns an integer that indicates the sign of a 16-bit signed integer. - A number that indicates the sign of , as shown in the following table. - - Return value - - Meaning - - -1 - - is less than zero. - - 0 - - is equal to zero. - - 1 - - is greater than zero. - + A number that indicates the sign of , as shown in the following table. + + Return value + + Meaning + + -1 + + is less than zero. + + 0 + + is equal to zero. + + 1 + + is greater than zero. + - method to determine the sign of an value and display it to the console. + method to determine the sign of an value and display it to the console. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/math.sign/CPP/sign.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System/Math/Sign/sign.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System/Math/Sign/sign.fs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/math.sign/VB/sign.vb" id="Snippet1"::: - + ]]> @@ -7470,36 +7470,36 @@ The following example demonstrates how to use the A signed number. Returns an integer that indicates the sign of a 32-bit signed integer. - A number that indicates the sign of , as shown in the following table. - - Return value - - Meaning - - -1 - - is less than zero. - - 0 - - is equal to zero. - - 1 - - is greater than zero. - + A number that indicates the sign of , as shown in the following table. + + Return value + + Meaning + + -1 + + is less than zero. + + 0 + + is equal to zero. + + 1 + + is greater than zero. + - method to determine the sign of an value and display it to the console. - + method to determine the sign of an value and display it to the console. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/math.sign/CPP/sign.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System/Math/Sign/sign.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System/Math/Sign/sign.fs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/math.sign/VB/sign.vb" id="Snippet1"::: - + ]]> @@ -7556,36 +7556,36 @@ The following example demonstrates how to use the A signed number. Returns an integer that indicates the sign of a 64-bit signed integer. - A number that indicates the sign of , as shown in the following table. - - Return value - - Meaning - - -1 - - is less than zero. - - 0 - - is equal to zero. - - 1 - - is greater than zero. - + A number that indicates the sign of , as shown in the following table. + + Return value + + Meaning + + -1 + + is less than zero. + + 0 + + is equal to zero. + + 1 + + is greater than zero. + - method to determine the sign of an value and display it to the console. + method to determine the sign of an value and display it to the console. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/math.sign/CPP/sign.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System/Math/Sign/sign.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System/Math/Sign/sign.fs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/math.sign/VB/sign.vb" id="Snippet1"::: - + ]]> @@ -7631,34 +7631,34 @@ The following example demonstrates how to use the A signed number. Returns an integer that indicates the sign of a native sized signed integer. - A number that indicates the sign of , as shown in the following table. - - Return value - - Meaning - - -1 - - is less than zero. - - 0 - - is equal to zero. - - 1 - - is greater than zero. - + A number that indicates the sign of , as shown in the following table. + + Return value + + Meaning + + -1 + + is less than zero. + + 0 + + is equal to zero. + + 1 + + is greater than zero. + - method to determine the sign of an value and display it to the console. + method to determine the sign of an value and display it to the console. :::code language="csharp" source="~/snippets/csharp/System/Math/Sign/sign.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System/Math/Sign/sign.fs" id="Snippet1"::: - + ]]> @@ -7719,36 +7719,36 @@ The following example demonstrates how to use the A signed number. Returns an integer that indicates the sign of an 8-bit signed integer. - A number that indicates the sign of , as shown in the following table. - - Return value - - Meaning - - -1 - - is less than zero. - - 0 - - is equal to zero. - - 1 - - is greater than zero. - + A number that indicates the sign of , as shown in the following table. + + Return value + + Meaning + + -1 + + is less than zero. + + 0 + + is equal to zero. + + 1 + + is greater than zero. + - method to determine the sign of an value and display it to the console. + method to determine the sign of an value and display it to the console. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/math.sign/CPP/sign.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System/Math/Sign/sign.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System/Math/Sign/sign.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/math.sign/VB/sign.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/math.sign/VB/sign.vb" id="Snippet1"::: + ]]> @@ -7805,36 +7805,36 @@ The following example demonstrates how to use the A signed number. Returns an integer that indicates the sign of a single-precision floating-point number. - A number that indicates the sign of , as shown in the following table. - - Return value - - Meaning - - -1 - - is less than zero. - - 0 - - is equal to zero. - - 1 - - is greater than zero. - + A number that indicates the sign of , as shown in the following table. + + Return value + + Meaning + + -1 + + is less than zero. + + 0 + + is equal to zero. + + 1 + + is greater than zero. + - method to determine the sign of a value and display it to the console. + method to determine the sign of a value and display it to the console. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/math.sign/CPP/sign.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System/Math/Sign/sign.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System/Math/Sign/sign.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/math.sign/VB/sign.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/math.sign/VB/sign.vb" id="Snippet1"::: + ]]> @@ -7895,23 +7895,23 @@ The following example demonstrates how to use the Returns the sine of the specified angle. The sine of . If is equal to , , or , this method returns . - /180 to convert degrees to radians. - - This method calls into the underlying C runtime, and the exact result or valid input range may differ between different operating systems or architectures. - - - -## Examples - The following example uses to evaluate certain trigonometric identities for selected angles. + /180 to convert degrees to radians. + + This method calls into the underlying C runtime, and the exact result or valid input range may differ between different operating systems or architectures. + + + +## Examples + The following example uses to evaluate certain trigonometric identities for selected angles. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Math.SinCos/CPP/sincos.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System/Math/Cos/sincos.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System/Math/Cos/sincos.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Math.SinCos/VB/sincos.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Math.SinCos/VB/sincos.vb" id="Snippet1"::: + ]]> @@ -7957,21 +7957,21 @@ The following example demonstrates how to use the Returns the sine and cosine of the specified angle. The sine and cosine of . If is equal to , , or , this method returns . - /180 to convert degrees to radians. - - This method calls into the underlying C runtime, and the exact result or valid input range may differ between different operating systems or architectures. - - - -## Examples - The following example uses to evaluate certain trigonometric identities for selected angles. + /180 to convert degrees to radians. + + This method calls into the underlying C runtime, and the exact result or valid input range may differ between different operating systems or architectures. + + + +## Examples + The following example uses to evaluate certain trigonometric identities for selected angles. :::code language="csharp" source="~/snippets/csharp/System/Math/Cos/sincos.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System/Math/Cos/sincos.fs" id="Snippet1"::: - + ]]> @@ -8030,23 +8030,23 @@ The following example demonstrates how to use the Returns the hyperbolic sine of the specified angle. The hyperbolic sine of . If is equal to , , or , this method returns a equal to . - /180 to convert degrees to radians. - - This method calls into the underlying C runtime, and the exact result or valid input range may differ between different operating systems or architectures. - - - -## Examples - The following example uses to evaluate certain hyperbolic identities for selected values. + /180 to convert degrees to radians. + + This method calls into the underlying C runtime, and the exact result or valid input range may differ between different operating systems or architectures. + + + +## Examples + The following example uses to evaluate certain hyperbolic identities for selected values. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Math.SinhCosh/CPP/sinhcosh.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System/Math/Cosh/sinhcosh.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System/Math/Cosh/sinhcosh.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Math.SinhCosh/VB/sinhcosh.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Math.SinhCosh/VB/sinhcosh.vb" id="Snippet1"::: + ]]> @@ -8107,30 +8107,30 @@ The following example demonstrates how to use the The number whose square root is to be found. Returns the square root of a specified number. - One of the values in the following table. - - parameter - - Return value - - Zero or positive - - The positive square root of . - - Negative - + One of the values in the following table. + + parameter + + Return value + + Zero or positive + + The positive square root of . + + Negative + Equals Equals - @@ -8190,23 +8190,23 @@ The following example demonstrates how to use the Returns the tangent of the specified angle. The tangent of . If is equal to , , or , this method returns . - /180 to convert degrees to radians. - - This method calls into the underlying C runtime, and the exact result or valid input range may differ between different operating systems or architectures. - - - -## Examples - The following example demonstrates how to calculate the tangent of an angle and display it to the console. + /180 to convert degrees to radians. + + This method calls into the underlying C runtime, and the exact result or valid input range may differ between different operating systems or architectures. + + + +## Examples + The following example demonstrates how to calculate the tangent of an angle and display it to the console. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/math.atanx/CPP/atan.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System/Math/Atan/atan.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System/Math/Atan/atan.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/math.atanx/VB/atan.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/math.atanx/VB/atan.vb" id="Snippet1"::: + ]]> @@ -8265,23 +8265,23 @@ The following example demonstrates how to use the Returns the hyperbolic tangent of the specified angle. The hyperbolic tangent of . If is equal to , this method returns -1. If value is equal to , this method returns 1. If is equal to , this method returns . - /180 to convert degrees to radians. - - This method calls into the underlying C runtime, and the exact result or valid input range may differ between different operating systems or architectures. - - - -## Examples - The following example uses to evaluate certain hyperbolic tangent identities for selected values. + /180 to convert degrees to radians. + + This method calls into the underlying C runtime, and the exact result or valid input range may differ between different operating systems or architectures. + + + +## Examples + The following example uses to evaluate certain hyperbolic tangent identities for selected values. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Math.Tanh/CPP/tanh.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System/Math/Tanh/tanh.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System/Math/Tanh/tanh.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Math.Tanh/VB/tanh.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Math.Tanh/VB/tanh.vb" id="Snippet1"::: + ]]> @@ -8330,11 +8330,11 @@ The following example demonstrates how to use the Calculates the integral part of a number. - @@ -8386,20 +8386,20 @@ The following example demonstrates how to use the Calculates the integral part of a specified decimal number. The integral part of ; that is, the number that remains after any fractional digits have been discarded. - rounds `d` to the nearest integer towards zero. - - - -## Examples - The following example calls the method to truncate both a positive and a negative value. - + rounds `d` to the nearest integer towards zero. + + + +## Examples + The following example calls the method to truncate both a positive and a negative value. + :::code language="csharp" source="~/snippets/csharp/System/Math/Truncate/Truncate1.cs" interactive="try-dotnet-method" id="Snippet2"::: :::code language="fsharp" source="~/snippets/fsharp/System/Math/Truncate/Truncate1.fs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Math.Truncate/vb/Truncate1.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Math.Truncate/vb/Truncate1.vb" id="Snippet2"::: + ]]> @@ -8452,32 +8452,32 @@ The following example demonstrates how to use the A number to truncate. Calculates the integral part of a specified double-precision floating-point number. - The integral part of ; that is, the number that remains after any fractional digits have been discarded, or one of the values listed in the following table. - - Return value - + The integral part of ; that is, the number that remains after any fractional digits have been discarded, or one of the values listed in the following table. + + Return value + - rounds `d` to the nearest integer towards zero. - + rounds `d` to the nearest integer towards zero. + Starting with Visual Basic 15.8, the performance of Double-to-integer conversion is optimized if you pass the value returned by the `Truncate` method to the any of the [integral conversion functions](/dotnet/visual-basic/language-reference/functions/conversion-functions), or if the Double value returned by `Truncate` is automatically converted to an integer with [Option Strict](/dotnet/visual-basic/language-reference/statements/option-strict-statement) set to Off. This optimization allows code to run faster -- up to twice as fast for code that does a large number of conversions to integer types. The following example illustrates such an optimized conversion: - + ```vb Dim d As Double = 164.7194 Dim i As Integer = CInt(Math.Truncate(d)) ' Result: 164 ``` -## Examples - The following example calls the method to truncate both a positive and a negative value. - +## Examples + The following example calls the method to truncate both a positive and a negative value. + :::code language="csharp" source="~/snippets/csharp/System/Math/Truncate/Truncate1.cs" interactive="try-dotnet-method" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System/Math/Truncate/Truncate1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Math.Truncate/vb/Truncate1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Math.Truncate/vb/Truncate1.vb" id="Snippet1"::: + ]]> diff --git a/xml/System/MemberAccessException.xml b/xml/System/MemberAccessException.xml index 39e5414ff69..49b754de373 100644 --- a/xml/System/MemberAccessException.xml +++ b/xml/System/MemberAccessException.xml @@ -72,21 +72,21 @@ The exception that is thrown when an attempt to access a class member fails. - is the base class for , , , , and , and (.NET Native only). These exceptions are thrown when a class member is not found or access to the member is not permitted. - - is thrown by the following methods: - - of the classes, of the class, and of the class. - - Apps compiled by using the .NET Native tool chain may throw a [MissingRuntimeArtifactException](/windows/uwp/dotnet-native/missingruntimeartifactexception-class-net-native) exception at run time. `MissingRuntimeArtifactException` is an internal-only exception type derived from . The exception indicates that metadata needed for the successful execution of an app is not present at run time. You should not use a `try`/`catch` block to handle the exception. Instead, you should determine what metadata is missing and modify your app's runtime directives file to ensure that it is present at run time. - - uses the HRESULT COR_E_MEMBERACCESS, that has the value 0x8013151A. - - For a list of initial property values for an instance of , see the constructors. - + is the base class for , , , , and , and (.NET Native only). These exceptions are thrown when a class member is not found or access to the member is not permitted. + + is thrown by the following methods: + + of the classes, of the class, and of the class. + + Apps compiled by using the .NET Native tool chain may throw a [MissingRuntimeArtifactException](/windows/uwp/dotnet-native/missingruntimeartifactexception-class-net-native) exception at run time. `MissingRuntimeArtifactException` is an internal-only exception type derived from . The exception indicates that metadata needed for the successful execution of an app is not present at run time. You should not use a `try`/`catch` block to handle the exception. Instead, you should determine what metadata is missing and modify your app's runtime directives file to ensure that it is present at run time. + + uses the HRESULT COR_E_MEMBERACCESS, that has the value 0x8013151A. + + For a list of initial property values for an instance of , see the constructors. + ]]> @@ -144,18 +144,18 @@ Initializes a new instance of the class. - property of the new instance to a system-supplied message that describes the error, such as "Cannot access member." This message takes into account the current system culture. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||A null reference (`Nothing` in Visual Basic).| -||The localized error message string.| - + property of the new instance to a system-supplied message that describes the error, such as "Cannot access member." This message takes into account the current system culture. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||A null reference (`Nothing` in Visual Basic).| +||The localized error message string.| + ]]> @@ -203,18 +203,18 @@ The message that describes the error. Initializes a new instance of the class with a specified error message. - . - -|Property|Value| -|--------------|-----------| -||A null reference (`Nothing` in Visual Basic).| -||The error message string.| - + . + +|Property|Value| +|--------------|-----------| +||A null reference (`Nothing` in Visual Basic).| +||The error message string.| + ]]> @@ -269,19 +269,19 @@ - - + + The object that holds the serialized object data. The contextual information about the source or destination. Initializes a new instance of the class with serialized data. - XML and SOAP Serialization @@ -332,18 +332,18 @@ The exception that is the cause of the current exception. If the parameter is not a null reference ( in Visual Basic), the current exception is raised in a block that handles the inner exception. Initializes a new instance of the class with a specified error message and a reference to the inner exception that is the cause of this exception. - property. The property returns the same value that is passed into the constructor, or a null reference (`Nothing` in Visual Basic) if the property does not supply the inner exception value to the constructor. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||The inner exception reference.| -||The error message string.| - + property. The property returns the same value that is passed into the constructor, or a null reference (`Nothing` in Visual Basic) if the property does not supply the inner exception value to the constructor. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||The inner exception reference.| +||The error message string.| + ]]> diff --git a/xml/System/MethodAccessException.xml b/xml/System/MethodAccessException.xml index c4ea364dd96..d41371d8353 100644 --- a/xml/System/MethodAccessException.xml +++ b/xml/System/MethodAccessException.xml @@ -64,28 +64,28 @@ The exception that is thrown when there is an invalid attempt to access a method, such as accessing a private method from partially trusted code. - [!NOTE] -> This exception is not included in the [.NET for Windows Store apps](https://go.microsoft.com/fwlink/?LinkID=247912) or the [Portable Class Library](/dotnet/standard/cross-platform/cross-platform-development-with-the-portable-class-library), but it is thrown by some members that are. To catch the exception in that case, write a `catch` statement for instead. - - This exception is thrown in situations such as the following: - -- A private, protected, or internal method that would not be accessible from normal compiled code is accessed from partially trusted code by using reflection. - -- A security-critical method is accessed from transparent code. - -- The access level of a method in a class library has changed, and one or more assemblies that reference the library have not been recompiled. - +> This exception is not included in the [.NET for Windows Store apps](https://go.microsoft.com/fwlink/?LinkID=247912) or the [Portable Class Library](/dotnet/standard/cross-platform/cross-platform-development-with-the-portable-class-library), but it is thrown by some members that are. To catch the exception in that case, write a `catch` statement for instead. + + This exception is thrown in situations such as the following: + +- A private, protected, or internal method that would not be accessible from normal compiled code is accessed from partially trusted code by using reflection. + +- A security-critical method is accessed from transparent code. + +- The access level of a method in a class library has changed, and one or more assemblies that reference the library have not been recompiled. + > [!NOTE] -> Beginning with the .NET Framework 4, the common language runtime treats application code as transparent when it is run with partial trust. See [Security Considerations for Reflection](/dotnet/framework/reflection-and-codedom/security-considerations-for-reflection). - - uses the HRESULT COR_E_METHODACCESS, that has the value 0x80131510. - - For a list of initial property values for an instance of , see the constructors. - +> Beginning with the .NET Framework 4, the common language runtime treats application code as transparent when it is run with partial trust. See [Security Considerations for Reflection](/dotnet/framework/reflection-and-codedom/security-considerations-for-reflection). + + uses the HRESULT COR_E_METHODACCESS, that has the value 0x80131510. + + For a list of initial property values for an instance of , see the constructors. + ]]> @@ -139,16 +139,16 @@ Initializes a new instance of the class, setting the property of the new instance to a system-supplied message that describes the error, such as "Attempt to access the method failed." This message takes into account the current system culture. - . - -|Property|Value| -|--------------|-----------| -||A null reference (`Nothing` in Visual Basic).| -||The localized error message string.| - + . + +|Property|Value| +|--------------|-----------| +||A null reference (`Nothing` in Visual Basic).| +||The localized error message string.| + ]]> @@ -194,18 +194,18 @@ A that describes the error. Initializes a new instance of the class with a specified error message. - . - -|Property|Value| -|--------------|-----------| -||A null reference (`Nothing` in Visual Basic).| -||The error message string.| - + . + +|Property|Value| +|--------------|-----------| +||A null reference (`Nothing` in Visual Basic).| +||The error message string.| + ]]> @@ -260,19 +260,19 @@ - - + + The object that holds the serialized object data. The contextual information about the source or destination. Initializes a new instance of the class with serialized data. - XML and SOAP Serialization @@ -321,18 +321,18 @@ The exception that is the cause of the current exception. If the parameter is not a null reference ( in Visual Basic), the current exception is raised in a block that handles the inner exception. Initializes a new instance of the class with a specified error message and a reference to the inner exception that is the cause of this exception. - property. The property returns the same value that is passed into the constructor, or a null reference (`Nothing` in Visual Basic) if the property does not supply the inner exception value to the constructor. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||The inner exception reference.| -||The error message string.| - + property. The property returns the same value that is passed into the constructor, or a null reference (`Nothing` in Visual Basic) if the property does not supply the inner exception value to the constructor. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||The inner exception reference.| +||The error message string.| + ]]> diff --git a/xml/System/MissingFieldException.xml b/xml/System/MissingFieldException.xml index 7b12e563f44..2d952ee5652 100644 --- a/xml/System/MissingFieldException.xml +++ b/xml/System/MissingFieldException.xml @@ -70,25 +70,25 @@ The exception that is thrown when there is an attempt to dynamically access a field that does not exist. If a field in a class library has been removed or renamed, recompile any assemblies that reference that library. - is designed to handle cases where an attempt is made to dynamically access a renamed or deleted field of an assembly that is not referenced by its strong name. The is thrown when code in a dependent assembly attempts to access a missing field in an assembly that was modified. - - uses the HRESULT COR_E_MISSINGFIELD, that has the value 0x80131511. - - For a list of initial property values for an instance of , see the constructors. - - - -## Examples - This example shows what happens if you attempt to use reflection to call a method that does not exist and access a field that does not exist. The application recovers by catching the , , and . - + is designed to handle cases where an attempt is made to dynamically access a renamed or deleted field of an assembly that is not referenced by its strong name. The is thrown when code in a dependent assembly attempts to access a missing field in an assembly that was modified. + + uses the HRESULT COR_E_MISSINGFIELD, that has the value 0x80131511. + + For a list of initial property values for an instance of , see the constructors. + + + +## Examples + This example shows what happens if you attempt to use reflection to call a method that does not exist and access a field that does not exist. The application recovers by catching the , , and . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/MissingMethodException/cpp/MissingMethodException.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System/MissingFieldException/Overview/MissingMethodException.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System/MissingFieldException/Overview/MissingMethodException.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/MissingMethodException/vb/missingmethodexception.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/MissingMethodException/vb/missingmethodexception.vb" id="Snippet1"::: + ]]> @@ -142,18 +142,18 @@ Initializes a new instance of the class. - property of the new instance to a system-supplied message that describes the error, such as "Attempted to access a non-existing field." This message takes into account the current system culture. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||A null reference (`Nothing` in Visual Basic).| -||The localized error message string.| - + property of the new instance to a system-supplied message that describes the error, such as "Attempted to access a non-existing field." This message takes into account the current system culture. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||A null reference (`Nothing` in Visual Basic).| +||The localized error message string.| + ]]> @@ -205,18 +205,18 @@ A that describes the error. Initializes a new instance of the class with a specified error message. - . - -|Property|Value| -|--------------|-----------| -||A null reference (`Nothing` in Visual Basic).| -||The error message string.| - + . + +|Property|Value| +|--------------|-----------| +||A null reference (`Nothing` in Visual Basic).| +||The error message string.| + ]]> @@ -267,19 +267,19 @@ - - + + The object that holds the serialized object data. The contextual information about the source or destination. Initializes a new instance of the class with serialized data. - XML and SOAP Serialization @@ -334,18 +334,18 @@ The exception that is the cause of the current exception. If the parameter is not a null reference ( in Visual Basic), the current exception is raised in a block that handles the inner exception. Initializes a new instance of the class with a specified error message and a reference to the inner exception that is the cause of this exception. - property. The property returns the same value that is passed into the constructor, or a null reference (`Nothing` in Visual Basic) if the property does not supply the inner exception value to the constructor. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||The inner exception reference.| -||The error message string.| - + property. The property returns the same value that is passed into the constructor, or a null reference (`Nothing` in Visual Basic) if the property does not supply the inner exception value to the constructor. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||The inner exception reference.| +||The error message string.| + ]]> @@ -390,8 +390,8 @@ - - + + The name of the class in which access to a nonexistent field was attempted. @@ -446,21 +446,21 @@ Gets the text string showing the signature of the missing field, the class name, and the field name. This property is read-only. The error message string. - . The error message should be localized. - - - -## Examples - The following example demonstrates the property. This code example is part of a larger example provided for the class. - + . The error message should be localized. + + + +## Examples + The following example demonstrates the property. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/MissingMethodException/cpp/MissingMethodException.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System/MissingFieldException/Overview/MissingMethodException.cs" id="Snippet3"::: :::code language="fsharp" source="~/snippets/fsharp/System/MissingFieldException/Overview/MissingMethodException.fs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/MissingMethodException/vb/missingmethodexception.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/MissingMethodException/vb/missingmethodexception.vb" id="Snippet3"::: + ]]> diff --git a/xml/System/MissingMemberException.xml b/xml/System/MissingMemberException.xml index ef41d50e7f5..e909bc9af6d 100644 --- a/xml/System/MissingMemberException.xml +++ b/xml/System/MissingMemberException.xml @@ -72,27 +72,27 @@ The exception that is thrown when there is an attempt to dynamically access a class member that does not exist or that is not declared as public. If a member in a class library has been removed or renamed, recompile any assemblies that reference that library. - is designed to handle cases where a field or a method is deleted or renamed in one assembly and the change is not reflected in a second assembly. At runtime, will be thrown when the code in the second assembly attempts to access the missing member in the first assembly. - - is the base class for and . In general it is better to use one of the derived classes of to more precisely indicate the exact nature of the error. Throw a if you are only interested in capturing the general case of a missing member error. - - uses the HRESULT COR_E_MISSINGMEMBER, that has the value 0x80131512. - - For a list of initial property values for an instance of , see the constructors. - - - -## Examples - This example shows what happens if you attempt to use reflection to call a method that does not exist and access a field that does not exist. The application recovers by catching the , , and . - + is designed to handle cases where a field or a method is deleted or renamed in one assembly and the change is not reflected in a second assembly. At runtime, will be thrown when the code in the second assembly attempts to access the missing member in the first assembly. + + is the base class for and . In general it is better to use one of the derived classes of to more precisely indicate the exact nature of the error. Throw a if you are only interested in capturing the general case of a missing member error. + + uses the HRESULT COR_E_MISSINGMEMBER, that has the value 0x80131512. + + For a list of initial property values for an instance of , see the constructors. + + + +## Examples + This example shows what happens if you attempt to use reflection to call a method that does not exist and access a field that does not exist. The application recovers by catching the , , and . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/MissingMethodException/cpp/MissingMethodException.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System/MissingFieldException/Overview/MissingMethodException.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System/MissingFieldException/Overview/MissingMethodException.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/MissingMethodException/vb/missingmethodexception.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/MissingMethodException/vb/missingmethodexception.vb" id="Snippet1"::: + ]]> @@ -152,18 +152,18 @@ Initializes a new instance of the class. - property of the new instance to a system-supplied message that describes the error, such as "Attempted to access a missing member." This message takes into account the current system culture. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||A null reference (`Nothing` in Visual Basic).| -||The localized error message string.| - + property of the new instance to a system-supplied message that describes the error, such as "Attempted to access a missing member." This message takes into account the current system culture. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||A null reference (`Nothing` in Visual Basic).| +||The localized error message string.| + ]]> @@ -211,18 +211,18 @@ The message that describes the error. Initializes a new instance of the class with a specified error message. - . - -|Property|Value| -|--------------|-----------| -||A null reference (`Nothing` in Visual Basic).| -||The error message string.| - + . + +|Property|Value| +|--------------|-----------| +||A null reference (`Nothing` in Visual Basic).| +||The error message string.| + ]]> @@ -277,19 +277,19 @@ - - + + The object that holds the serialized object data. The contextual information about the source or destination. Initializes a new instance of the class with serialized data. - XML and SOAP Serialization @@ -340,18 +340,18 @@ An instance of that is the cause of the current . If is not a null reference ( in Visual Basic), then the current is raised in a catch block handling . Initializes a new instance of the class with a specified error message and a reference to the inner exception that is the root cause of this exception. - property. The property returns the same value that is passed into the constructor, or a null reference (`Nothing` in Visual Basic) if the property does not supply the inner exception value to the constructor. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||The inner exception reference.| -||The error message string.| - + property. The property returns the same value that is passed into the constructor, or a null reference (`Nothing` in Visual Basic) if the property does not supply the inner exception value to the constructor. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||The inner exception reference.| +||The error message string.| + ]]> @@ -391,8 +391,8 @@ 9.0.0.0 - - + + The name of the class in which access to a nonexistent member was attempted. @@ -497,21 +497,21 @@ System.Void - - + + The object that holds the serialized object data. The contextual information about the source or destination. Sets the object with the class name, the member name, the signature of the missing member, and additional exception information. - 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 . - + 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 . + ]]> The object is . @@ -615,25 +615,25 @@ Gets the text string showing the class name, the member name, and the signature of the missing member. The error message string. - . The error message should be localized. - - This property is read-only. - - - -## Examples - The following example demonstrates the property. This code example is part of a larger example provided for the class. - + . The error message should be localized. + + This property is read-only. + + + +## Examples + The following example demonstrates the property. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/MissingMethodException/cpp/MissingMethodException.cpp" id="Snippet4"::: :::code language="csharp" source="~/snippets/csharp/System/MissingFieldException/Overview/MissingMethodException.cs" id="Snippet4"::: :::code language="fsharp" source="~/snippets/fsharp/System/MissingFieldException/Overview/MissingMethodException.fs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/MissingMethodException/vb/missingmethodexception.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/MissingMethodException/vb/missingmethodexception.vb" id="Snippet4"::: + ]]> @@ -680,13 +680,13 @@ Holds the signature of the missing member. - contains a value that represents the signature of the missing member. - - is used to format the signature. For additional information, see , , and . - + contains a value that represents the signature of the missing member. + + is used to format the signature. For additional information, see , , and . + ]]> diff --git a/xml/System/MissingMethodException.xml b/xml/System/MissingMethodException.xml index 7fd418d358d..da8d9d431b7 100644 --- a/xml/System/MissingMethodException.xml +++ b/xml/System/MissingMethodException.xml @@ -70,25 +70,25 @@ The exception that is thrown when there is an attempt to dynamically access a method that does not exist. - is designed to handle cases where an attempt is made to dynamically access a renamed or deleted method of an assembly that is not referenced by its strong name. is thrown when code in a dependent assembly attempts to access a missing method in an assembly that was modified. - - uses the HRESULT COR_E_MISSINGMETHOD, that has the value 0x80131513. - - For a list of initial property values for an instance of , see the constructors. - + is designed to handle cases where an attempt is made to dynamically access a renamed or deleted method of an assembly that is not referenced by its strong name. is thrown when code in a dependent assembly attempts to access a missing method in an assembly that was modified. + + uses the HRESULT COR_E_MISSINGMETHOD, that has the value 0x80131513. + + For a list of initial property values for an instance of , see the constructors. + The exact timing of when statically referenced methods are loaded is unspecified. This exception may be thrown before the method that references the missing method starts executing. - + > [!NOTE] -> This exception is not included in [.NET for Windows Store apps](https://go.microsoft.com/fwlink/?LinkID=247912) or the [Portable Class Library](/dotnet/standard/cross-platform/cross-platform-development-with-the-portable-class-library), but it is thrown by some members that are. To catch the exception in that case, write a `catch` statement for instead. - - - -## Examples - This example shows what happens if you attempt to use reflection to call a method that does not exist and access a field that does not exist. The application recovers by catching the , , and . - +> This exception is not included in [.NET for Windows Store apps](https://go.microsoft.com/fwlink/?LinkID=247912) or the [Portable Class Library](/dotnet/standard/cross-platform/cross-platform-development-with-the-portable-class-library), but it is thrown by some members that are. To catch the exception in that case, write a `catch` statement for instead. + + + +## Examples + This example shows what happens if you attempt to use reflection to call a method that does not exist and access a field that does not exist. The application recovers by catching the , , and . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/MissingMethodException/cpp/MissingMethodException.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System/MissingFieldException/Overview/MissingMethodException.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System/MissingFieldException/Overview/MissingMethodException.fs" id="Snippet1"::: @@ -147,18 +147,18 @@ The exact timing of when statically referenced methods are loaded is unspecified Initializes a new instance of the class. - property of the new instance to a system-supplied message that describes the error, such as "Attempted to access a missing method." This message takes into account the current system culture. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||A null reference (`Nothing` in Visual Basic).| -||The localized error message string.| - + property of the new instance to a system-supplied message that describes the error, such as "Attempted to access a missing method." This message takes into account the current system culture. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||A null reference (`Nothing` in Visual Basic).| +||The localized error message string.| + ]]> @@ -210,18 +210,18 @@ The exact timing of when statically referenced methods are loaded is unspecified A that describes the error. Initializes a new instance of the class with a specified error message. - . - -|Property|Value| -|--------------|-----------| -||A null reference (`Nothing` in Visual Basic).| -||The error message string.| - + . + +|Property|Value| +|--------------|-----------| +||A null reference (`Nothing` in Visual Basic).| +||The error message string.| + ]]> XML and SOAP Serialization @@ -273,19 +273,19 @@ The exact timing of when statically referenced methods are loaded is unspecified - - + + The object that holds the serialized object data. The contextual information about the source or destination. Initializes a new instance of the class with serialized data. - XML and SOAP Serialization @@ -340,18 +340,18 @@ The exact timing of when statically referenced methods are loaded is unspecified The exception that is the cause of the current exception. If the parameter is not a null reference ( in Visual Basic), the current exception is raised in a block that handles the inner exception. Initializes a new instance of the class with a specified error message and a reference to the inner exception that is the cause of this exception. - property. The property returns the same value that is passed into the constructor, or a null reference (`Nothing` in Visual Basic) if the property does not supply the inner exception value to the constructor. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||The inner exception reference.| -||The error message string.| - + property. The property returns the same value that is passed into the constructor, or a null reference (`Nothing` in Visual Basic) if the property does not supply the inner exception value to the constructor. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||The inner exception reference.| +||The error message string.| + ]]> @@ -397,8 +397,8 @@ The exact timing of when statically referenced methods are loaded is unspecified - - + + The name of the class in which access to a nonexistent method was attempted. @@ -453,23 +453,23 @@ The exact timing of when statically referenced methods are loaded is unspecified Gets the text string showing the class name, the method name, and the signature of the missing method. This property is read-only. The error message string. - . The error message should be localized. - - - -## Examples - The following example demonstrates the property. This code example is part of a larger example provided for the class. - + . The error message should be localized. + + + +## Examples + The following example demonstrates the property. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/MissingMethodException/cpp/MissingMethodException.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System/MissingFieldException/Overview/MissingMethodException.cs" id="Snippet2"::: :::code language="fsharp" source="~/snippets/fsharp/System/MissingFieldException/Overview/MissingMethodException.fs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/MissingMethodException/vb/missingmethodexception.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/MissingMethodException/vb/missingmethodexception.vb" id="Snippet2"::: + ]]> diff --git a/xml/System/MulticastDelegate.xml b/xml/System/MulticastDelegate.xml index 1436938a11a..48812f12911 100644 --- a/xml/System/MulticastDelegate.xml +++ b/xml/System/MulticastDelegate.xml @@ -66,30 +66,30 @@ Represents a multicast delegate; that is, a delegate that can have more than one element in its invocation list. - is a special class. Compilers and other tools can derive from this class, but you cannot derive from it explicitly. The same is true of the class. - - In addition to the methods that delegate types inherit from , the common language runtime provides two special methods: `BeginInvoke` and `EndInvoke`. For more information about these methods, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously). - - A has a linked list of delegates, called an invocation list, consisting of one or more elements. When a multicast delegate is invoked, the delegates in the invocation list are called synchronously in the order in which they appear. If an error occurs during execution of the list then an exception is thrown. - - - -## Examples - The following example defines a class, `StringContainer`, which includes a collection of strings. One of its members is the `CheckAndDisplayDelegate` delegate, which is used to display strings stored in a `StringContainer` object that satisfy particular criteria. The delegate takes a single string as a parameter and returns `void` (or, in Visual Basic, it's a `Sub` procedure). It also includes a method, `DisplayAllQualified`, that has a single parameter, a `CheckAndDisplayDelegate` delegate. This allows the method to be called and to display a set of strings that are filtered based on the methods that the delegate contains. - - The example also defines a utility class, `StringExtensions`, that has two methods: - -- `ConStart`, which displays strings that begin with a consonant. - -- `VowelStart`, which displays strings that begin with a vowel. - - Note that both methods include a single string parameter and return `void`. In other words, both methods can be assigned to the `CheckAndDisplayDelegate` delegate. - - The `Test.Main` method is the application entry point. It instantiates a `StringContainer` object, populates it with strings, and creates two `CheckAndDisplayDelegate` delegates, `conStart` and `vowelStart`, that invoke a single method. It then calls the method to create the `multipleDelegates` delegate, which initially contains the `ConStart` and `VowelStart` delegates. Note that when the `multipleDelegates` delegate is invoked, it displays all the strings in the collection in their original order. This is because each letter is passed separately to each delegate, and each letter meets the filtering criteria of only one of the two delegates. Finally, after calls to and , `multipleDelegates` contains two `conStart` delegates. When it is invoked, each string in the `StringContainer` object is displayed twice. - + is a special class. Compilers and other tools can derive from this class, but you cannot derive from it explicitly. The same is true of the class. + + In addition to the methods that delegate types inherit from , the common language runtime provides two special methods: `BeginInvoke` and `EndInvoke`. For more information about these methods, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously). + + A has a linked list of delegates, called an invocation list, consisting of one or more elements. When a multicast delegate is invoked, the delegates in the invocation list are called synchronously in the order in which they appear. If an error occurs during execution of the list then an exception is thrown. + + + +## Examples + The following example defines a class, `StringContainer`, which includes a collection of strings. One of its members is the `CheckAndDisplayDelegate` delegate, which is used to display strings stored in a `StringContainer` object that satisfy particular criteria. The delegate takes a single string as a parameter and returns `void` (or, in Visual Basic, it's a `Sub` procedure). It also includes a method, `DisplayAllQualified`, that has a single parameter, a `CheckAndDisplayDelegate` delegate. This allows the method to be called and to display a set of strings that are filtered based on the methods that the delegate contains. + + The example also defines a utility class, `StringExtensions`, that has two methods: + +- `ConStart`, which displays strings that begin with a consonant. + +- `VowelStart`, which displays strings that begin with a vowel. + + Note that both methods include a single string parameter and return `void`. In other words, both methods can be assigned to the `CheckAndDisplayDelegate` delegate. + + The `Test.Main` method is the application entry point. It instantiates a `StringContainer` object, populates it with strings, and creates two `CheckAndDisplayDelegate` delegates, `conStart` and `vowelStart`, that invoke a single method. It then calls the method to create the `multipleDelegates` delegate, which initially contains the `ConStart` and `VowelStart` delegates. Note that when the `multipleDelegates` delegate is invoked, it displays all the strings in the collection in their original order. This is because each letter is passed separately to each delegate, and each letter meets the filtering criteria of only one of the two delegates. Finally, after calls to and , `multipleDelegates` contains two `conStart` delegates. When it is invoked, each string in the `StringContainer` object is displayed twice. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Multicast Delegate Introduction/CPP/delegatestring.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System/MulticastDelegate/Overview/delegatestring.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System/MulticastDelegate/Overview/delegatestring.fs" id="Snippet1"::: @@ -147,19 +147,19 @@ - - + + The object on which is defined. The name of the method for which a delegate is created. Initializes a new instance of the class. - method that specifies a method name and a target object. For example, the method overload creates a delegate for an instance method with a specified name. - + method that specifies a method name and a target object. For example, the method overload creates a delegate for an instance method with a specified name. + ]]> Cannot create an instance of an abstract class, or this member was invoked with a late-binding mechanism. @@ -197,7 +197,7 @@ 9.0.0.0 - + [System.Diagnostics.CodeAnalysis.DynamicallyAccessedMembers(System.Diagnostics.CodeAnalysis.DynamicallyAccessedMemberTypes.All)] @@ -205,18 +205,18 @@ - + The type of object on which is defined. The name of the static method for which a delegate is created. Initializes a new instance of the class. - method that specifies a method name but does not specify a target object. For example, the method overload creates a static delegate for a method with a specified name. - + method that specifies a method name but does not specify a target object. For example, the method overload creates a static delegate for a method with a specified name. + ]]> Cannot create an instance of an abstract class, or this member was invoked with a late-binding mechanism. @@ -264,7 +264,7 @@ System.Delegate - + [System.Runtime.CompilerServices.Nullable(2)] @@ -305,7 +305,7 @@ System.Object - + The arguments to pass to the encapsulated method. @@ -388,13 +388,13 @@ if and this instance have the same invocation lists; otherwise, . - Cannot create an instance of an abstract class, or this member was invoked with a late-binding mechanism. @@ -501,11 +501,11 @@ Returns the invocation list of this multicast delegate, in invocation order. An array of delegates whose invocation lists collectively match the invocation list of this instance. - Cannot create an instance of an abstract class, or this member was invoked with a late-binding mechanism. @@ -555,11 +555,11 @@ Returns a method represented by the current . A method represented by the current . - represents multiple methods, only one method is returned. - + represents multiple methods, only one method is returned. + ]]> @@ -613,21 +613,21 @@ System.Void - - + + An object that holds all the data needed to serialize or deserialize this instance. (Reserved) The location where serialized data is stored and retrieved. Populates a object with all the data needed to serialize this instance. - @@ -694,13 +694,13 @@ if and have the same invocation lists; otherwise, . - ]]> Cannot create an instance of an abstract class, or this member was invoked with a late-binding mechanism. @@ -762,13 +762,13 @@ if and do not have the same invocation lists; otherwise, . - ]]> Cannot create an instance of an abstract class, or this member was invoked with a late-binding mechanism. @@ -816,7 +816,7 @@ System.Delegate - + The delegate to search for in the invocation list. diff --git a/xml/System/NotImplementedException.xml b/xml/System/NotImplementedException.xml index 6ca49c1d9cb..be5f1106022 100644 --- a/xml/System/NotImplementedException.xml +++ b/xml/System/NotImplementedException.xml @@ -257,8 +257,8 @@ The following example throws this exception for a method that has not been devel - - + + The that holds the serialized object data about the exception being thrown. diff --git a/xml/System/NotSupportedException.xml b/xml/System/NotSupportedException.xml index c7c3b407b0d..94cf956985f 100644 --- a/xml/System/NotSupportedException.xml +++ b/xml/System/NotSupportedException.xml @@ -249,8 +249,8 @@ - - + + The object that holds the serialized object data. diff --git a/xml/System/NullReferenceException.xml b/xml/System/NullReferenceException.xml index ba176ff3a47..4e22c6bc02e 100644 --- a/xml/System/NullReferenceException.xml +++ b/xml/System/NullReferenceException.xml @@ -72,107 +72,107 @@ The exception that is thrown when there is an attempt to dereference a null object reference. - exception is thrown when you try to access a member on a type whose value is `null`. A exception typically reflects developer error and is thrown in the following scenarios: - -- You've forgotten to instantiate a reference type. In the following example, `names` is declared but never instantiated: - + exception is thrown when you try to access a member on a type whose value is `null`. A exception typically reflects developer error and is thrown in the following scenarios: + +- You've forgotten to instantiate a reference type. In the following example, `names` is declared but never instantiated: + :::code language="csharp" source="~/snippets/csharp/System/NullReferenceException/Overview/example1.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System/NullReferenceException/Overview/example1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.nullreferenceexception.class/vb/example1.vb" id="Snippet1"::: - - Some compilers issue a warning when they compile this code. Others issue an error, and the compilation fails. To address this problem, instantiate the object so that its value is no longer `null`. The following example does this by calling a type's class constructor. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.nullreferenceexception.class/vb/example1.vb" id="Snippet1"::: + + Some compilers issue a warning when they compile this code. Others issue an error, and the compilation fails. To address this problem, instantiate the object so that its value is no longer `null`. The following example does this by calling a type's class constructor. + :::code language="csharp" source="~/snippets/csharp/System/NullReferenceException/Overview/example1a.cs" id="Snippet2"::: :::code language="fsharp" source="~/snippets/fsharp/System/NullReferenceException/Overview/example1a.fs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.nullreferenceexception.class/vb/example1a.vb" id="Snippet2"::: - -- You've forgotten to dimension an array before initializing it. In the following example, `values` is declared to be an integer array, but the number of elements that it contains is never specified. The attempt to initialize its values therefore thrown a exception. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.nullreferenceexception.class/vb/example1a.vb" id="Snippet2"::: + +- You've forgotten to dimension an array before initializing it. In the following example, `values` is declared to be an integer array, but the number of elements that it contains is never specified. The attempt to initialize its values therefore thrown a exception. + :::code language="csharp" source="~/snippets/csharp/System/NullReferenceException/Overview/Array3.cs" id="Snippet10"::: :::code language="fsharp" source="~/snippets/fsharp/System/NullReferenceException/Overview/Array3.fs" id="Snippet10"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.nullreferenceexception.class/vb/Array3.vb" id="Snippet10"::: - - You can eliminate the exception by declaring the number of elements in the array before initializing it, as the following example does. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.nullreferenceexception.class/vb/Array3.vb" id="Snippet10"::: + + You can eliminate the exception by declaring the number of elements in the array before initializing it, as the following example does. + :::code language="csharp" source="~/snippets/csharp/System/NullReferenceException/Overview/Array4.cs" id="Snippet11"::: :::code language="fsharp" source="~/snippets/fsharp/System/NullReferenceException/Overview/Array4.fs" id="Snippet11"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.nullreferenceexception.class/vb/Array4.vb" id="Snippet11"::: - - For more information on declaring and initializing arrays, see [Arrays](/dotnet/csharp/programming-guide/arrays/) and [Arrays](/dotnet/visual-basic/programming-guide/language-features/arrays/). - -- You get a **null** return value from a method, and then call a method on the returned type. This sometimes is the result of a documentation error; the documentation fails to note that a method call can return `null`. In other cases, your code erroneously assumes that the method will always return a non-**null** value. - - The code in the following example assumes that the method always returns `Person` object whose `FirstName` field matches a search string. Because there is no match, the runtime throws a exception. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.nullreferenceexception.class/vb/Array4.vb" id="Snippet11"::: + + For more information on declaring and initializing arrays, see [Arrays](/dotnet/csharp/programming-guide/arrays/) and [Arrays](/dotnet/visual-basic/programming-guide/language-features/arrays/). + +- You get a **null** return value from a method, and then call a method on the returned type. This sometimes is the result of a documentation error; the documentation fails to note that a method call can return `null`. In other cases, your code erroneously assumes that the method will always return a non-**null** value. + + The code in the following example assumes that the method always returns `Person` object whose `FirstName` field matches a search string. Because there is no match, the runtime throws a exception. + :::code language="csharp" source="~/snippets/csharp/System/NullReferenceException/Overview/nullreturn2.cs" id="Snippet4"::: :::code language="fsharp" source="~/snippets/fsharp/System/NullReferenceException/Overview/nullreturn2.fs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.nullreferenceexception.class/vb/nullreturn2.vb" id="Snippet4"::: - - To address this problem, test the method's return value to ensure that it is not `null` before calling any of its members, as the following example does. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.nullreferenceexception.class/vb/nullreturn2.vb" id="Snippet4"::: + + To address this problem, test the method's return value to ensure that it is not `null` before calling any of its members, as the following example does. + :::code language="csharp" source="~/snippets/csharp/System/NullReferenceException/Overview/nullreturn2a.cs" id="Snippet5"::: :::code language="fsharp" source="~/snippets/fsharp/System/NullReferenceException/Overview/nullreturn2a.fs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.nullreferenceexception.class/vb/nullreturn2a.vb" id="Snippet5"::: - -- You're using an expression (for example, you're chaining a list of methods or properties together) to retrieve a value and, although you're checking whether the value is `null`, the runtime still throws a exception. This occurs because one of the intermediate values in the expression returns `null`. As a result, your test for `null` is never evaluated. - - The following example defines a `Pages` object that caches information about web pages, which are presented by `Page` objects. The `Example.Main` method checks whether the current web page has a non-null title and, if it does, displays the title. Despite this check, however, the method throws a exception. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.nullreferenceexception.class/vb/nullreturn2a.vb" id="Snippet5"::: + +- You're using an expression (for example, you're chaining a list of methods or properties together) to retrieve a value and, although you're checking whether the value is `null`, the runtime still throws a exception. This occurs because one of the intermediate values in the expression returns `null`. As a result, your test for `null` is never evaluated. + + The following example defines a `Pages` object that caches information about web pages, which are presented by `Page` objects. The `Example.Main` method checks whether the current web page has a non-null title and, if it does, displays the title. Despite this check, however, the method throws a exception. + :::code language="csharp" source="~/snippets/csharp/System/NullReferenceException/Overview/Chain1.cs" id="Snippet6"::: :::code language="fsharp" source="~/snippets/fsharp/System/NullReferenceException/Overview/Chain1.fs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.nullreferenceexception.class/vb/Chain1.vb" id="Snippet6"::: - - The exception is thrown because `pages.CurrentPage` returns `null` if no page information is stored in the cache. This exception can be corrected by testing the value of the `CurrentPage` property before retrieving the current `Page` object's `Title` property, as the following example does: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.nullreferenceexception.class/vb/Chain1.vb" id="Snippet6"::: + + The exception is thrown because `pages.CurrentPage` returns `null` if no page information is stored in the cache. This exception can be corrected by testing the value of the `CurrentPage` property before retrieving the current `Page` object's `Title` property, as the following example does: + :::code language="csharp" source="~/snippets/csharp/System/NullReferenceException/Overview/Chain2.cs" id="Snippet7"::: :::code language="fsharp" source="~/snippets/fsharp/System/NullReferenceException/Overview/Chain2.fs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.nullreferenceexception.class/vb/Chain2.vb" id="Snippet7"::: - -- You're enumerating the elements of an array that contains reference types, and your attempt to process one of the elements throws a exception. - - The following example defines a string array. A `for` statement enumerates the elements in the array and calls each string's method before displaying the string. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.nullreferenceexception.class/vb/Chain2.vb" id="Snippet7"::: + +- You're enumerating the elements of an array that contains reference types, and your attempt to process one of the elements throws a exception. + + The following example defines a string array. A `for` statement enumerates the elements in the array and calls each string's method before displaying the string. + :::code language="csharp" source="~/snippets/csharp/System/NullReferenceException/Overview/Array1.cs" id="Snippet8"::: :::code language="fsharp" source="~/snippets/fsharp/System/NullReferenceException/Overview/Array1.fs" id="Snippet8"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.nullreferenceexception.class/vb/Array1.vb" id="Snippet8"::: - - This exception occurs if you assume that each element of the array must contain a non-null value, and the value of the array element is in fact `null`. The exception can be eliminated by testing whether the element is `null` before performing any operation on that element, as the following example shows. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.nullreferenceexception.class/vb/Array1.vb" id="Snippet8"::: + + This exception occurs if you assume that each element of the array must contain a non-null value, and the value of the array element is in fact `null`. The exception can be eliminated by testing whether the element is `null` before performing any operation on that element, as the following example shows. + :::code language="csharp" source="~/snippets/csharp/System/NullReferenceException/Overview/Array2.cs" id="Snippet9"::: :::code language="fsharp" source="~/snippets/fsharp/System/NullReferenceException/Overview/Array2.fs" id="Snippet9"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.nullreferenceexception.class/vb/Array2.vb" id="Snippet9"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.nullreferenceexception.class/vb/Array2.vb" id="Snippet9"::: + - A exception can be thrown by a method when it accesses a member of one of its arguments, but that argument is `null`. The `PopulateNames` method in the following example throws the exception at the line `names.Add(arrName);`. - + :::code language="csharp" source="~/snippets/csharp/System/NullReferenceException/Overview/example2.cs" id="Snippet3"::: :::code language="fsharp" source="~/snippets/fsharp/System/NullReferenceException/Overview/example2.fs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.nullreferenceexception.class/vb/example2.vb" id="Snippet3"::: - - To address this issue, make sure that the argument passed to the method is not `null`, or handle the thrown exception in a `try…catch…finally` block. For more information, see [Exceptions](/dotnet/standard/exceptions/). - - The following Microsoft intermediate language (MSIL) instructions throw : `callvirt`, `cpblk`, `cpobj`, `initblk`, `ldelem.`, `ldelema`, `ldfld`, `ldflda`, `ldind.`, `ldlen`, `stelem.`, `stfld`, `stind.`, `throw`, and `unbox`. - - uses the HRESULT COR_E_NULLREFERENCE, which has the value 0x80004003. - - For a list of initial property values for an instance of , see the constructors. - - **Handling NullReferenceException in release code** - - It's usually better to avoid a NullReferenceException than to handle it after it occurs. Handling an exception can make your code harder to maintain and understand, and can sometimes introduce other bugs. A NullReferenceException is often a non-recoverable error. In these cases, letting the exception stop the app might be the best alternative. - - However, there are many situations where handling the error can be useful: - -- Your app can ignore objects that are null. For example, if your app retrieves and processes records in a database, you might be able to ignore some number of bad records that result in null objects. Recording the bad data in a log file or in the application UI might be all you have to do. - -- You can recover from the exception. For example, a call to a web service that returns a reference type might return null if the connection is lost or the connection times out. You can attempt to reestablish the connection and try the call again. - -- You can restore the state of your app to a valid state. For example, you might be performing a multi-step task that requires you to save information to a data store before you call a method that throws a NullReferenceException. If the uninitialized object would corrupt the data record, you can remove the previous data before you close the app. - -- You want to report the exception. For example, if the error was caused by a mistake from the user of your app, you can generate a message to help them supply the correct information. You can also log information about the error to help you fix the problem. Some frameworks, like ASP.NET, have a high-level exception handler that captures all errors to that the app never crashes; in that case, logging the exception might be the only way you can know that it occurs. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.nullreferenceexception.class/vb/example2.vb" id="Snippet3"::: + + To address this issue, make sure that the argument passed to the method is not `null`, or handle the thrown exception in a `try…catch…finally` block. For more information, see [Exceptions](/dotnet/standard/exceptions/). + + The following Microsoft intermediate language (MSIL) instructions throw : `callvirt`, `cpblk`, `cpobj`, `initblk`, `ldelem.`, `ldelema`, `ldfld`, `ldflda`, `ldind.`, `ldlen`, `stelem.`, `stfld`, `stind.`, `throw`, and `unbox`. + + uses the HRESULT COR_E_NULLREFERENCE, which has the value 0x80004003. + + For a list of initial property values for an instance of , see the constructors. + + **Handling NullReferenceException in release code** + + It's usually better to avoid a NullReferenceException than to handle it after it occurs. Handling an exception can make your code harder to maintain and understand, and can sometimes introduce other bugs. A NullReferenceException is often a non-recoverable error. In these cases, letting the exception stop the app might be the best alternative. + + However, there are many situations where handling the error can be useful: + +- Your app can ignore objects that are null. For example, if your app retrieves and processes records in a database, you might be able to ignore some number of bad records that result in null objects. Recording the bad data in a log file or in the application UI might be all you have to do. + +- You can recover from the exception. For example, a call to a web service that returns a reference type might return null if the connection is lost or the connection times out. You can attempt to reestablish the connection and try the call again. + +- You can restore the state of your app to a valid state. For example, you might be performing a multi-step task that requires you to save information to a data store before you call a method that throws a NullReferenceException. If the uninitialized object would corrupt the data record, you can remove the previous data before you close the app. + +- You want to report the exception. For example, if the error was caused by a mistake from the user of your app, you can generate a message to help them supply the correct information. You can also log information about the error to help you fix the problem. Some frameworks, like ASP.NET, have a high-level exception handler that captures all errors to that the app never crashes; in that case, logging the exception might be the only way you can know that it occurs. + ]]> @@ -230,16 +230,16 @@ Initializes a new instance of the class, setting the property of the new instance to a system-supplied message that describes the error, such as "The value 'null' was found where an instance of an object was required." This message takes into account the current system culture. - . - -|Property|Value| -|--------------|-----------| -||`null`.| -||The localized error message string.| - + . + +|Property|Value| +|--------------|-----------| +||`null`.| +||The localized error message string.| + ]]> @@ -287,16 +287,16 @@ A that describes the error. The content of is intended to be understood by humans. The caller of this constructor is required to ensure that this string has been localized for the current system culture. Initializes a new instance of the class with a specified error message. - . - -|Property|Value| -|--------------|-----------| -||`null`.| -||The error message string.| - + . + +|Property|Value| +|--------------|-----------| +||`null`.| +||The error message string.| + ]]> @@ -351,19 +351,19 @@ - - + + The object that holds the serialized object data. The contextual information about the source or destination. Initializes a new instance of the class with serialized data. - XML and SOAP Serialization @@ -414,18 +414,18 @@ The exception that is the cause of the current exception. If the parameter is not , the current exception is raised in a block that handles the inner exception. Initializes a new instance of the class with a specified error message and a reference to the inner exception that is the cause of this exception. - property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||The inner exception reference.| -||The error message string.| - + property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||The inner exception reference.| +||The error message string.| + ]]> diff --git a/xml/System/ObjectDisposedException.xml b/xml/System/ObjectDisposedException.xml index 18e4f18e647..9e36a553f63 100644 --- a/xml/System/ObjectDisposedException.xml +++ b/xml/System/ObjectDisposedException.xml @@ -66,40 +66,40 @@ The exception that is thrown when an operation is performed on a disposed object. - is thrown when you try to access a member of an object that implements the interface or interface, and that object has been disposed. Typically, this exception is caused by one of the following conditions: - -- You've called an `IDisposable` object's `Dispose` method (or an `IDisposableAsync` object's `DisposeAsync` method), and you're trying to access an instance member that gets or sets the object's state. The following example illustrates the that is thrown when you try to reset the frequency of timer notifications after you call the method. - + is thrown when you try to access a member of an object that implements the interface or interface, and that object has been disposed. Typically, this exception is caused by one of the following conditions: + +- You've called an `IDisposable` object's `Dispose` method (or an `IDisposableAsync` object's `DisposeAsync` method), and you're trying to access an instance member that gets or sets the object's state. The following example illustrates the that is thrown when you try to reset the frequency of timer notifications after you call the method. + :::code language="csharp" source="~/snippets/csharp/System/ObjectDisposedException/Overview/dispose1.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System/ObjectDisposedException/Overview/dispose1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.objectdisposedexception/vb/dispose1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.objectdisposedexception/vb/dispose1.vb" id="Snippet1"::: + - You've called an object's `Close` method, and you're trying to access an instance member that gets or sets the object's state. Often, the `Close` method provides a type's public implementation of the method. The same is true for `CloseAsync` and ``. - -- You've called an object's `Dispose` or `DisposeAsync` methods multiple times. Typically, this doesn't throw an exception. However, depending on how a type implements or , it may not allow multiple calls to that method. - In most cases, this exception results from developer error. Instead of handling the error in a `try`/`catch` block, you should correct the error, typically by reinstantiating the object. - - - -## Examples - The following example demonstrates an error that causes the `ObjectDisposedException` exception to be thrown. - +- You've called an object's `Dispose` or `DisposeAsync` methods multiple times. Typically, this doesn't throw an exception. However, depending on how a type implements or , it may not allow multiple calls to that method. + + In most cases, this exception results from developer error. Instead of handling the error in a `try`/`catch` block, you should correct the error, typically by reinstantiating the object. + + + +## Examples + The following example demonstrates an error that causes the `ObjectDisposedException` exception to be thrown. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/ObjDispEx/CPP/objdispexc.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System/ObjectDisposedException/Overview/objdispexc.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System/ObjectDisposedException/Overview/objdispexc.fs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ObjDispEx/VB/objdispexc.vb" id="Snippet1"::: - This code produces the following output: - -``` -Caught: - Cannot access a closed Stream. -``` - + This code produces the following output: + +``` +Caught: + Cannot access a closed Stream. +``` + ]]> @@ -167,15 +167,15 @@ Caught: A string containing the name of the disposed object. Initializes a new instance of the class with a string containing the name of the disposed object. - property is initialized to a system-supplied message that describes the error and includes the `objectName` parameter. This message takes into account the current system culture. - - The `InnerException` property of the new instance is initialized to `null`. - - If `objectName` is `null`, the `Message` property contains only an error message. - + property is initialized to a system-supplied message that describes the error and includes the `objectName` parameter. This message takes into account the current system culture. + + The `InnerException` property of the new instance is initialized to `null`. + + If `objectName` is `null`, the `Message` property contains only an error message. + ]]> @@ -226,8 +226,8 @@ Caught: - - + + The that holds the serialized object data about the exception being thrown. @@ -286,11 +286,11 @@ Caught: The exception that is the cause of the current exception. If is not , the current exception is raised in a block that handles the inner exception. Initializes a new instance of the class with a specified error message and a reference to the inner exception that is the cause of this exception. - property. The property returns the same value that is passed into the constructor. - + property. The property returns the same value that is passed into the constructor. + ]]> @@ -346,13 +346,13 @@ Caught: The error message that explains the reason for the exception. Initializes a new instance of the class with the specified object name and message. - @@ -406,8 +406,8 @@ Caught: System.Void - - + + The that holds the serialized object data about the exception being thrown. @@ -464,13 +464,13 @@ Caught: Gets the message that describes the error. A string that describes the error. - property is not `null`, the message includes the name of the object. - - This property overrides . - + property is not `null`, the message includes the name of the object. + + This property overrides . + ]]> @@ -517,11 +517,11 @@ Caught: Gets the name of the disposed object. A string containing the name of the disposed object. - , the value of this property is included in the string returned by the property. - + , the value of this property is included in the string returned by the property. + ]]> diff --git a/xml/System/OperationCanceledException.xml b/xml/System/OperationCanceledException.xml index 15f04d65f67..d2c6bb36bb4 100644 --- a/xml/System/OperationCanceledException.xml +++ b/xml/System/OperationCanceledException.xml @@ -77,11 +77,11 @@ The exception that is thrown in a thread upon cancellation of an operation that the thread was executing. - property, and the property of the token is set to `true`. - + property, and the property of the token is set to `true`. + ]]> @@ -137,19 +137,19 @@ Initializes a new instance of the class with a system-supplied error message. - property of the new instance to a system-supplied message that describes the error, such as "The operation was canceled." This message takes into account the current system culture. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||A nullreference (`Nothing` in Visual Basic).| -||The localized error message string.| -||A cancellation token created in the non-canceled state.| - + property of the new instance to a system-supplied message that describes the error, such as "The operation was canceled." This message takes into account the current system culture. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||A nullreference (`Nothing` in Visual Basic).| +||The localized error message string.| +||A cancellation token created in the non-canceled state.| + ]]> @@ -199,19 +199,19 @@ A that describes the error. Initializes a new instance of the class with a specified error message. - . - -|Property|Value| -|--------------|-----------| -||A null reference (`Nothing` in Visual Basic).| -||The error message string.| -||A cancellation token created in the non-canceled state.| - + . + +|Property|Value| +|--------------|-----------| +||A null reference (`Nothing` in Visual Basic).| +||The error message string.| +||A cancellation token created in the non-canceled state.| + ]]> @@ -259,19 +259,19 @@ A cancellation token associated with the operation that was canceled. Initializes a new instance of the class with a cancellation token. - property of the new instance to a system-supplied message that describes the error, such as "The operation was canceled." This message takes into account the current system culture. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||A nullreference (`Nothing` in Visual Basic).| -||The localized error message string.| -||`token`.| - + property of the new instance to a system-supplied message that describes the error, such as "The operation was canceled." This message takes into account the current system culture. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||A nullreference (`Nothing` in Visual Basic).| +||The localized error message string.| +||`token`.| + ]]> @@ -326,19 +326,19 @@ - - + + The object that holds the serialized object data. The contextual information about the source or destination. Initializes a new instance of the class with serialized data. - XML and SOAP Serialization @@ -389,21 +389,21 @@ The exception that is the cause of the current exception. If the parameter is not , the current exception is raised in a block that handles the inner exception. Initializes a new instance of the class with a specified error message and a reference to the inner exception that is the cause of this exception. - property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. - - The following table shows the initial property values for an instance of . - -|Property Type|Condition| -|-------------------|---------------| -||`innerException`.| -||`message`.| -||A cancellation token created in the non-canceled state.| - + property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. + + The following table shows the initial property values for an instance of . + +|Property Type|Condition| +|-------------------|---------------| +||`innerException`.| +||`message`.| +||A cancellation token created in the non-canceled state.| + ]]> @@ -454,19 +454,19 @@ A cancellation token associated with the operation that was canceled. Initializes a new instance of the class with a specified error message and a cancellation token. - . - -|Property|Value| -|--------------|-----------| -||A null reference (`Nothing` in Visual Basic).| -||`message`.| -||`token`.| - + . + +|Property|Value| +|--------------|-----------| +||A null reference (`Nothing` in Visual Basic).| +||`message`.| +||`token`.| + ]]> @@ -519,21 +519,21 @@ A cancellation token associated with the operation that was canceled. Initializes a new instance of the class with a specified error message, a reference to the inner exception that is the cause of this exception, and a cancellation token. - property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. - - The following table shows the initial property values for an instance of . - -|Property Type|Condition| -|-------------------|---------------| -||`innerException`.| -||`message`.| -||`token`.| - + property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. + + The following table shows the initial property values for an instance of . + +|Property Type|Condition| +|-------------------|---------------| +||`innerException`.| +||`message`.| +||`token`.| + ]]> @@ -581,11 +581,11 @@ Gets a token associated with the operation that was canceled. A token associated with the operation that was canceled, or a default token. - property of the token returns `true`. - + property of the token returns `true`. + ]]> diff --git a/xml/System/OutOfMemoryException.xml b/xml/System/OutOfMemoryException.xml index f19445aefb7..9b9200d99ac 100644 --- a/xml/System/OutOfMemoryException.xml +++ b/xml/System/OutOfMemoryException.xml @@ -72,106 +72,106 @@ The exception that is thrown when there is not enough memory to continue the execution of a program. - uses the HRESULT `COR_E_OUTOFMEMORY`, which has the value 0x8007000E. - -For a list of initial property values for an instance of , see the constructors. - + uses the HRESULT `COR_E_OUTOFMEMORY`, which has the value 0x8007000E. + +For a list of initial property values for an instance of , see the constructors. + > [!NOTE] -> The value of the inherited property is always `null`. - -An exception has two major causes: - -- You are attempting to expand a object beyond the length defined by its property. - -- The common language runtime cannot allocate enough contiguous memory to successfully perform an operation. This exception can be thrown by any property assignment or method call that requires a memory allocation. For more information on the cause of the exception, see the blog post ["Out of Memory" Does Not Refer to Physical Memory](https://docs.microsoft.com/archive/blogs/ericlippert/out-of-memory-does-not-refer-to-physical-memory). - - This type of exception represents a catastrophic failure. If you choose to handle the exception, you should include a `catch` block that calls the method to terminate your app and add an entry to the system event log, as the following example does. - +> The value of the inherited property is always `null`. + +An exception has two major causes: + +- You are attempting to expand a object beyond the length defined by its property. + +- The common language runtime cannot allocate enough contiguous memory to successfully perform an operation. This exception can be thrown by any property assignment or method call that requires a memory allocation. For more information on the cause of the exception, see the blog post ["Out of Memory" Does Not Refer to Physical Memory](https://docs.microsoft.com/archive/blogs/ericlippert/out-of-memory-does-not-refer-to-physical-memory). + + This type of exception represents a catastrophic failure. If you choose to handle the exception, you should include a `catch` block that calls the method to terminate your app and add an entry to the system event log, as the following example does. + :::code language="csharp" source="~/snippets/csharp/System/OutOfMemoryException/Overview/failfast1.cs" id="Snippet2"::: :::code language="fsharp" source="~/snippets/fsharp/System/OutOfMemoryException/Overview/failfast1.fs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.outofmemoryexception/vb/failfast1.vb" id="Snippet2"::: - - Some of the conditions under which the exception is thrown and the actions you can take to eliminate it include the following: - -**You are calling the method.** - -You are attempting to increase the length of a object beyond the size specified by its property. The following example illustrates the exception thrown by a call to the method when the example tries to insert a string that would cause the object's property to exceed its maximum capacity. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.outofmemoryexception/vb/failfast1.vb" id="Snippet2"::: + + Some of the conditions under which the exception is thrown and the actions you can take to eliminate it include the following: + +**You are calling the method.** + +You are attempting to increase the length of a object beyond the size specified by its property. The following example illustrates the exception thrown by a call to the method when the example tries to insert a string that would cause the object's property to exceed its maximum capacity. + :::code language="csharp" source="~/snippets/csharp/System/OutOfMemoryException/Overview/sb_example1.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System/OutOfMemoryException/Overview/sb_example1.fs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.outofmemoryexception/vb/sb_example1.vb" id="Snippet1"::: -You can do either of the following to address the error: - -- Replace the call to the constructor with a call any other constructor overload. The maximum capacity of your object will be set to its default value, which is . +You can do either of the following to address the error: + +- Replace the call to the constructor with a call any other constructor overload. The maximum capacity of your object will be set to its default value, which is . + +- Call the constructor with a `maxCapacity` value that is large enough to accommodate any expansions to the object. -- Call the constructor with a `maxCapacity` value that is large enough to accommodate any expansions to the object. - **Your app runs as a 32-bit process.** -32-bit processes can allocate a maximum of 2GB of virtual user-mode memory on 32-bit systems, and 4GB of virtual user-mode memory on 64-bit systems. This can make it more difficult for the common language runtime to allocate sufficient contiguous memory when a large allocation is needed. In contrast, 64-bit processes can allocate up to 8TB of virtual memory. To address this exception, recompile your app to target a 64-bit platform. For information on targeting specific platforms in Visual Studio, see [How to: Configure Projects to Target Platforms](/visualstudio/ide/how-to-configure-projects-to-target-platforms). - -**Your app is leaking unmanaged resources** +32-bit processes can allocate a maximum of 2GB of virtual user-mode memory on 32-bit systems, and 4GB of virtual user-mode memory on 64-bit systems. This can make it more difficult for the common language runtime to allocate sufficient contiguous memory when a large allocation is needed. In contrast, 64-bit processes can allocate up to 8TB of virtual memory. To address this exception, recompile your app to target a 64-bit platform. For information on targeting specific platforms in Visual Studio, see [How to: Configure Projects to Target Platforms](/visualstudio/ide/how-to-configure-projects-to-target-platforms). + +**Your app is leaking unmanaged resources** + +Although the garbage collector is able to free memory allocated to managed types, it does not manage memory allocated to unmanaged resources such as operating system handles (including handles to files, memory-mapped files, pipes, registry keys, and wait handles) and memory blocks allocated directly by Windows API calls or by calls to memory allocation functions such as `malloc`. Types that consume unmanaged resources implement the interface. -Although the garbage collector is able to free memory allocated to managed types, it does not manage memory allocated to unmanaged resources such as operating system handles (including handles to files, memory-mapped files, pipes, registry keys, and wait handles) and memory blocks allocated directly by Windows API calls or by calls to memory allocation functions such as `malloc`. Types that consume unmanaged resources implement the interface. +If you are consuming a type that uses unmanaged resources, you should be sure to call its method when you have finished using it. (Some types also implement a `Close` method that is identical in function to a `Dispose` method.) For more information, see the [Using Objects That Implement IDisposable](/dotnet/standard/garbage-collection/using-objects) topic. -If you are consuming a type that uses unmanaged resources, you should be sure to call its method when you have finished using it. (Some types also implement a `Close` method that is identical in function to a `Dispose` method.) For more information, see the [Using Objects That Implement IDisposable](/dotnet/standard/garbage-collection/using-objects) topic. +If you have created a type that uses unmanaged resources, make sure that you have implemented the Dispose pattern and, if necessary, supplied a finalizer. For more information, see [Implementing a Dispose method](/dotnet/standard/garbage-collection/implementing-dispose) and . -If you have created a type that uses unmanaged resources, make sure that you have implemented the Dispose pattern and, if necessary, supplied a finalizer. For more information, see [Implementing a Dispose method](/dotnet/standard/garbage-collection/implementing-dispose) and . - **You are attempting to create a large array in a 64-bit process** -By default, the common language runtime in .NET Framework does not allow single objects whose size exceeds 2GB. To override this default, you can use the [\](/dotnet/framework/configure-apps/file-schema/runtime/gcallowverylargeobjects-element) configuration file setting to enable arrays whose total size exceeds 2 GB. On .NET Core, support for arrays of greater than 2 GB is enabled by default. - +By default, the common language runtime in .NET Framework does not allow single objects whose size exceeds 2GB. To override this default, you can use the [\](/dotnet/framework/configure-apps/file-schema/runtime/gcallowverylargeobjects-element) configuration file setting to enable arrays whose total size exceeds 2 GB. On .NET Core, support for arrays of greater than 2 GB is enabled by default. + **You are working with very large sets of data (such as arrays, collections, or database data sets) in memory.** -When data structures or data sets that reside in memory become so large that the common language runtime is unable to allocate enough contiguous memory for them, an exception results. +When data structures or data sets that reside in memory become so large that the common language runtime is unable to allocate enough contiguous memory for them, an exception results. + +To prevent the exceptions, you must modify your application so that less data is resident in memory, or the data is divided into segments that require smaller memory allocations. For example: -To prevent the exceptions, you must modify your application so that less data is resident in memory, or the data is divided into segments that require smaller memory allocations. For example: +- If you are retrieving all of the data from a database and then filtering it in your app to minimize trips to the server, you should modify your queries to return only the subset of data that your app needs. When working with large tables, multiple queries are almost always more efficient than retrieving all of the data in a single table and then manipulating it. -- If you are retrieving all of the data from a database and then filtering it in your app to minimize trips to the server, you should modify your queries to return only the subset of data that your app needs. When working with large tables, multiple queries are almost always more efficient than retrieving all of the data in a single table and then manipulating it. +- If you are executing queries that users create dynamically, you should ensure that the number of records returned by the query is limited. -- If you are executing queries that users create dynamically, you should ensure that the number of records returned by the query is limited. +- If you are using large arrays or other collection objects whose size results in an exception, you should modify your application to work the data in subsets rather than to work with it all at once. -- If you are using large arrays or other collection objects whose size results in an exception, you should modify your application to work the data in subsets rather than to work with it all at once. - -The following example gets a array that consists of 200 million floating-point values and then calculates their mean. The output from the example shows that, because the example stores the entire array in memory before it calculates the mean, an is thrown. +The following example gets a array that consists of 200 million floating-point values and then calculates their mean. The output from the example shows that, because the example stores the entire array in memory before it calculates the mean, an is thrown. :::code language="csharp" source="~/snippets/csharp/System/OutOfMemoryException/Overview/data1.cs" id="Snippet3"::: :::code language="fsharp" source="~/snippets/fsharp/System/OutOfMemoryException/Overview/data1.fs" id="Snippet3"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.outofmemoryexception/vb/data1.vb" id="Snippet3"::: - -The following example eliminates the exception by processing the incoming data without storing the entire data set in memory, serializing the data to a file if necessary to permit further processing (these lines are commented out in the example, since in this case they produce a file whose size is greater than 1GB), and returning the calculated mean and the number of cases to the calling routine. +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.outofmemoryexception/vb/data1.vb" id="Snippet3"::: + +The following example eliminates the exception by processing the incoming data without storing the entire data set in memory, serializing the data to a file if necessary to permit further processing (these lines are commented out in the example, since in this case they produce a file whose size is greater than 1GB), and returning the calculated mean and the number of cases to the calling routine. :::code language="csharp" source="~/snippets/csharp/System/OutOfMemoryException/Overview/data2.cs" id="Snippet4"::: :::code language="fsharp" source="~/snippets/fsharp/System/OutOfMemoryException/Overview/data2.fs" id="Snippet4"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.outofmemoryexception/vb/data2.vb" id="Snippet4"::: - -**You are repeatedly concatenating large strings.** +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.outofmemoryexception/vb/data2.vb" id="Snippet4"::: + +**You are repeatedly concatenating large strings.** + +Because strings are immutable, each string concatenation operation creates a new string. The impact for small strings, or for a small number of concatenation operations, is negligible. But for large strings or a very large number of concatenation operations, string concatenation can lead to a large number of memory allocations and memory fragmentation, poor performance, and possibly exceptions. -Because strings are immutable, each string concatenation operation creates a new string. The impact for small strings, or for a small number of concatenation operations, is negligible. But for large strings or a very large number of concatenation operations, string concatenation can lead to a large number of memory allocations and memory fragmentation, poor performance, and possibly exceptions. +When concatenating large strings or performing a large number of concatenation operations, you should use the class instead of the class. When you have finished manipulating the string, convert the instance to a string by calling the method. -When concatenating large strings or performing a large number of concatenation operations, you should use the class instead of the class. When you have finished manipulating the string, convert the instance to a string by calling the method. - -**You pin a large number of objects in memory.** - -Pinning a large number of objects in memory for long periods can make it difficult for the garbage collector to allocate contiguous blocks of memory. If you've pinned a large number of objects in memory, for example by using the `fixed` statement in C# or by calling the method with a handle type of , you can do the following to address the exception. - -- Evaluate whether each object really needs to be pinned, +**You pin a large number of objects in memory.** -- Ensure that each object is unpinned as soon as possible. +Pinning a large number of objects in memory for long periods can make it difficult for the garbage collector to allocate contiguous blocks of memory. If you've pinned a large number of objects in memory, for example by using the `fixed` statement in C# or by calling the method with a handle type of , you can do the following to address the exception. -- Make sure that each call to the method to pin memory has a corresponding call to the method to unpin that memory. +- Evaluate whether each object really needs to be pinned, -The following Microsoft intermediate (MSIL) instructions throw an exception: - -- [box](xref:System.Reflection.Emit.OpCodes.Box) -- [newarr](xref:System.Reflection.Emit.OpCodes.Newarr) -- [newobj](xref:System.Reflection.Emit.OpCodes.Newobj) +- Ensure that each object is unpinned as soon as possible. + +- Make sure that each call to the method to pin memory has a corresponding call to the method to unpin that memory. + +The following Microsoft intermediate (MSIL) instructions throw an exception: + +- [box](xref:System.Reflection.Emit.OpCodes.Box) +- [newarr](xref:System.Reflection.Emit.OpCodes.Newarr) +- [newobj](xref:System.Reflection.Emit.OpCodes.Newobj) ]]> @@ -231,18 +231,18 @@ The following Microsoft intermediate (MSIL) instructions throw an Initializes a new instance of the class. - property of the new instance to a system-supplied message that describes the error, such as "There was not enough memory to continue the execution of the program." This message takes into account the current system culture. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||`null`.| -||The localized error message string.| - + property of the new instance to a system-supplied message that describes the error, such as "There was not enough memory to continue the execution of the program." This message takes into account the current system culture. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||`null`.| +||The localized error message string.| + ]]> @@ -290,18 +290,18 @@ The following Microsoft intermediate (MSIL) instructions throw an The message that describes the error. Initializes a new instance of the class with a specified error message. - . - -|Property|Value| -|--------------|-----------| -||A null reference (`Nothing` in Visual Basic).| -||The error message string.| - + . + +|Property|Value| +|--------------|-----------| +||A null reference (`Nothing` in Visual Basic).| +||The error message string.| + ]]> @@ -356,19 +356,19 @@ The following Microsoft intermediate (MSIL) instructions throw an - - + + The object that holds the serialized object data. The contextual information about the source or destination. Initializes a new instance of the class with serialized data. - XML and SOAP Serialization @@ -419,18 +419,18 @@ The following Microsoft intermediate (MSIL) instructions throw an The exception that is the cause of the current exception. If the parameter is not a null reference ( in Visual Basic), the current exception is raised in a block that handles the inner exception. Initializes a new instance of the class with a specified error message and a reference to the inner exception that is the cause of this exception. - property. The property returns the same value that is passed into the constructor, or a null reference (`Nothing` in Visual Basic) if the property does not supply the inner exception value to the constructor. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||The inner exception reference.| -||The error message string.| - + property. The property returns the same value that is passed into the constructor, or a null reference (`Nothing` in Visual Basic) if the property does not supply the inner exception value to the constructor. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||The inner exception reference.| +||The error message string.| + ]]> diff --git a/xml/System/OverflowException.xml b/xml/System/OverflowException.xml index 012e2d42e64..392bfbde7be 100644 --- a/xml/System/OverflowException.xml +++ b/xml/System/OverflowException.xml @@ -66,48 +66,48 @@ The exception that is thrown when an arithmetic, casting, or conversion operation in a checked context results in an overflow. - is thrown at run time under the following conditions: - -- An arithmetic operation produces a result that is outside the range of the data type returned by the operation. The following example illustrates the that is thrown by a multiplication operation that overflows the bounds of the type. - + is thrown at run time under the following conditions: + +- An arithmetic operation produces a result that is outside the range of the data type returned by the operation. The following example illustrates the that is thrown by a multiplication operation that overflows the bounds of the type. + :::code language="csharp" source="~/snippets/csharp/System/OverflowException/Overview/arithmetic1.cs" interactive="try-dotnet-method" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System/OverflowException/Overview/arithmetic1.fs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.overflowexception/vb/arithmetic1.vb" id="Snippet1"::: -- A casting or conversion operation attempts to perform a narrowing conversion, and the value of the source data type is outside the range of the target data type. The following example illustrates the that is thrown by the attempt to convert a large unsigned byte value to a signed byte value. - +- A casting or conversion operation attempts to perform a narrowing conversion, and the value of the source data type is outside the range of the target data type. The following example illustrates the that is thrown by the attempt to convert a large unsigned byte value to a signed byte value. + :::code language="csharp" source="~/snippets/csharp/System/OverflowException/Overview/arithmetic1.cs" interactive="try-dotnet-method" id="Snippet2"::: :::code language="fsharp" source="~/snippets/fsharp/System/OverflowException/Overview/arithmetic1.fs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.overflowexception/vb/arithmetic1.vb" id="Snippet2"::: - In each case, the result of the operation is a value that is less than the `MinValue` property or greater than the `MaxValue` property of the data type that results from the operation. - - For the arithmetic, casting, or conversion operation to throw an , the operation must occur in a checked context. By default, arithmetic operations and overflows in Visual Basic are checked; in C# and F#, they are not. If the operation occurs in an unchecked context, the result is truncated by discarding any high-order bits that do not fit into the destination type. The following example illustrates such an unchecked conversion in C# or F#. It repeats the previous example in an unchecked context. - - :::code language="csharp" source="~/snippets/csharp/System/OverflowException/Overview/arithmetic1.cs" interactive="try-dotnet-method" id="Snippet3"::: - :::code language="fsharp" source="~/snippets/fsharp/System/OverflowException/Overview/arithmetic1.fs" id="Snippet3"::: - - The following Microsoft intermediate language (MSIL) instructions throw an : - -- `add.ovf.` *\* - -- `conv.ovf.` *\* - -- `conv.ovf.` *\* `.un` - -- `mul.ovf.` *\* - -- `sub.ovf.` *\* - -- `newarr` - - uses the HRESULT COR_E_OVERFLOW, which has the value 0x80131516. - - For a list of initial property values for an instance of , see the constructors. - + In each case, the result of the operation is a value that is less than the `MinValue` property or greater than the `MaxValue` property of the data type that results from the operation. + + For the arithmetic, casting, or conversion operation to throw an , the operation must occur in a checked context. By default, arithmetic operations and overflows in Visual Basic are checked; in C# and F#, they are not. If the operation occurs in an unchecked context, the result is truncated by discarding any high-order bits that do not fit into the destination type. The following example illustrates such an unchecked conversion in C# or F#. It repeats the previous example in an unchecked context. + + :::code language="csharp" source="~/snippets/csharp/System/OverflowException/Overview/arithmetic1.cs" interactive="try-dotnet-method" id="Snippet3"::: + :::code language="fsharp" source="~/snippets/fsharp/System/OverflowException/Overview/arithmetic1.fs" id="Snippet3"::: + + The following Microsoft intermediate language (MSIL) instructions throw an : + +- `add.ovf.` *\* + +- `conv.ovf.` *\* + +- `conv.ovf.` *\* `.un` + +- `mul.ovf.` *\* + +- `sub.ovf.` *\* + +- `newarr` + + uses the HRESULT COR_E_OVERFLOW, which has the value 0x80131516. + + For a list of initial property values for an instance of , see the constructors. + ]]> @@ -165,16 +165,16 @@ Initializes a new instance of the class. - . - -|Property|Value| -|--------------|-----------| -||A null reference (`Nothing` in Visual Basic).| -||The localized error message string.| - + . + +|Property|Value| +|--------------|-----------| +||A null reference (`Nothing` in Visual Basic).| +||The localized error message string.| + ]]> @@ -222,18 +222,18 @@ The message that describes the error. Initializes a new instance of the class with a specified error message. - . - -|Property|Value| -|--------------|-----------| -||A null reference (`Nothing` in Visual Basic).| -||The error message string.| - + . + +|Property|Value| +|--------------|-----------| +||A null reference (`Nothing` in Visual Basic).| +||The error message string.| + ]]> @@ -288,19 +288,19 @@ - - + + The object that holds the serialized object data. The contextual information about the source or destination. Initializes a new instance of the class with serialized data. - @@ -350,18 +350,18 @@ The exception that is the cause of the current exception. If the parameter is not a null reference ( in Visual Basic), the current exception is raised in a block that handles the inner exception. Initializes a new instance of the class with a specified error message and a reference to the inner exception that is the cause of this exception. - property. The property returns the same value that is passed into the constructor, or a null reference (`Nothing` in Visual Basic) if the property does not supply the inner exception value to the constructor. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||The inner exception reference.| -||The error message string.| - + property. The property returns the same value that is passed into the constructor, or a null reference (`Nothing` in Visual Basic) if the property does not supply the inner exception value to the constructor. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||The inner exception reference.| +||The error message string.| + ]]> diff --git a/xml/System/PlatformNotSupportedException.xml b/xml/System/PlatformNotSupportedException.xml index 523f5c3e3fe..bbd007be49f 100644 --- a/xml/System/PlatformNotSupportedException.xml +++ b/xml/System/PlatformNotSupportedException.xml @@ -66,11 +66,11 @@ The exception that is thrown when a feature does not run on a particular platform. - @@ -128,16 +128,16 @@ Initializes a new instance of the class with default properties. - class is created by a call to this constructor, the following properties are initialized to the specified values: - -|Property|Value| -|--------------|-----------| -||`null`.| -||The empty string.| - + class is created by a call to this constructor, the following properties are initialized to the specified values: + +|Property|Value| +|--------------|-----------| +||`null`.| +||The empty string.| + ]]> @@ -185,16 +185,16 @@ The text message that explains the reason for the exception. Initializes a new instance of the class with a specified error message. - class is created by a call to this constructor, the following properties are initialized to the specified values: - -|Property|Value| -|--------------|-----------| -||`null`.| -||The error message string.| - + class is created by a call to this constructor, the following properties are initialized to the specified values: + +|Property|Value| +|--------------|-----------| +||`null`.| +||The error message string.| + ]]> @@ -249,8 +249,8 @@ - - + + The that holds the serialized object data about the exception being thrown. @@ -304,18 +304,18 @@ The exception that is the cause of the current exception. If the parameter is not , the current exception is raised in a block that handles the inner exception. Initializes a new instance of the class with a specified error message and a reference to the inner exception that is the cause of this exception. - property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||The inner exception reference.| -||The error message string.| - + property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||The inner exception reference.| +||The error message string.| + ]]> diff --git a/xml/System/RankException.xml b/xml/System/RankException.xml index ad5c3e7990a..d6738d2adb4 100644 --- a/xml/System/RankException.xml +++ b/xml/System/RankException.xml @@ -72,13 +72,13 @@ The exception that is thrown when an array with the wrong number of dimensions is passed to a method. - uses the HRESULT COR_E_RANK, that has the value 0x80131517. - - For a list of initial property values for an instance of , see the constructors. - + uses the HRESULT COR_E_RANK, that has the value 0x80131517. + + For a list of initial property values for an instance of , see the constructors. + ]]> @@ -136,18 +136,18 @@ Initializes a new instance of the class. - property of the new instance to a system-supplied message that describes the error, such as "The two arrays must have the same number of dimensions." This message takes into account the current system culture. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||A null reference (`Nothing` in Visual Basic).| -||The localized error message string.| - + property of the new instance to a system-supplied message that describes the error, such as "The two arrays must have the same number of dimensions." This message takes into account the current system culture. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||A null reference (`Nothing` in Visual Basic).| +||The localized error message string.| + ]]> @@ -195,18 +195,18 @@ A that describes the error. Initializes a new instance of the class with a specified error message. - . - -|Property|Value| -|--------------|-----------| -||A null reference (`Nothing` in Visual Basic).| -||The error message string.| - + . + +|Property|Value| +|--------------|-----------| +||A null reference (`Nothing` in Visual Basic).| +||The error message string.| + ]]> @@ -261,19 +261,19 @@ - - + + The object that holds the serialized object data. The contextual information about the source or destination. Initializes a new instance of the class with serialized data. - XML and SOAP Serialization @@ -324,18 +324,18 @@ The exception that is the cause of the current exception. If the parameter is not a null reference ( in Visual Basic), the current exception is raised in a block that handles the inner exception. Initializes a new instance of the class with a specified error message and a reference to the inner exception that is the cause of this exception. - property. The property returns the same value that is passed into the constructor, or a null reference (`Nothing` in Visual Basic) if the property does not supply the inner exception value to the constructor. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||The inner exception reference.| -||The error message string.| - + property. The property returns the same value that is passed into the constructor, or a null reference (`Nothing` in Visual Basic) if the property does not supply the inner exception value to the constructor. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||The inner exception reference.| +||The error message string.| + ]]> diff --git a/xml/System/RuntimeFieldHandle.xml b/xml/System/RuntimeFieldHandle.xml index fc7d148068d..b16e30b599b 100644 --- a/xml/System/RuntimeFieldHandle.xml +++ b/xml/System/RuntimeFieldHandle.xml @@ -74,11 +74,11 @@ Represents a field using an internal metadata token. - structure is a handle to the field represented by the instance. - + structure is a handle to the field represented by the instance. + ]]> @@ -362,21 +362,21 @@ System.Void - - + + The object to populate with serialization information. (Reserved) The place to store and retrieve serialized data. Populates a with the data necessary to deserialize the field represented by the current instance. - method. - + method. + ]]> diff --git a/xml/System/RuntimeMethodHandle.xml b/xml/System/RuntimeMethodHandle.xml index ee64f16ce3c..071c36ce28a 100644 --- a/xml/System/RuntimeMethodHandle.xml +++ b/xml/System/RuntimeMethodHandle.xml @@ -296,12 +296,12 @@ Obtains a pointer to the method represented by this instance. A pointer to the method represented by this instance. - attribute, then the returned value is an unmanaged function pointer with the same calling convention as specified in the attribute. If the method this handle represents is static, then the returned value can be cast to a C# managed function pointer type with the same signature. For instance method handles, the value is not easily usable from user code and is meant exclusively for usage within the runtime. - - For methods that don't have the , use to get a function pointer that can be passed to native code. + + For methods that don't have the , use to get a function pointer that can be passed to native code. ]]> The caller does not have the necessary permission to perform this operation. @@ -413,21 +413,21 @@ System.Void - - + + The object to populate with serialization information. (Reserved) The place to store and retrieve serialized data. Populates a with the data necessary to deserialize the field represented by this instance. - method. - + method. + ]]> diff --git a/xml/System/RuntimeTypeHandle.xml b/xml/System/RuntimeTypeHandle.xml index 9c3603bc235..fb52a83259f 100644 --- a/xml/System/RuntimeTypeHandle.xml +++ b/xml/System/RuntimeTypeHandle.xml @@ -82,16 +82,16 @@ Represents a type using an internal metadata token. - from a type or from an object, and how to turn the handle back into a type. - + from a type or from an object, and how to turn the handle back into a type. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Type_GetTypeHandle/CPP/Type_GetTypeHandle.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System/RuntimeTypeHandle/Overview/type_gettypehandle.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System/RuntimeTypeHandle/Overview/type_gettypehandle.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Type_GetTypeHandle/VB/type_gettypehandle.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Type_GetTypeHandle/VB/type_gettypehandle.vb" id="Snippet1"::: + ]]> @@ -406,21 +406,21 @@ System.Void - - + + The object to be populated with serialization information. (Reserved) The location where serialized data will be stored and retrieved. Populates a with the data necessary to deserialize the type represented by the current instance. - method. - + method. + ]]> @@ -491,11 +491,11 @@ if is a structure and is equal to ; otherwise, . - causes an ambiguous overload resolution error when compiled. Use the method instead. - + causes an ambiguous overload resolution error when compiled. Use the method instead. + The equivalent method for this operator is .]]> @@ -549,11 +549,11 @@ if is a and is equal to ; otherwise, . - causes an ambiguous overload resolution error when compiled. Use the method instead. - + causes an ambiguous overload resolution error when compiled. Use the method instead. + The equivalent method for this operator is >.]]> @@ -620,11 +620,11 @@ if is a and is not equal to ; otherwise, . - causes an ambiguous overload resolution error when compiled. Use the method instead. - + causes an ambiguous overload resolution error when compiled. Use the method instead. + The equivalent method for this operator is .]]> @@ -678,11 +678,11 @@ if is a structure and is not equal to ; otherwise, . - causes an ambiguous overload resolution error when compiled. Use the method instead. - + causes an ambiguous overload resolution error when compiled. Use the method instead. + The equivalent method for this operator is .]]> diff --git a/xml/System/SByte.xml b/xml/System/SByte.xml index 917b0d303ca..f4a2a9159c6 100644 --- a/xml/System/SByte.xml +++ b/xml/System/SByte.xml @@ -413,7 +413,7 @@ System.Int32 - + An object to compare, or . diff --git a/xml/System/Single.xml b/xml/System/Single.xml index f679b9df717..5a10a8c2eca 100644 --- a/xml/System/Single.xml +++ b/xml/System/Single.xml @@ -1067,7 +1067,7 @@ This computes `arctan(x) / π` in the interval `[-0.5, +0.5]`. System.Int32 - + An object to compare, or . diff --git a/xml/System/String.xml b/xml/System/String.xml index a7176b148bf..5b2d3d5c67f 100644 --- a/xml/System/String.xml +++ b/xml/System/String.xml @@ -206,13 +206,13 @@ A pointer to a null-terminated array of Unicode characters. Initializes a new instance of the class to the value indicated by a specified pointer to an array of Unicode characters. - [!NOTE] -> For examples and comprehensive usage information about this and other `String` constructor overloads, see the constructor summary. - + [!NOTE] +> For examples and comprehensive usage information about this and other `String` constructor overloads, see the constructor summary. + ]]> The current process does not have read access to all the addressed characters. @@ -273,13 +273,13 @@ An array of Unicode characters. Initializes a new instance of the class to the Unicode characters indicated in the specified character array. - [!NOTE] -> For examples and comprehensive usage information about this and other `String` constructor overloads, see the constructor summary. - + [!NOTE] +> For examples and comprehensive usage information about this and other `String` constructor overloads, see the constructor summary. + ]]> @@ -369,19 +369,19 @@ - + A pointer to a null-terminated array of 8-bit signed integers. The integers are interpreted using the current system code page encoding (that is, the encoding specified by ). Initializes a new instance of the class to the value indicated by a pointer to an array of 8-bit signed integers. - [!NOTE] -> For examples and comprehensive usage information about this and other `String` constructor overloads, see the constructor summary. - + [!NOTE] +> For examples and comprehensive usage information about this and other `String` constructor overloads, see the constructor summary. + ]]> @@ -442,13 +442,13 @@ The number of times occurs. Initializes a new instance of the class to the value indicated by a specified Unicode character repeated a specified number of times. - [!NOTE] -> For examples and comprehensive usage information about this and other `String` constructor overloads, see the constructor summary. - + [!NOTE] +> For examples and comprehensive usage information about this and other `String` constructor overloads, see the constructor summary. + ]]> @@ -514,13 +514,13 @@ The number of characters within to use. Initializes a new instance of the class to the value indicated by a specified pointer to an array of Unicode characters, a starting character position within that array, and a length. - [!NOTE] -> For examples and comprehensive usage information about this and other `String` constructor overloads, see the constructor summary. - + [!NOTE] +> For examples and comprehensive usage information about this and other `String` constructor overloads, see the constructor summary. + ]]> @@ -581,22 +581,22 @@ The number of characters within to use. Initializes a new instance of the class to the value indicated by an array of Unicode characters, a starting character position within that array, and a length. - [!NOTE] -> For examples and comprehensive usage information about this and other `String` constructor overloads, see the constructor summary. - + [!NOTE] +> For examples and comprehensive usage information about this and other `String` constructor overloads, see the constructor summary. + ]]> is . - or is less than zero. - --or- - + or is less than zero. + +-or- + The sum of and is greater than the number of elements in . @@ -645,9 +645,9 @@ The sum of and is grea - - - + + + A pointer to an array of 8-bit signed integers. The integers are interpreted using the current system code page encoding (that is, the encoding specified by ). @@ -655,31 +655,31 @@ The sum of and is grea The number of characters within to use. Initializes a new instance of the class to the value indicated by a specified pointer to an array of 8-bit signed integers, a starting position within that array, and a length. - [!NOTE] -> For examples and comprehensive usage information about this and other `String` constructor overloads, see the constructor summary. - + [!NOTE] +> For examples and comprehensive usage information about this and other `String` constructor overloads, see the constructor summary. + ]]> is . - or is less than zero. - --or- - -The address specified by + is too large for the current platform; that is, the address calculation overflowed. - --or- - + or is less than zero. + +-or- + +The address specified by + is too large for the current platform; that is, the address calculation overflowed. + +-or- + The length of the new string to initialize is too large to allocate. - The address specified by + is less than 64K. - --or- - + The address specified by + is less than 64K. + +-or- + A new instance of could not be initialized using , assuming is encoded in ANSI. , , and collectively specify an invalid address. @@ -730,10 +730,10 @@ A new instance of could not be initialized using - - - - + + + + [System.Runtime.CompilerServices.Nullable(1)] @@ -749,31 +749,31 @@ A new instance of could not be initialized using An object that specifies how the array referenced by is encoded. If is , ANSI encoding is assumed. Initializes a new instance of the class to the value indicated by a specified pointer to an array of 8-bit signed integers, a starting position within that array, a length, and an object. - [!NOTE] -> For examples and comprehensive usage information about this and other `String` constructor overloads, see the constructor summary. - + [!NOTE] +> For examples and comprehensive usage information about this and other `String` constructor overloads, see the constructor summary. + ]]> is . - or is less than zero. - --or- - -The address specified by + is too large for the current platform; that is, the address calculation overflowed. - --or- - + or is less than zero. + +-or- + +The address specified by + is too large for the current platform; that is, the address calculation overflowed. + +-or- + The length of the new string to initialize is too large to allocate. - The address specified by + is less than 64K. - --or- - + The address specified by + is less than 64K. + +-or- + A new instance of could not be initialized using , assuming is encoded as specified by . , , and collectively specify an invalid address. @@ -831,27 +831,27 @@ A new instance of could not be initialized using Gets the object at a specified position in the current object. The object at position . - object at the position specified by the `index` parameter. However, a Unicode character might be represented by more than one . Use the class to work with Unicode characters instead of objects. For more information, see the "Char Objects and Unicode Characters" section in the class overview. - -In C#, the property is an indexer. In Visual Basic, it is the default property of the class. Each object in the string can be accessed by using code such as the following. - -:::code language="csharp" source="~/snippets/csharp/System/String/Chars/chars1.cs" interactive="try-dotnet-method" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Chars/chars1.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.chars/vb/chars1.vb" id="Snippet1"::: - -## Examples -The following example demonstrates how you can use this indexer in a routine to validate a string. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Uri_IsHexDigit/CPP/uri_ishexdigit.cpp" id="Snippet1"::: -:::code language="csharp" source="~/snippets/csharp/System/String/Chars/uri_ishexdigit.cs" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Chars/uri_ishexdigit.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Uri_IsHexDigit/VB/uri_ishexdigit.vb" id="Snippet1"::: - + object at the position specified by the `index` parameter. However, a Unicode character might be represented by more than one . Use the class to work with Unicode characters instead of objects. For more information, see the "Char Objects and Unicode Characters" section in the class overview. + +In C#, the property is an indexer. In Visual Basic, it is the default property of the class. Each object in the string can be accessed by using code such as the following. + +:::code language="csharp" source="~/snippets/csharp/System/String/Chars/chars1.cs" interactive="try-dotnet-method" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Chars/chars1.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.chars/vb/chars1.vb" id="Snippet1"::: + +## Examples +The following example demonstrates how you can use this indexer in a routine to validate a string. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Uri_IsHexDigit/CPP/uri_ishexdigit.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Chars/uri_ishexdigit.cs" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Chars/uri_ishexdigit.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Uri_IsHexDigit/VB/uri_ishexdigit.vb" id="Snippet1"::: + ]]> @@ -903,13 +903,13 @@ The following example demonstrates how you can use this indexer in a routine to Returns a reference to this instance of . This instance of . - or method to create a separate object with the same value as this instance. - -Because the method simply returns the existing string instance, there is little reason to call it directly. - + or method to create a separate object with the same value as this instance. + +Because the method simply returns the existing string instance, there is little reason to call it directly. + ]]> @@ -927,20 +927,20 @@ Because the method simply returns the existing str Compares two specified objects and returns an integer that indicates their relative position in the sort order. - method return a 32-bit signed integer indicating the lexical relationship between the two comparands. - -|Value|Condition| -|-----------|---------------| -|Less than zero|The first substring precedes the second substring in the sort order.| -|Zero|The substrings occur in the same position in the sort order, or `length` is zero.| -|Greater than zero|The first substring follows the second substring in the sort order.| - -> [!WARNING] -> Whenever possible, you should call an overload of the method that includes a parameter. For more information, see [Best Practices for Using Strings](/dotnet/standard/base-types/best-practices-strings). - + method return a 32-bit signed integer indicating the lexical relationship between the two comparands. + +|Value|Condition| +|-----------|---------------| +|Less than zero|The first substring precedes the second substring in the sort order.| +|Zero|The substrings occur in the same position in the sort order, or `length` is zero.| +|Greater than zero|The first substring follows the second substring in the sort order.| + +> [!WARNING] +> Whenever possible, you should call an overload of the method that includes a parameter. For more information, see [Best Practices for Using Strings](/dotnet/standard/base-types/best-practices-strings). + ]]> Best Practices for Using Strings in .NET @@ -1003,78 +1003,78 @@ All overloads of the method return a 32-bit sign The first string to compare. The second string to compare. Compares two specified objects and returns an integer that indicates their relative position in the sort order. - A 32-bit signed integer that indicates the lexical relationship between the two comparands. - - Value - - Condition - - Less than zero - - precedes in the sort order. - - Zero - - occurs in the same position as in the sort order. - - Greater than zero - - follows in the sort order. - + A 32-bit signed integer that indicates the lexical relationship between the two comparands. + + Value + + Condition + + Less than zero + + precedes in the sort order. + + Zero + + occurs in the same position as in the sort order. + + Greater than zero + + follows in the sort order. + - . - -> [!WARNING] -> When comparing strings, you should call the method, which requires that you explicitly specify the type of string comparison that the method uses. For more information, see [Best Practices for Using Strings](/dotnet/standard/base-types/best-practices-strings). - -One or both comparands can be `null`. By definition, any string, including the empty string (""), compares greater than a null reference; and two null references compare equal to each other. - -The comparison terminates when an inequality is discovered or both strings have been compared. However, if the two strings compare equal to the end of one string, and the other string has characters remaining, then the string with remaining characters is considered greater. The return value is the result of the last comparison performed. - -Unexpected results can occur when comparisons are affected by culture-specific casing rules. For example, in Turkish, the following example yields the wrong results because the file system in Turkish does not use linguistic casing rules for the letter "i" in "file". - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Compare/cpp/remarks.cpp" id="Snippet10"::: -:::code language="csharp" source="~/snippets/csharp/System/String/Compare/remarks.cs" id="Snippet10"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/remarks.fs" id="Snippet10"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare/vb/remarks.vb" id="Snippet10"::: - -Compare the path name to "file" using an ordinal comparison. The correct code to do this is as follows: - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Compare/cpp/remarks.cpp" id="Snippet11"::: -:::code language="csharp" source="~/snippets/csharp/System/String/Compare/remarks.cs" id="Snippet11"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/remarks.fs" id="Snippet11"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare/vb/remarks.vb" id="Snippet11"::: - -## Examples -The following example calls the method to compare three sets of strings. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Compare/cpp/compare02.cpp" id="Snippet18"::: -:::code language="csharp" source="~/snippets/csharp/System/String/Compare/compare02.cs" interactive="try-dotnet-method" id="Snippet18"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/compare02.fs" id="Snippet18"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare/vb/compare02.vb" id="Snippet18"::: - -In the following example, the `ReverseStringComparer` class demonstrates how you can evaluate two strings with the method. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/ArrayList/CPP/ArrayListSample.cpp" id="Snippet7"::: -:::code language="csharp" source="~/snippets/csharp/System/String/Compare/ArrayListSample.cs" interactive="try-dotnet" id="Snippet7"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/ArrayListSample.fs" id="Snippet7"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ArrayList/VB/ArrayListSample.vb" id="Snippet7"::: - + . + +> [!WARNING] +> When comparing strings, you should call the method, which requires that you explicitly specify the type of string comparison that the method uses. For more information, see [Best Practices for Using Strings](/dotnet/standard/base-types/best-practices-strings). + +One or both comparands can be `null`. By definition, any string, including the empty string (""), compares greater than a null reference; and two null references compare equal to each other. + +The comparison terminates when an inequality is discovered or both strings have been compared. However, if the two strings compare equal to the end of one string, and the other string has characters remaining, then the string with remaining characters is considered greater. The return value is the result of the last comparison performed. + +Unexpected results can occur when comparisons are affected by culture-specific casing rules. For example, in Turkish, the following example yields the wrong results because the file system in Turkish does not use linguistic casing rules for the letter "i" in "file". + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Compare/cpp/remarks.cpp" id="Snippet10"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Compare/remarks.cs" id="Snippet10"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/remarks.fs" id="Snippet10"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare/vb/remarks.vb" id="Snippet10"::: + +Compare the path name to "file" using an ordinal comparison. The correct code to do this is as follows: + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Compare/cpp/remarks.cpp" id="Snippet11"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Compare/remarks.cs" id="Snippet11"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/remarks.fs" id="Snippet11"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare/vb/remarks.vb" id="Snippet11"::: + +## Examples +The following example calls the method to compare three sets of strings. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Compare/cpp/compare02.cpp" id="Snippet18"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Compare/compare02.cs" interactive="try-dotnet-method" id="Snippet18"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/compare02.fs" id="Snippet18"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare/vb/compare02.vb" id="Snippet18"::: + +In the following example, the `ReverseStringComparer` class demonstrates how you can evaluate two strings with the method. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/ArrayList/CPP/ArrayListSample.cpp" id="Snippet7"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Compare/ArrayListSample.cs" interactive="try-dotnet" id="Snippet7"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/ArrayListSample.fs" id="Snippet7"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ArrayList/VB/ArrayListSample.vb" id="Snippet7"::: + ]]> - Character sets include ignorable characters. The method does not consider such characters when it performs a culture-sensitive comparison. For example, if the following code is run on the .NET Framework 4 or later, a culture-sensitive comparison of "animal" with "ani-mal" (using a soft hyphen, or U+00AD) indicates that the two strings are equivalent. - -:::code language="csharp" source="~/snippets/csharp/System/String/Compare/compare21.cs" id="Snippet21"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/compare21.fs" id="Snippet21"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare/vb/compare21.vb" id="Snippet21"::: - + Character sets include ignorable characters. The method does not consider such characters when it performs a culture-sensitive comparison. For example, if the following code is run on the .NET Framework 4 or later, a culture-sensitive comparison of "animal" with "ani-mal" (using a soft hyphen, or U+00AD) indicates that the two strings are equivalent. + +:::code language="csharp" source="~/snippets/csharp/System/String/Compare/compare21.cs" id="Snippet21"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/compare21.fs" id="Snippet21"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare/vb/compare21.vb" id="Snippet21"::: + To recognize ignorable characters in a string comparison, call the method and supply a value of either or for the `comparisonType` parameter. @@ -1140,71 +1140,71 @@ To recognize ignorable characters in a string comparison, call the to ignore case during the comparison; otherwise, . Compares two specified objects, ignoring or honoring their case, and returns an integer that indicates their relative position in the sort order. - A 32-bit signed integer that indicates the lexical relationship between the two comparands. - - Value - - Condition - - Less than zero - - precedes in the sort order. - - Zero - - occurs in the same position as in the sort order. - - Greater than zero - - follows in the sort order. - + A 32-bit signed integer that indicates the lexical relationship between the two comparands. + + Value + + Condition + + Less than zero + + precedes in the sort order. + + Zero + + occurs in the same position as in the sort order. + + Greater than zero + + follows in the sort order. + - . - -> [!WARNING] -> When comparing strings, you should call the method, which requires that you explicitly specify the type of string comparison that the method uses. For more information, see [Best Practices for Using Strings](/dotnet/standard/base-types/best-practices-strings). - -One or both comparands can be `null`. By definition, any string, including the empty string (""), compares greater than a null reference; and two null references compare equal to each other. - -The comparison terminates when an inequality is discovered or both strings have been compared. However, if the two strings compare equal to the end of one string, and the other string has characters remaining, then the string with remaining characters is considered greater. The return value is the result of the last comparison performed. - -Unexpected results can occur when comparisons are affected by culture-specific casing rules. For example, in Turkish, the following example yields the wrong results because the file system in Turkish does not use linguistic casing rules for the letter "i" in "file". - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Compare/cpp/remarks.cpp" id="Snippet12"::: -:::code language="csharp" source="~/snippets/csharp/System/String/Compare/remarks.cs" id="Snippet12"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/remarks.fs" id="Snippet12"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare/vb/remarks.vb" id="Snippet12"::: - -Compare the path name to "file" using an ordinal comparison. The correct code to do this is as follows: - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Compare/cpp/remarks.cpp" id="Snippet13"::: -:::code language="csharp" source="~/snippets/csharp/System/String/Compare/remarks.cs" id="Snippet13"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/remarks.fs" id="Snippet13"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare/vb/remarks.vb" id="Snippet13"::: - -## Examples -The following example demonstrates that the method is equivalent to using or when comparing strings. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Compare/cpp/compare02.cpp" id="Snippet18"::: -:::code language="csharp" source="~/snippets/csharp/System/String/Compare/compare02.cs" interactive="try-dotnet-method" id="Snippet18"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/compare02.fs" id="Snippet18"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare/vb/compare02.vb" id="Snippet18"::: - + . + +> [!WARNING] +> When comparing strings, you should call the method, which requires that you explicitly specify the type of string comparison that the method uses. For more information, see [Best Practices for Using Strings](/dotnet/standard/base-types/best-practices-strings). + +One or both comparands can be `null`. By definition, any string, including the empty string (""), compares greater than a null reference; and two null references compare equal to each other. + +The comparison terminates when an inequality is discovered or both strings have been compared. However, if the two strings compare equal to the end of one string, and the other string has characters remaining, then the string with remaining characters is considered greater. The return value is the result of the last comparison performed. + +Unexpected results can occur when comparisons are affected by culture-specific casing rules. For example, in Turkish, the following example yields the wrong results because the file system in Turkish does not use linguistic casing rules for the letter "i" in "file". + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Compare/cpp/remarks.cpp" id="Snippet12"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Compare/remarks.cs" id="Snippet12"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/remarks.fs" id="Snippet12"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare/vb/remarks.vb" id="Snippet12"::: + +Compare the path name to "file" using an ordinal comparison. The correct code to do this is as follows: + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Compare/cpp/remarks.cpp" id="Snippet13"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Compare/remarks.cs" id="Snippet13"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/remarks.fs" id="Snippet13"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare/vb/remarks.vb" id="Snippet13"::: + +## Examples +The following example demonstrates that the method is equivalent to using or when comparing strings. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Compare/cpp/compare02.cpp" id="Snippet18"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Compare/compare02.cs" interactive="try-dotnet-method" id="Snippet18"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/compare02.fs" id="Snippet18"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare/vb/compare02.vb" id="Snippet18"::: + ]]> - Character sets include ignorable characters. The method does not consider such characters when it performs a culture-sensitive comparison. For example, if the following code is run on the .NET Framework 4 or later, a culture-sensitive, case-insensitive comparison of "animal" with "Ani-mal" (using a soft hyphen, or U+00AD) indicates that the two strings are equivalent. - -:::code language="csharp" source="~/snippets/csharp/System/String/Compare/compare22.cs" id="Snippet22"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/compare22.fs" id="Snippet22"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare/vb/compare22.vb" id="Snippet22"::: - + Character sets include ignorable characters. The method does not consider such characters when it performs a culture-sensitive comparison. For example, if the following code is run on the .NET Framework 4 or later, a culture-sensitive, case-insensitive comparison of "animal" with "Ani-mal" (using a soft hyphen, or U+00AD) indicates that the two strings are equivalent. + +:::code language="csharp" source="~/snippets/csharp/System/String/Compare/compare22.cs" id="Snippet22"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/compare22.fs" id="Snippet22"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare/vb/compare22.vb" id="Snippet22"::: + To recognize ignorable characters in a string comparison, call the method and supply a value of either or for the parameter. @@ -1271,57 +1271,57 @@ To recognize ignorable characters in a string comparison, call the The second string to compare. One of the enumeration values that specifies the rules to use in the comparison. Compares two specified objects using the specified rules, and returns an integer that indicates their relative position in the sort order. - A 32-bit signed integer that indicates the lexical relationship between the two comparands. - - Value - - Condition - - Less than zero - - precedes in the sort order. - - Zero - - is in the same position as in the sort order. - - Greater than zero - - follows in the sort order. - + A 32-bit signed integer that indicates the lexical relationship between the two comparands. + + Value + + Condition + + Less than zero + + precedes in the sort order. + + Zero + + is in the same position as in the sort order. + + Greater than zero + + follows in the sort order. + - @@ -1383,10 +1383,10 @@ The following example compares three versions of the letter "I". The results are System.Int32 - - - - + + + + The first string to compare. @@ -1395,68 +1395,68 @@ The following example compares three versions of the letter "I". The results are to ignore case during the comparison; otherwise, . An object that supplies culture-specific comparison information. If is , the current culture is used. Compares two specified objects, ignoring or honoring their case, and using culture-specific information to influence the comparison, and returns an integer that indicates their relative position in the sort order. - A 32-bit signed integer that indicates the lexical relationship between the two comparands. - - Value - - Condition - - Less than zero - - precedes in the sort order. - - Zero - - occurs in the same position as in the sort order. - - Greater than zero - - follows in the sort order. - + A 32-bit signed integer that indicates the lexical relationship between the two comparands. + + Value + + Condition + + Less than zero + + precedes in the sort order. + + Zero + + occurs in the same position as in the sort order. + + Greater than zero + + follows in the sort order. + - . - -One or both comparands can be `null`. By definition, any string, including the empty string (""), compares greater than a null reference; and two null references compare equal to each other. - -The comparison terminates when an inequality is discovered or both strings have been compared. However, if the two strings compare equal to the end of one string, and the other string has characters remaining, then the string with remaining characters is considered greater. The return value is the result of the last comparison performed. - -Unexpected results can occur when comparisons are affected by culture-specific casing rules. For example, in Turkish, the following example yields the wrong results because the file system in Turkish does not use linguistic casing rules for the letter "i" in "file". - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Compare/cpp/remarks.cpp" id="Snippet14"::: -:::code language="csharp" source="~/snippets/csharp/System/String/Compare/remarks.cs" id="Snippet14"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/remarks.fs" id="Snippet14"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare/vb/remarks.vb" id="Snippet14"::: - -Compare the path name to "file" using an ordinal comparison. The correct code to do this is as follows: - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Compare/cpp/remarks.cpp" id="Snippet15"::: -:::code language="csharp" source="~/snippets/csharp/System/String/Compare/remarks.cs" id="Snippet15"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/remarks.fs" id="Snippet15"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare/vb/remarks.vb" id="Snippet15"::: - -## Examples -The following example demonstrates how culture can affect a comparison. In Czech - Czech Republic culture, "ch" is a single character that is greater than "d". However, in English - United States culture, "ch" consists of two characters, and "c" is less than "d". - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.comp4/CPP/string.comp4.cpp" id="Snippet1"::: -:::code language="csharp" source="~/snippets/csharp/System/String/Compare/string.comp4.cs" interactive="try-dotnet" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/string.comp4.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.comp4/VB/string.comp4.vb" id="Snippet1"::: - + . + +One or both comparands can be `null`. By definition, any string, including the empty string (""), compares greater than a null reference; and two null references compare equal to each other. + +The comparison terminates when an inequality is discovered or both strings have been compared. However, if the two strings compare equal to the end of one string, and the other string has characters remaining, then the string with remaining characters is considered greater. The return value is the result of the last comparison performed. + +Unexpected results can occur when comparisons are affected by culture-specific casing rules. For example, in Turkish, the following example yields the wrong results because the file system in Turkish does not use linguistic casing rules for the letter "i" in "file". + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Compare/cpp/remarks.cpp" id="Snippet14"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Compare/remarks.cs" id="Snippet14"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/remarks.fs" id="Snippet14"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare/vb/remarks.vb" id="Snippet14"::: + +Compare the path name to "file" using an ordinal comparison. The correct code to do this is as follows: + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Compare/cpp/remarks.cpp" id="Snippet15"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Compare/remarks.cs" id="Snippet15"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/remarks.fs" id="Snippet15"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare/vb/remarks.vb" id="Snippet15"::: + +## Examples +The following example demonstrates how culture can affect a comparison. In Czech - Czech Republic culture, "ch" is a single character that is greater than "d". However, in English - United States culture, "ch" consists of two characters, and "c" is less than "d". + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.comp4/CPP/string.comp4.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Compare/string.comp4.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/string.comp4.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.comp4/VB/string.comp4.vb" id="Snippet1"::: + ]]> - Character sets include ignorable characters. The method does not consider such characters when it performs a culture-sensitive comparison. For example, if the following code is run on the .NET Framework 4 or later, a case-insensitive comparison of "animal" with "Ani-mal" (using a soft hyphen, or U+00AD) using the invariant culture indicates that the two strings are equivalent. - -:::code language="csharp" source="~/snippets/csharp/System/String/Compare/compare23.cs" id="Snippet23"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/compare23.fs" id="Snippet23"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare/vb/compare23.vb" id="Snippet23"::: - + Character sets include ignorable characters. The method does not consider such characters when it performs a culture-sensitive comparison. For example, if the following code is run on the .NET Framework 4 or later, a case-insensitive comparison of "animal" with "Ani-mal" (using a soft hyphen, or U+00AD) using the invariant culture indicates that the two strings are equivalent. + +:::code language="csharp" source="~/snippets/csharp/System/String/Compare/compare23.cs" id="Snippet23"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/compare23.fs" id="Snippet23"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare/vb/compare23.vb" id="Snippet23"::: + To recognize ignorable characters in a string comparison, call the method and supply a value of either or for the parameter. @@ -1511,10 +1511,10 @@ To recognize ignorable characters in a string comparison, call the - - - + + + + The first string to compare. @@ -1522,48 +1522,48 @@ To recognize ignorable characters in a string comparison, call the The culture that supplies culture-specific comparison information. If is , the current culture is used. Options to use when performing the comparison (such as ignoring case or symbols). Compares two specified objects using the specified comparison options and culture-specific information to influence the comparison, and returns an integer that indicates the relationship of the two strings to each other in the sort order. - A 32-bit signed integer that indicates the lexical relationship between and , as shown in the following table - - Value - - Condition - - Less than zero - - precedes in the sort order. - - Zero - - occurs in the same position as in the sort order. - - Greater than zero - - follows in the sort order. - + A 32-bit signed integer that indicates the lexical relationship between and , as shown in the following table + + Value + + Condition + + Less than zero + + precedes in the sort order. + + Zero + + occurs in the same position as in the sort order. + + Greater than zero + + follows in the sort order. + - [!CAUTION] -> The method is designed primarily for use in sorting or alphabetizing operations. It should not be used when the primary purpose of the method call is to determine whether two strings are equivalent (that is, when the purpose of the method call is to test for a return value of zero). To determine whether two strings are equivalent, call the method. - -The comparison can be further specified by the `options` parameter, which consists of one or more members of the enumeration. However, because the purpose of this method is to conduct a culture-sensitive string comparison, the and values have no effect. - -Either or both comparands can be `null`. By definition, any string, including , compares greater than a null reference, and two null references compare equal to each other. - -The comparison terminates when an inequality is discovered or both strings have been compared. However, if the two strings compare equal to the end of one string, and the other string has characters remaining, the string with the remaining characters is considered greater. - -## Examples -The following example compares two strings in three different ways: Use linguistic comparison for the en-US culture; using linguistic case-sensitive comparison for the en-US culture; and using an ordinal comparison. It illustrates how the three methods of comparison produce three different results. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Compare/cpp/example.cpp" id="Snippet1"::: -:::code language="csharp" source="~/snippets/csharp/System/String/Compare/Example.cs" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/Example.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare/vb/Example.vb" id="Snippet1"::: - + [!CAUTION] +> The method is designed primarily for use in sorting or alphabetizing operations. It should not be used when the primary purpose of the method call is to determine whether two strings are equivalent (that is, when the purpose of the method call is to test for a return value of zero). To determine whether two strings are equivalent, call the method. + +The comparison can be further specified by the `options` parameter, which consists of one or more members of the enumeration. However, because the purpose of this method is to conduct a culture-sensitive string comparison, the and values have no effect. + +Either or both comparands can be `null`. By definition, any string, including , compares greater than a null reference, and two null references compare equal to each other. + +The comparison terminates when an inequality is discovered or both strings have been compared. However, if the two strings compare equal to the end of one string, and the other string has characters remaining, the string with the remaining characters is considered greater. + +## Examples +The following example compares two strings in three different ways: Use linguistic comparison for the en-US culture; using linguistic case-sensitive comparison for the en-US culture; and using an ordinal comparison. It illustrates how the three methods of comparison produce three different results. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Compare/cpp/example.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Compare/Example.cs" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/Example.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare/vb/Example.vb" id="Snippet1"::: + ]]> @@ -1635,81 +1635,81 @@ The following example compares two strings in three different ways: Use linguist The position of the substring within . The maximum number of characters in the substrings to compare. Compares substrings of two specified objects and returns an integer that indicates their relative position in the sort order. - A 32-bit signed integer indicating the lexical relationship between the two comparands. - - Value - - Condition - - Less than zero - - The substring in precedes the substring in in the sort order. - - Zero - - The substrings occur in the same position in the sort order, or is zero. - - Greater than zero - - The substring in follows the substring in in the sort order. - + A 32-bit signed integer indicating the lexical relationship between the two comparands. + + Value + + Condition + + Less than zero + + The substring in precedes the substring in in the sort order. + + Zero + + The substrings occur in the same position in the sort order, or is zero. + + Greater than zero + + The substring in follows the substring in in the sort order. + - . - -> [!WARNING] -> When comparing strings, you should call the method, which requires that you explicitly specify the type of string comparison that the method uses. For more information, see [Best Practices for Using Strings](/dotnet/standard/base-types/best-practices-strings). - -One or both comparands can be `null`. By definition, any string, including the empty string (""), compares greater than a null reference; and two null references compare equal to each other. - -The comparison terminates when an inequality is discovered or both substrings have been compared. However, if the two strings compare equal to the end of one string, and the other string has characters remaining, then the string with remaining characters is considered greater. The return value is the result of the last comparison performed. - -Unexpected results can occur when comparisons are affected by culture-specific casing rules. For example, in Turkish, the following example yields the wrong results because the file system in Turkish does not use linguistic casing rules for the letter "i" in "file". - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Compare/cpp/remarks.cpp" id="Snippet2"::: -:::code language="csharp" source="~/snippets/csharp/System/String/Compare/remarks.cs" id="Snippet2"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/remarks.fs" id="Snippet2"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare/vb/remarks.vb" id="Snippet2"::: - -Compare the path name to "file" using an ordinal comparison. The correct code to do this is as follows: - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Compare/cpp/remarks.cpp" id="Snippet3"::: -:::code language="csharp" source="~/snippets/csharp/System/String/Compare/remarks.cs" id="Snippet3"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/remarks.fs" id="Snippet3"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare/vb/remarks.vb" id="Snippet3"::: - -## Examples -The following example compares two substrings. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.compare3/CPP/comp3.cpp" id="Snippet1"::: -:::code language="csharp" source="~/snippets/csharp/System/String/Compare/comp3.cs" interactive="try-dotnet-method" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/comp3.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.compare3/VB/comp3.vb" id="Snippet1"::: - + . + +> [!WARNING] +> When comparing strings, you should call the method, which requires that you explicitly specify the type of string comparison that the method uses. For more information, see [Best Practices for Using Strings](/dotnet/standard/base-types/best-practices-strings). + +One or both comparands can be `null`. By definition, any string, including the empty string (""), compares greater than a null reference; and two null references compare equal to each other. + +The comparison terminates when an inequality is discovered or both substrings have been compared. However, if the two strings compare equal to the end of one string, and the other string has characters remaining, then the string with remaining characters is considered greater. The return value is the result of the last comparison performed. + +Unexpected results can occur when comparisons are affected by culture-specific casing rules. For example, in Turkish, the following example yields the wrong results because the file system in Turkish does not use linguistic casing rules for the letter "i" in "file". + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Compare/cpp/remarks.cpp" id="Snippet2"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Compare/remarks.cs" id="Snippet2"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/remarks.fs" id="Snippet2"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare/vb/remarks.vb" id="Snippet2"::: + +Compare the path name to "file" using an ordinal comparison. The correct code to do this is as follows: + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Compare/cpp/remarks.cpp" id="Snippet3"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Compare/remarks.cs" id="Snippet3"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/remarks.fs" id="Snippet3"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare/vb/remarks.vb" id="Snippet3"::: + +## Examples +The following example compares two substrings. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.compare3/CPP/comp3.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Compare/comp3.cs" interactive="try-dotnet-method" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/comp3.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.compare3/VB/comp3.vb" id="Snippet1"::: + ]]> - is greater than .. - --or- - - is greater than .. - --or- - -, , or is negative. - --or- - + is greater than .. + +-or- + + is greater than .. + +-or- + +, , or is negative. + +-or- + Either or is , and is greater than zero. Character sets include ignorable characters. The method does not consider these characters when it performs a linguistic or culture-sensitive comparison. To recognize ignorable characters in your comparison, call the method and supply a value of or for the parameter. @@ -1761,12 +1761,12 @@ Either or is System.Int32 - - - - - - + + + + + + The first string to use in the comparison. @@ -1777,81 +1777,81 @@ Either or is to ignore case during the comparison; otherwise, . Compares substrings of two specified objects, ignoring or honoring their case, and returns an integer that indicates their relative position in the sort order. - A 32-bit signed integer that indicates the lexical relationship between the two comparands. - - Value - - Condition - - Less than zero - - The substring in precedes the substring in in the sort order. - - Zero - - The substrings occur in the same position in the sort order, or is zero. - - Greater than zero - - The substring in follows the substring in in the sort order. - + A 32-bit signed integer that indicates the lexical relationship between the two comparands. + + Value + + Condition + + Less than zero + + The substring in precedes the substring in in the sort order. + + Zero + + The substrings occur in the same position in the sort order, or is zero. + + Greater than zero + + The substring in follows the substring in in the sort order. + - . - -> [!WARNING] -> When comparing strings, you should call the method, which requires that you explicitly specify the type of string comparison that the method uses. For more information, see [Best Practices for Using Strings](/dotnet/standard/base-types/best-practices-strings). - -One or both comparands can be `null`. By definition, any string, including the empty string (""), compares greater than a null reference; and two null references compare equal to each other. - -The comparison terminates when an inequality is discovered or both substrings have been compared. However, if the two strings compare equal to the end of one string, and the other string has characters remaining, then the string with remaining characters is considered greater. The return value is the result of the last comparison performed. - -Unexpected results can occur when comparisons are affected by culture-specific casing rules. For example, in Turkish, the following example yields the wrong results because the file system in Turkish does not use linguistic casing rules for the letter "i" in "file". - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Compare/cpp/remarks.cpp" id="Snippet4"::: -:::code language="csharp" source="~/snippets/csharp/System/String/Compare/remarks.cs" id="Snippet4"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/remarks.fs" id="Snippet4"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare/vb/remarks.vb" id="Snippet4"::: - -The path name needs to be compared in an invariant manner. The correct code to do this is as follows. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Compare/cpp/remarks.cpp" id="Snippet5"::: -:::code language="csharp" source="~/snippets/csharp/System/String/Compare/remarks.cs" id="Snippet5"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/remarks.fs" id="Snippet5"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare/vb/remarks.vb" id="Snippet5"::: - -## Examples -The following example performs two comparisons of two substrings that only differ in case. The first comparison ignores case and the second comparison considers case. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.compare4/CPP/comp4.cpp" id="Snippet1"::: -:::code language="csharp" source="~/snippets/csharp/System/String/Compare/comp4.cs" interactive="try-dotnet-method" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/comp4.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.compare4/VB/comp4.vb" id="Snippet1"::: - + . + +> [!WARNING] +> When comparing strings, you should call the method, which requires that you explicitly specify the type of string comparison that the method uses. For more information, see [Best Practices for Using Strings](/dotnet/standard/base-types/best-practices-strings). + +One or both comparands can be `null`. By definition, any string, including the empty string (""), compares greater than a null reference; and two null references compare equal to each other. + +The comparison terminates when an inequality is discovered or both substrings have been compared. However, if the two strings compare equal to the end of one string, and the other string has characters remaining, then the string with remaining characters is considered greater. The return value is the result of the last comparison performed. + +Unexpected results can occur when comparisons are affected by culture-specific casing rules. For example, in Turkish, the following example yields the wrong results because the file system in Turkish does not use linguistic casing rules for the letter "i" in "file". + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Compare/cpp/remarks.cpp" id="Snippet4"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Compare/remarks.cs" id="Snippet4"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/remarks.fs" id="Snippet4"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare/vb/remarks.vb" id="Snippet4"::: + +The path name needs to be compared in an invariant manner. The correct code to do this is as follows. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Compare/cpp/remarks.cpp" id="Snippet5"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Compare/remarks.cs" id="Snippet5"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/remarks.fs" id="Snippet5"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare/vb/remarks.vb" id="Snippet5"::: + +## Examples +The following example performs two comparisons of two substrings that only differ in case. The first comparison ignores case and the second comparison considers case. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.compare4/CPP/comp4.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Compare/comp4.cs" interactive="try-dotnet-method" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/comp4.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.compare4/VB/comp4.vb" id="Snippet1"::: + ]]> - is greater than .. - --or- - - is greater than .. - --or- - -, , or is negative. - --or- - + is greater than .. + +-or- + + is greater than .. + +-or- + +, , or is negative. + +-or- + Either or is , and is greater than zero. Character sets include ignorable characters. The method does not consider these characters when it performs a linguistic or culture-sensitive comparison. To recognize ignorable characters in your comparison, call the method and supply a value of or for the parameter. @@ -1925,76 +1925,76 @@ Either or is The maximum number of characters in the substrings to compare. One of the enumeration values that specifies the rules to use in the comparison. Compares substrings of two specified objects using the specified rules, and returns an integer that indicates their relative position in the sort order. - A 32-bit signed integer that indicates the lexical relationship between the two comparands. - - Value - - Condition - - Less than zero - - The substring in precedes the substring in in the sort order. - - Zero - - The substrings occur in the same position in the sort order, or the parameter is zero. - - Greater than zero - - The substring in follows the substring in in the sort order. - + A 32-bit signed integer that indicates the lexical relationship between the two comparands. + + Value + + Condition + + Less than zero + + The substring in precedes the substring in in the sort order. + + Zero + + The substrings occur in the same position in the sort order, or the parameter is zero. + + Greater than zero + + The substring in follows the substring in in the sort order. + - - is greater than .. - --or- - - is greater than .. - --or- - -, , or is negative. - --or- - + is greater than .. + +-or- + + is greater than .. + +-or- + +, , or is negative. + +-or- + Either or is , and is greater than zero. is not a value. @@ -2048,13 +2048,13 @@ Either or is System.Int32 - - - - - - - + + + + + + + The first string to use in the comparison. @@ -2066,78 +2066,78 @@ Either or is to ignore case during the comparison; otherwise, . An object that supplies culture-specific comparison information. If is , the current culture is used. Compares substrings of two specified objects, ignoring or honoring their case and using culture-specific information to influence the comparison, and returns an integer that indicates their relative position in the sort order. - An integer that indicates the lexical relationship between the two comparands. - - Value - - Condition - - Less than zero - - The substring in precedes the substring in in the sort order. - - Zero - - The substrings occur in the same position in the sort order, or is zero. - - Greater than zero - - The substring in follows the substring in in the sort order. - + An integer that indicates the lexical relationship between the two comparands. + + Value + + Condition + + Less than zero + + The substring in precedes the substring in in the sort order. + + Zero + + The substrings occur in the same position in the sort order, or is zero. + + Greater than zero + + The substring in follows the substring in in the sort order. + - . - -One or both comparands can be `null`. By definition, any string, including the empty string (""), compares greater than a null reference; and two null references compare equal to each other. - -The comparison terminates when an inequality is discovered or both substrings have been compared. However, if the two strings compare equal to the end of one string, and the other string has characters remaining, then the string with remaining characters is considered greater. The return value is the result of the last comparison performed. - -Unexpected results can occur when comparisons are affected by culture-specific casing rules. For example, in Turkish, the following example yields the wrong results because the file system in Turkish does not use linguistic casing rules for the letter "i" in "file". - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Compare/cpp/remarks.cpp" id="Snippet6"::: -:::code language="csharp" source="~/snippets/csharp/System/String/Compare/remarks.cs" id="Snippet6"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/remarks.fs" id="Snippet6"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare/vb/remarks.vb" id="Snippet6"::: - -Compare the path name to "file" using an ordinal comparison. The correct code to do this is as follows: - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Compare/cpp/remarks.cpp" id="Snippet7"::: -:::code language="csharp" source="~/snippets/csharp/System/String/Compare/remarks.cs" id="Snippet7"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/remarks.fs" id="Snippet7"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare/vb/remarks.vb" id="Snippet7"::: - -## Examples -The following example compares two substrings using different cultures and ignoring the case of the substrings. The choice of culture affects how the letter "I" is compared. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.compare5/CPP/comp5.cpp" id="Snippet1"::: -:::code language="csharp" source="~/snippets/csharp/System/String/Compare/comp5.cs" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/comp5.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.compare5/VB/comp5.vb" id="Snippet1"::: - + . + +One or both comparands can be `null`. By definition, any string, including the empty string (""), compares greater than a null reference; and two null references compare equal to each other. + +The comparison terminates when an inequality is discovered or both substrings have been compared. However, if the two strings compare equal to the end of one string, and the other string has characters remaining, then the string with remaining characters is considered greater. The return value is the result of the last comparison performed. + +Unexpected results can occur when comparisons are affected by culture-specific casing rules. For example, in Turkish, the following example yields the wrong results because the file system in Turkish does not use linguistic casing rules for the letter "i" in "file". + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Compare/cpp/remarks.cpp" id="Snippet6"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Compare/remarks.cs" id="Snippet6"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/remarks.fs" id="Snippet6"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare/vb/remarks.vb" id="Snippet6"::: + +Compare the path name to "file" using an ordinal comparison. The correct code to do this is as follows: + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Compare/cpp/remarks.cpp" id="Snippet7"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Compare/remarks.cs" id="Snippet7"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/remarks.fs" id="Snippet7"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare/vb/remarks.vb" id="Snippet7"::: + +## Examples +The following example compares two substrings using different cultures and ignoring the case of the substrings. The choice of culture affects how the letter "I" is compared. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.compare5/CPP/comp5.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Compare/comp5.cs" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/comp5.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.compare5/VB/comp5.vb" id="Snippet1"::: + ]]> - is greater than .. - --or- - - is greater than .. - --or- - -, , or is negative. - --or- - + is greater than .. + +-or- + + is greater than .. + +-or- + +, , or is negative. + +-or- + Either or is , and is greater than zero. Character sets include ignorable characters. The method does not consider these characters when it performs a linguistic or culture-sensitive comparison. To recognize ignorable characters in your comparison, call the method and supply a value of or for the parameter. @@ -2188,13 +2188,13 @@ Either or is - - - - - - + + + + + + + The first string to use in the comparison. @@ -2205,68 +2205,68 @@ Either or is An object that supplies culture-specific comparison information. If is , the current culture is used. Options to use when performing the comparison (such as ignoring case or symbols). Compares substrings of two specified objects using the specified comparison options and culture-specific information to influence the comparison, and returns an integer that indicates the relationship of the two substrings to each other in the sort order. - An integer that indicates the lexical relationship between the two substrings, as shown in the following table. - - Value - - Condition - - Less than zero - - The substring in precedes the substring in in the sort order. - - Zero - - The substrings occur in the same position in the sort order, or is zero. - - Greater than zero - - The substring in follows the substring in in the sort order. - + An integer that indicates the lexical relationship between the two substrings, as shown in the following table. + + Value + + Condition + + Less than zero + + The substring in precedes the substring in in the sort order. + + Zero + + The substrings occur in the same position in the sort order, or is zero. + + Greater than zero + + The substring in follows the substring in in the sort order. + - [!CAUTION] -> The method is designed primarily for use in sorting or alphabetizing operations. It should not be used when the primary purpose of the method call is to determine whether two substrings are equivalent (that is, when the purpose of the method call is to test for a return value of zero). To determine whether two strings are equivalent, call the method. - -One or both of `strA` and `strB` can be `null`. By definition, any string, including , compares greater than a null reference, and two null references compare equal to each other. - -The comparison can be further specified by the `options` parameter, which consists of one or more members of the enumeration. However, because the purpose of this method is to conduct a culture-sensitive string comparison, the and values have no effect. - -The comparison terminates when an inequality is discovered or both substrings have been compared. However, if the two strings compare equal to the end of one string, and the other string has characters remaining, the string with the remaining characters is considered greater. The return value is the result of the last comparison performed. - -## Examples -The following example uses the method to compare the last names of two people. It then lists them in alphabetical order. - -:::code language="csharp" source="~/snippets/csharp/System/String/Compare/Example1.cs" interactive="try-dotnet" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/Example1.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare5/vb/Example.vb" id="Snippet1"::: - + [!CAUTION] +> The method is designed primarily for use in sorting or alphabetizing operations. It should not be used when the primary purpose of the method call is to determine whether two substrings are equivalent (that is, when the purpose of the method call is to test for a return value of zero). To determine whether two strings are equivalent, call the method. + +One or both of `strA` and `strB` can be `null`. By definition, any string, including , compares greater than a null reference, and two null references compare equal to each other. + +The comparison can be further specified by the `options` parameter, which consists of one or more members of the enumeration. However, because the purpose of this method is to conduct a culture-sensitive string comparison, the and values have no effect. + +The comparison terminates when an inequality is discovered or both substrings have been compared. However, if the two strings compare equal to the end of one string, and the other string has characters remaining, the string with the remaining characters is considered greater. The return value is the result of the last comparison performed. + +## Examples +The following example uses the method to compare the last names of two people. It then lists them in alphabetical order. + +:::code language="csharp" source="~/snippets/csharp/System/String/Compare/Example1.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Compare/Example1.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare5/vb/Example.vb" id="Snippet1"::: + ]]> is not a value. - is greater than . - --or- - - is greater than . - --or- - -, , or is negative. - --or- - + is greater than . + +-or- + + is greater than . + +-or- + +, , or is negative. + +-or- + Either or is , and is greater than zero. Character sets include ignorable characters. The method does not consider these characters when it performs a linguistic or culture-sensitive comparison. To recognize ignorable characters in your comparison, supply a value of or for the parameter. @@ -2344,41 +2344,41 @@ Either or is The first string to compare. The second string to compare. Compares two specified objects by evaluating the numeric values of the corresponding objects in each string. - An integer that indicates the lexical relationship between the two comparands. - - Value - - Condition - - Less than zero - - is less than . - - Zero - - and are equal. - - Greater than zero - - is greater than . - + An integer that indicates the lexical relationship between the two comparands. + + Value + + Condition + + Less than zero + + is less than . + + Zero + + and are equal. + + Greater than zero + + is greater than . + - . To perform a case-insensitive comparison using ordinal sort rules, call the method with the `comparisonType` argument set to . - -Because is a static method, `strA` and `strB` can be `null`. If both values are `null`, the method returns 0 (zero), which indicates that `strA` and `strB` are equal. If only one of the values is `null`, the method considers the non-null value to be greater. - -## Examples -The following example performs and ordinal comparison of two strings that only differ in case. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.compareordinal/CPP/comp0.cpp" id="Snippet1"::: -:::code language="csharp" source="~/snippets/csharp/System/String/CompareOrdinal/comp0.cs" interactive="try-dotnet" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/CompareOrdinal/comp0.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.compareordinal/VB/comp0.vb" id="Snippet1"::: - + . To perform a case-insensitive comparison using ordinal sort rules, call the method with the `comparisonType` argument set to . + +Because is a static method, `strA` and `strB` can be `null`. If both values are `null`, the method returns 0 (zero), which indicates that `strA` and `strB` are equal. If only one of the values is `null`, the method considers the non-null value to be greater. + +## Examples +The following example performs and ordinal comparison of two strings that only differ in case. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.compareordinal/CPP/comp0.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/CompareOrdinal/comp0.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/CompareOrdinal/comp0.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.compareordinal/VB/comp0.vb" id="Snippet1"::: + ]]> @@ -2453,56 +2453,56 @@ The following example performs and ordinal comparison of two strings that only d The starting index of the substring in . The maximum number of characters in the substrings to compare. Compares substrings of two specified objects by evaluating the numeric values of the corresponding objects in each substring. - A 32-bit signed integer that indicates the lexical relationship between the two comparands. - - Value - - Condition - - Less than zero - - The substring in is less than the substring in . - - Zero - - The substrings are equal, or is zero. - - Greater than zero - - The substring in is greater than the substring in . - + A 32-bit signed integer that indicates the lexical relationship between the two comparands. + + Value + + Condition + + Less than zero + + The substring in is less than the substring in . + + Zero + + The substrings are equal, or is zero. + + Greater than zero + + The substring in is greater than the substring in . + - . To perform a case-insensitive comparison using ordinal sort rules, call the method with the `comparisonType` argument set to . - -Because is a static method, `strA` and `strB` can be `null`. If both values are `null`, the method returns 0 (zero), which indicates that `strA` and `strB` are equal. If only one of the values is `null`, the method considers the non-null value to be greater. - -## Examples -This following example demonstrates that and use different sort orders. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/StringCompareOrdinal/CPP/stringcompareordinal.cpp" id="Snippet1"::: -:::code language="csharp" source="~/snippets/csharp/System/String/CompareOrdinal/stringcompareordinal.cs" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/CompareOrdinal/stringcompareordinal.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/StringCompareOrdinal/VB/stringcompareordinal.vb" id="Snippet1"::: - + . To perform a case-insensitive comparison using ordinal sort rules, call the method with the `comparisonType` argument set to . + +Because is a static method, `strA` and `strB` can be `null`. If both values are `null`, the method returns 0 (zero), which indicates that `strA` and `strB` are equal. If only one of the values is `null`, the method considers the non-null value to be greater. + +## Examples +This following example demonstrates that and use different sort orders. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/StringCompareOrdinal/CPP/stringcompareordinal.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/CompareOrdinal/stringcompareordinal.cs" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/CompareOrdinal/stringcompareordinal.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/StringCompareOrdinal/VB/stringcompareordinal.vb" id="Snippet1"::: + ]]> - is not and is greater than .. - --or- - - is not and is greater than .. - --or- - + is not and is greater than .. + +-or- + + is not and is greater than .. + +-or- + , , or is negative. @@ -2518,11 +2518,11 @@ This following example demonstrates that Compares this instance with a specified object or and returns an integer that indicates whether this instance precedes, follows, or appears in the same position in the sort order as the specified object or . - method perform culture-sensitive and case-sensitive comparison. You cannot use this method to perform culture-insensitive or ordinal comparisons. For code clarity, we recommend that you avoid the method and call the method instead. - + method perform culture-sensitive and case-sensitive comparison. You cannot use this method to perform culture-insensitive or ordinal comparisons. For code clarity, we recommend that you avoid the method and call the method instead. + ]]> @@ -2576,66 +2576,66 @@ Both overloads of the method perform culture-s System.Int32 - + An object that evaluates to a . Compares this instance with a specified and indicates whether this instance precedes, follows, or appears in the same position in the sort order as the specified . - A 32-bit signed integer that indicates whether this instance precedes, follows, or appears in the same position in the sort order as the parameter. - - Value - - Condition - - Less than zero - - This instance precedes . - - Zero - - This instance has the same position in the sort order as . - - Greater than zero - - This instance follows . - --or- - - is . - + A 32-bit signed integer that indicates whether this instance precedes, follows, or appears in the same position in the sort order as the parameter. + + Value + + Condition + + Less than zero + + This instance precedes . + + Zero + + This instance has the same position in the sort order as . + + Greater than zero + + This instance follows . + +-or- + + is . + - object. - -> [!CAUTION] -> The method was designed primarily for use in sorting or alphabetizing operations. It should not be used when the primary purpose of the method call is to determine whether two strings are equivalent. To determine whether two strings are equivalent, call the method. - -This method performs a word (case-sensitive and culture-sensitive) comparison using the current culture. For more information about word, string, and ordinal sorts, see . - -For more information about the behavior of this method, see the Remarks section of the method. - -## Examples -The following example uses the method with an . Because it attempts to compare a instance to a `TestClass` object, the method throws an . - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/ExToString/CPP/extostring.cpp" id="Snippet1"::: -:::code language="csharp" source="~/snippets/csharp/System/String/CompareTo/extostring.cs" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/CompareTo/extostring.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ExToString/VB/extostring.vb" id="Snippet1"::: - + object. + +> [!CAUTION] +> The method was designed primarily for use in sorting or alphabetizing operations. It should not be used when the primary purpose of the method call is to determine whether two strings are equivalent. To determine whether two strings are equivalent, call the method. + +This method performs a word (case-sensitive and culture-sensitive) comparison using the current culture. For more information about word, string, and ordinal sorts, see . + +For more information about the behavior of this method, see the Remarks section of the method. + +## Examples +The following example uses the method with an . Because it attempts to compare a instance to a `TestClass` object, the method throws an . + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/ExToString/CPP/extostring.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/CompareTo/extostring.cs" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/CompareTo/extostring.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ExToString/VB/extostring.vb" id="Snippet1"::: + ]]> is not a . - Character sets include ignorable characters. The method does not consider such characters when it performs a culture-sensitive comparison. For example, if the following code is run on the .NET Framework 4 or later, a comparison of "animal" with "ani-mal" (using a soft hyphen, or U+00AD) indicates that the two strings are equivalent. - -:::code language="csharp" source="~/snippets/csharp/System/String/CompareTo/compareto1.cs" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/CompareTo/compareto1.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.compareto/vb/compareto1.vb" id="Snippet1"::: - + Character sets include ignorable characters. The method does not consider such characters when it performs a culture-sensitive comparison. For example, if the following code is run on the .NET Framework 4 or later, a comparison of "animal" with "ani-mal" (using a soft hyphen, or U+00AD) indicates that the two strings are equivalent. + +:::code language="csharp" source="~/snippets/csharp/System/String/CompareTo/compareto1.cs" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/CompareTo/compareto1.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.compareto/vb/compareto1.vb" id="Snippet1"::: + To recognize ignorable characters in a string comparison, call the method. @@ -2703,66 +2703,66 @@ To recognize ignorable characters in a string comparison, call the The string to compare with this instance. Compares this instance with a specified object and indicates whether this instance precedes, follows, or appears in the same position in the sort order as the specified string. - A 32-bit signed integer that indicates whether this instance precedes, follows, or appears in the same position in the sort order as the parameter. - - Value - - Condition - - Less than zero - - This instance precedes . - - Zero - - This instance has the same position in the sort order as . - - Greater than zero - - This instance follows . - --or- - - is . - + A 32-bit signed integer that indicates whether this instance precedes, follows, or appears in the same position in the sort order as the parameter. + + Value + + Condition + + Less than zero + + This instance precedes . + + Zero + + This instance has the same position in the sort order as . + + Greater than zero + + This instance follows . + +-or- + + is . + - . - -> [!CAUTION] -> The method was designed primarily for use in sorting or alphabetizing operations. It should not be used when the primary purpose of the method call is to determine whether two strings are equivalent. To determine whether two strings are equivalent, call the method. - -For more information about the behavior of this method, see the Remarks section of the method. - -This method implements the interface and performs slightly better than the method, because it does not have to determine whether the `strB` argument is a mutable value type that must be boxed, and it does not have to cast its parameter from an to a . - -## Examples -The following example uses the method to compare the current string instance with another string. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/StringCompareTo/CPP/stringcompareto.cpp" id="Snippet1"::: -:::code language="csharp" source="~/snippets/csharp/System/String/CompareTo/stringcompareto.cs" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/CompareTo/stringcompareto.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/StringCompareTo/VB/stringcompareto.vb" id="Snippet1"::: - -The following example demonstrates generic and non-generic versions of the CompareTo method for several value and reference types. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/T.CompareTo/CPP/cat.cpp" id="Snippet1"::: -:::code language="csharp" source="~/snippets/csharp/System/Boolean/CompareTo/cat.cs" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/Boolean/CompareTo/cat.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/T.CompareTo/VB/cat.vb" id="Snippet1"::: - + . + +> [!CAUTION] +> The method was designed primarily for use in sorting or alphabetizing operations. It should not be used when the primary purpose of the method call is to determine whether two strings are equivalent. To determine whether two strings are equivalent, call the method. + +For more information about the behavior of this method, see the Remarks section of the method. + +This method implements the interface and performs slightly better than the method, because it does not have to determine whether the `strB` argument is a mutable value type that must be boxed, and it does not have to cast its parameter from an to a . + +## Examples +The following example uses the method to compare the current string instance with another string. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/StringCompareTo/CPP/stringcompareto.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/CompareTo/stringcompareto.cs" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/CompareTo/stringcompareto.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/StringCompareTo/VB/stringcompareto.vb" id="Snippet1"::: + +The following example demonstrates generic and non-generic versions of the CompareTo method for several value and reference types. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/T.CompareTo/CPP/cat.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/Boolean/CompareTo/cat.cs" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/Boolean/CompareTo/cat.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/T.CompareTo/VB/cat.vb" id="Snippet1"::: + ]]> - Character sets include ignorable characters. The method does not consider such characters when it performs a culture-sensitive comparison. For example, if the following code is run on the .NET Framework 4 or later, a comparison of "animal" with "ani-mal" (using a soft hyphen, or U+00AD) indicates that the two strings are equivalent. - -:::code language="csharp" source="~/snippets/csharp/System/String/CompareTo/compareto2.cs" id="Snippet2"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/CompareTo/compareto2.fs" id="Snippet2"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.compareto/vb/compareto2.vb" id="Snippet2"::: - + Character sets include ignorable characters. The method does not consider such characters when it performs a culture-sensitive comparison. For example, if the following code is run on the .NET Framework 4 or later, a comparison of "animal" with "ani-mal" (using a soft hyphen, or U+00AD) indicates that the two strings are equivalent. + +:::code language="csharp" source="~/snippets/csharp/System/String/CompareTo/compareto2.cs" id="Snippet2"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/CompareTo/compareto2.fs" id="Snippet2"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.compareto/vb/compareto2.vb" id="Snippet2"::: + To recognize ignorable characters in a string comparison, call the method. @@ -2781,11 +2781,11 @@ To recognize ignorable characters in a string comparison, call the , or the representations of the values of one or more instances of . - [!NOTE] -> You can also use your language's string concatenation operator, such as `+` in C# and F#, or `&` and `+` in Visual Basic, to concatenate strings. Both compilers translate the concatenation operator into a call to one of the overloads of `String.Concat`. - + [!NOTE] +> You can also use your language's string concatenation operator, such as `+` in C# and F#, or `&` and `+` in Visual Basic, to concatenate strings. Both compilers translate the concatenation operator into a call to one of the overloads of `String.Concat`. + ]]> @@ -2848,28 +2848,28 @@ To recognize ignorable characters in a string comparison, call the collection of type . The concatenated strings in , or if is an empty . - method. - -An string is used in place of any null element in `values`. - -If `values` is an empty `IEnumerable(Of String)`, the method returns . If `values` is `null`, the method throws an exception. - - is a convenience method that lets you concatenate each element in an `IEnumerable(Of String)` collection without first converting the elements to a string array. It is particularly useful with Language-Integrated Query (LINQ) query expressions. The following example passes a `List(Of String)` object that contains either the uppercase or lowercase letters of the alphabet to a lambda expression that selects letters that are equal to or greater than a particular letter (which, in the example, is "M"). The `IEnumerable(Of String)` collection that is returned by the method is passed to the method to display the result as a single string. - -:::code language="csharp" source="~/snippets/csharp/System/String/Concat/concat2.cs" interactive="try-dotnet" id="Snippet3"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Concat/concat2.fs" id="Snippet3"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.concat/vb/concat2.vb" id="Snippet3"::: - -## Examples -The following example uses the Sieve of Eratosthenes algorithm to calculate the prime numbers that are less than or equal to 100. It assigns the result to a object of type , which it then passes to the method. - -:::code language="csharp" source="~/snippets/csharp/System/String/Concat/concat1.cs" interactive="try-dotnet" id="Snippet2"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Concat/concat1.fs" id="Snippet2"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.concat/vb/concat1.vb" id="Snippet2"::: - + method. + +An string is used in place of any null element in `values`. + +If `values` is an empty `IEnumerable(Of String)`, the method returns . If `values` is `null`, the method throws an exception. + + is a convenience method that lets you concatenate each element in an `IEnumerable(Of String)` collection without first converting the elements to a string array. It is particularly useful with Language-Integrated Query (LINQ) query expressions. The following example passes a `List(Of String)` object that contains either the uppercase or lowercase letters of the alphabet to a lambda expression that selects letters that are equal to or greater than a particular letter (which, in the example, is "M"). The `IEnumerable(Of String)` collection that is returned by the method is passed to the method to display the result as a single string. + +:::code language="csharp" source="~/snippets/csharp/System/String/Concat/concat2.cs" interactive="try-dotnet" id="Snippet3"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Concat/concat2.fs" id="Snippet3"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.concat/vb/concat2.vb" id="Snippet3"::: + +## Examples +The following example uses the Sieve of Eratosthenes algorithm to calculate the prime numbers that are less than or equal to 100. It assigns the result to a object of type , which it then passes to the method. + +:::code language="csharp" source="~/snippets/csharp/System/String/Concat/concat1.cs" interactive="try-dotnet" id="Snippet2"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Concat/concat1.fs" id="Snippet2"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.concat/vb/concat1.vb" id="Snippet2"::: + ]]> @@ -2930,19 +2930,19 @@ The following example uses the Sieve of Eratosthenes algorithm to calculate the Creates the string representation of a specified object. The string representation of the value of , or if is . - method represents `arg0` as a string by calling its parameterless `ToString` method. - -## Examples -The following example demonstrates the method. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.concat5/CPP/string.concat5.cpp" id="Snippet1"::: -:::code language="csharp" source="~/snippets/csharp/System/String/Concat/string.concat5.cs" interactive="try-dotnet" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Concat/string.concat5.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.concat5/VB/string.concat5.vb" id="Snippet1"::: - + method represents `arg0` as a string by calling its parameterless `ToString` method. + +## Examples +The following example demonstrates the method. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.concat5/CPP/string.concat5.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Concat/string.concat5.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Concat/string.concat5.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.concat5/VB/string.concat5.vb" id="Snippet1"::: + ]]> @@ -3007,20 +3007,20 @@ The following example demonstrates the method. Concatenates the string representations of the elements in a specified array. The concatenated string representations of the values of the elements in . - is used in place of any null object in the array. - -## Examples -The following example demonstrates the use of the method with an array. - -:::code language="csharp" source="~/snippets/csharp/System/String/Concat/stringconcat1.cs" interactive="try-dotnet" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Concat/stringconcat1.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringconcat1/VB/stringconcat1.vb" id="Snippet1"::: - + is used in place of any null object in the array. + +## Examples +The following example demonstrates the use of the method with an array. + +:::code language="csharp" source="~/snippets/csharp/System/String/Concat/stringconcat1.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Concat/stringconcat1.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringconcat1/VB/stringconcat1.vb" id="Snippet1"::: + ]]> @@ -3097,21 +3097,21 @@ The following example demonstrates the use of the Concatenates the elements of a specified array. The concatenated elements of . - string is used in place of any null object in the array. - -## Examples -The following example demonstrates the use of the method with a array. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringconcat3/CPP/stringconcat3.cpp" id="Snippet1"::: -:::code language="csharp" source="~/snippets/csharp/System/String/Concat/stringconcat3.cs" interactive="try-dotnet" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Concat/stringconcat3.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringconcat3/VB/stringconcat3.vb" id="Snippet1"::: - + string is used in place of any null object in the array. + +## Examples +The following example demonstrates the use of the method with a array. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringconcat3/CPP/stringconcat3.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Concat/stringconcat3.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Concat/stringconcat3.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringconcat3/VB/stringconcat3.vb" id="Snippet1"::: + ]]> @@ -3175,23 +3175,23 @@ The following example demonstrates the use of the Concatenates the string representations of two specified objects. The concatenated string representations of the values of and . - is used in place of any null argument. - -If either of the arguments is an array reference, the method concatenates a string representing that array, instead of its members (for example, "System.String[]"). - -## Examples -The following example demonstrates the method. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.concat5/CPP/string.concat5.cpp" id="Snippet1"::: -:::code language="csharp" source="~/snippets/csharp/System/String/Concat/string.concat5.cs" interactive="try-dotnet" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Concat/string.concat5.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.concat5/VB/string.concat5.vb" id="Snippet1"::: - + is used in place of any null argument. + +If either of the arguments is an array reference, the method concatenates a string representing that array, instead of its members (for example, "System.String[]"). + +## Examples +The following example demonstrates the method. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.concat5/CPP/string.concat5.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Concat/string.concat5.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Concat/string.concat5.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.concat5/VB/string.concat5.vb" id="Snippet1"::: + ]]> @@ -3302,21 +3302,21 @@ The following example demonstrates the method. Concatenates two specified instances of . The concatenation of and . - string is used in place of any null argument. - -## Examples -The following example concatenates a person's first, middle, and last name. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringconcat4/CPP/stringconcat4.cpp" id="Snippet1"::: -:::code language="csharp" source="~/snippets/csharp/System/String/Concat/stringconcat4.cs" interactive="try-dotnet" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Concat/stringconcat4.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringconcat4/VB/stringconcat4.vb" id="Snippet1"::: - + string is used in place of any null argument. + +## Examples +The following example concatenates a person's first, middle, and last name. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringconcat4/CPP/stringconcat4.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Concat/stringconcat4.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Concat/stringconcat4.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringconcat4/VB/stringconcat4.vb" id="Snippet1"::: + ]]> @@ -3379,21 +3379,21 @@ The following example concatenates a person's first, middle, and last name. Concatenates the string representations of three specified objects. The concatenated string representations of the values of , , and . - is used in place of any null argument. - -## Examples -The following example demonstrates the method. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.concat5/CPP/string.concat5.cpp" id="Snippet1"::: -:::code language="csharp" source="~/snippets/csharp/System/String/Concat/string.concat5.cs" interactive="try-dotnet" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Concat/string.concat5.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.concat5/VB/string.concat5.vb" id="Snippet1"::: - + is used in place of any null argument. + +## Examples +The following example demonstrates the method. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.concat5/CPP/string.concat5.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Concat/string.concat5.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Concat/string.concat5.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.concat5/VB/string.concat5.vb" id="Snippet1"::: + ]]> @@ -3508,19 +3508,19 @@ The following example demonstrates the method. Concatenates three specified instances of . The concatenation of , , and . - method to concatenate three strings and displays the result. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.string.concat/cpp/Concat6.cpp" id="Snippet6"::: -:::code language="csharp" source="~/snippets/csharp/System/String/Concat/Concat6.cs" interactive="try-dotnet" id="Snippet6"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Concat/Concat6.fs" id="Snippet6"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.concat/vb/Concat6.vb" id="Snippet6"::: - + method to concatenate three strings and displays the result. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.string.concat/cpp/Concat6.cpp" id="Snippet6"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Concat/Concat6.cs" interactive="try-dotnet" id="Snippet6"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Concat/Concat6.fs" id="Snippet6"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.concat/vb/Concat6.vb" id="Snippet6"::: + ]]> @@ -3561,10 +3561,10 @@ The following example uses the method to concaten System.String - - - - + + + + The first object to concatenate. @@ -3574,27 +3574,27 @@ The following example uses the method to concaten Concatenates the string representations of four specified objects and any objects specified in an optional variable length parameter list. The concatenated string representation of each value in the parameter list. - [!NOTE] -> This API is not CLS-compliant. The CLS-compliant alternative is . The C# and Visual Basic compilers automatically resolve a call to this method as a call to . - -The method concatenates each object in the parameter list by calling its parameterless `ToString` method; it does not add any delimiters. - - is used in place of any null argument. - -> [!NOTE] -> The last parameter of the method is an optional comma-delimited list of one or more additional objects to concatenate. - -## Examples -The following example illustrates the use of the method to concatenate a list of variable parameters. In this case, the method is called with nine parameters. - -:::code language="csharp" source="~/snippets/csharp/System/String/Concat/concat4.cs" interactive="try-dotnet" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Concat/concat4.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.concat/vb/concat4.vb" id="Snippet1"::: - + [!NOTE] +> This API is not CLS-compliant. The CLS-compliant alternative is . The C# and Visual Basic compilers automatically resolve a call to this method as a call to . + +The method concatenates each object in the parameter list by calling its parameterless `ToString` method; it does not add any delimiters. + + is used in place of any null argument. + +> [!NOTE] +> The last parameter of the method is an optional comma-delimited list of one or more additional objects to concatenate. + +## Examples +The following example illustrates the use of the method to concatenate a list of variable parameters. In this case, the method is called with nine parameters. + +:::code language="csharp" source="~/snippets/csharp/System/String/Concat/concat4.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Concat/concat4.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.concat/vb/concat4.vb" id="Snippet1"::: + ]]> @@ -3714,18 +3714,18 @@ The following example illustrates the use of the Concatenates four specified instances of . The concatenation of , , , and . - method to reassemble the scrambled words. - -:::code language="csharp" source="~/snippets/csharp/System/String/Concat/concat4.cs" interactive="try-dotnet" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Concat/concat4.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.concat/vb/concat4.vb" id="Snippet1"::: - + method to reassemble the scrambled words. + +:::code language="csharp" source="~/snippets/csharp/System/String/Concat/concat4.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Concat/concat4.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.concat/vb/concat4.vb" id="Snippet1"::: + ]]> @@ -3792,22 +3792,22 @@ The following example defines an array of four-letter words and stores their ind Concatenates the members of an implementation. The concatenated members in . - string is used in place of any null argument. - - is a convenience method that lets you concatenate each element in an collection without first converting the elements to strings. It is particularly useful with Language-Integrated Query (LINQ) query expressions, as the example illustrates. The string representation of each object in the collection is derived by calling that object's `ToString` method. - -## Examples -The following example defines a very simple `Animal` class that contains the name of an animal and the order to which it belongs. It then defines a object to contain a number of `Animal` objects. The extension method is called to extract the `Animal` objects whose `Order` property equals "Rodent". The result is passed to the method and displayed to the console. - -:::code language="csharp" source="~/snippets/csharp/System/String/Concat/concat3.cs" interactive="try-dotnet" id="Snippet4"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Concat/concat3.fs" id="Snippet4"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.concat/vb/concat3.vb" id="Snippet4"::: - + string is used in place of any null argument. + + is a convenience method that lets you concatenate each element in an collection without first converting the elements to strings. It is particularly useful with Language-Integrated Query (LINQ) query expressions, as the example illustrates. The string representation of each object in the collection is derived by calling that object's `ToString` method. + +## Examples +The following example defines a very simple `Animal` class that contains the name of an animal and the order to which it belongs. It then defines a object to contain a number of `Animal` objects. The extension method is called to extract the `Animal` objects whose `Order` property equals "Rodent". The result is passed to the method and displayed to the console. + +:::code language="csharp" source="~/snippets/csharp/System/String/Concat/concat3.cs" interactive="try-dotnet" id="Snippet4"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Concat/concat3.fs" id="Snippet4"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.concat/vb/concat3.vb" id="Snippet4"::: + ]]> @@ -3851,10 +3851,10 @@ The following example defines a very simple `Animal` class that contains the nam if the parameter occurs within this string; otherwise, . - @@ -3911,34 +3911,34 @@ This method performs an ordinal (case-sensitive and culture-insensitive) compari if the parameter occurs within this string, or if is the empty string (""); otherwise, . - overload instead. - -- On .NET Framework: Create a custom method. The following example illustrates one such approach. It defines a extension method that includes a parameter and indicates whether a string contains a substring when using the specified form of string comparison. - -:::code language="csharp" source="~/snippets/csharp/System/String/Contains/ContainsExt1.cs" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Contains/ContainsExt1.fs" id="Snippet1"::: -:::code language="csharp" source="~/snippets/csharp/System/String/Contains/ContainsExt1.cs" id="Snippet2"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Contains/ContainsExt1.fs" id="Snippet2"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/System.String.Contains/vb/ContainsExt1.vb" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/System.String.Contains/vb/ContainsExt1.vb" id="Snippet2"::: - -If you are interested in the position of the substring `value` in the current instance, you can call the method to get the starting position of its first occurrence, or you can call the method to get the starting position of its last occurrence. The example includes a call to the method if a substring is found in a string instance. - -## Examples -The following example determines whether the string "fox" is a substring of a familiar quotation. If "fox" is found in the string, it also displays its starting position. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.contains/CPP/cont.cpp" id="Snippet1"::: -:::code language="csharp" source="~/snippets/csharp/System/String/Contains/cont.cs" interactive="try-dotnet-method" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Contains/cont.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.contains/VB/cont.vb" id="Snippet1"::: - + overload instead. + +- On .NET Framework: Create a custom method. The following example illustrates one such approach. It defines a extension method that includes a parameter and indicates whether a string contains a substring when using the specified form of string comparison. + +:::code language="csharp" source="~/snippets/csharp/System/String/Contains/ContainsExt1.cs" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Contains/ContainsExt1.fs" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Contains/ContainsExt1.cs" id="Snippet2"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Contains/ContainsExt1.fs" id="Snippet2"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/System.String.Contains/vb/ContainsExt1.vb" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/System.String.Contains/vb/ContainsExt1.vb" id="Snippet2"::: + +If you are interested in the position of the substring `value` in the current instance, you can call the method to get the starting position of its first occurrence, or you can call the method to get the starting position of its last occurrence. The example includes a call to the method if a substring is found in a string instance. + +## Examples +The following example determines whether the string "fox" is a substring of a familiar quotation. If "fox" is found in the string, it also displays its starting position. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.contains/CPP/cont.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Contains/cont.cs" interactive="try-dotnet-method" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Contains/cont.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.contains/VB/cont.vb" id="Snippet1"::: + ]]> @@ -4078,43 +4078,43 @@ The following example determines whether the string "fox" is a substring of a fa System.String - + The string to copy. Creates a new instance of with the same value as a specified . A new string with the same value as . - object that has the same value as the original string but represents a different object reference. It differs from an assignment operation, which assigns an existing string reference to an additional object variable. - -> [!IMPORTANT] -> Starting with .NET Core 3.0, this method is obsolete. However, we do not recommend its use in any .NET implementation. In particular, because of changes in string interning in .NET Core 3.0, in some cases the `Copy` method will not create a new string but will simply return a reference to an existing interned string. - -Depending on Why you want to call the `Copy` method, there are a number of alternatives: - -- If you want a different string instance to use in an operation that modifies the string, use the original string instance. Because strings are immutable, the string operation creates a new string instance, and the original string remains unaffected. In this case, you should not assign the new string reference to the original string variable. The following example provides an illustration. - - :::code language="csharp" source="~/snippets/csharp/System/String/Copy/Program.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/Copy/Program.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/api/system/string/copy/program.vb" id="Snippet1"::: - - In this case, calling the `Copy` method to create a new string before calling the method unnecessarily creates a new string instance. - -- If you want to create a mutable buffer with the same contents as the original string, call the or constructor. For example: - - :::code language="csharp" source="~/snippets/csharp/System/String/Copy/Program.cs" id="Snippet2"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/Copy/Program.fs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/api/system/string/copy/program.vb" id="Snippet2"::: - -- If you want to create a mutable copy of the string so that you can use unsafe code to modify the string contents, use method. The following example uses the method to get a pointer to the location of an copied string in unmanaged memory, increments the Unicode code point of each character in the string by one, and copies the resulting string back to a managed string. - - :::code language="csharp" source="~/snippets/csharp/System/String/Copy/Program.cs" id="Snippet3"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/Copy/Program.fs" id="Snippet3"::: - + object that has the same value as the original string but represents a different object reference. It differs from an assignment operation, which assigns an existing string reference to an additional object variable. + +> [!IMPORTANT] +> Starting with .NET Core 3.0, this method is obsolete. However, we do not recommend its use in any .NET implementation. In particular, because of changes in string interning in .NET Core 3.0, in some cases the `Copy` method will not create a new string but will simply return a reference to an existing interned string. + +Depending on Why you want to call the `Copy` method, there are a number of alternatives: + +- If you want a different string instance to use in an operation that modifies the string, use the original string instance. Because strings are immutable, the string operation creates a new string instance, and the original string remains unaffected. In this case, you should not assign the new string reference to the original string variable. The following example provides an illustration. + + :::code language="csharp" source="~/snippets/csharp/System/String/Copy/Program.cs" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/System/String/Copy/Program.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/api/system/string/copy/program.vb" id="Snippet1"::: + + In this case, calling the `Copy` method to create a new string before calling the method unnecessarily creates a new string instance. + +- If you want to create a mutable buffer with the same contents as the original string, call the or constructor. For example: + + :::code language="csharp" source="~/snippets/csharp/System/String/Copy/Program.cs" id="Snippet2"::: + :::code language="fsharp" source="~/snippets/fsharp/System/String/Copy/Program.fs" id="Snippet2"::: + :::code language="vb" source="~/snippets/visualbasic/api/system/string/copy/program.vb" id="Snippet2"::: + +- If you want to create a mutable copy of the string so that you can use unsafe code to modify the string contents, use method. The following example uses the method to get a pointer to the location of an copied string in unmanaged memory, increments the Unicode code point of each character in the string by one, and copies the resulting string back to a managed string. + + :::code language="csharp" source="~/snippets/csharp/System/String/Copy/Program.cs" id="Snippet3"::: + :::code language="fsharp" source="~/snippets/fsharp/System/String/Copy/Program.fs" id="Snippet3"::: + ]]> @@ -4218,42 +4218,42 @@ Depending on Why you want to call the `Copy` method, there are a number of alter The number of characters in this instance to copy to . Copies a specified number of characters from a specified position in this instance to a specified position in an array of Unicode characters. - . - -`sourceIndex` and `destinationIndex` are zero-based. - -## Examples -The following example demonstrates the method. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringcopyto/CPP/stringcopyto.cpp" id="Snippet1"::: -:::code language="csharp" source="~/snippets/csharp/System/String/CopyTo/stringcopyto.cs" interactive="try-dotnet" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/CopyTo/stringcopyto.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringcopyto/VB/stringcopyto.vb" id="Snippet1"::: - + . + +`sourceIndex` and `destinationIndex` are zero-based. + +## Examples +The following example demonstrates the method. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringcopyto/CPP/stringcopyto.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/CopyTo/stringcopyto.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/CopyTo/stringcopyto.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringcopyto/VB/stringcopyto.vb" id="Snippet1"::: + ]]> is . - , , or is negative - --or- - - does not identify a position in the current instance. - --or- - - does not identify a valid index in the array. - --or- - - is greater than the length of the substring from to the end of this instance - --or- - + , , or is negative + +-or- + + does not identify a position in the current instance. + +-or- + + does not identify a valid index in the array. + +-or- + + is greater than the length of the substring from to the end of this instance + +-or- + is greater than the length of the subarray from to the end of the array. @@ -4420,9 +4420,9 @@ The following example demonstrates the method. Creates a new string with a specific length and initializes it after creation by using the specified callback. The created string. - @@ -4468,13 +4468,13 @@ The initial content of the destination span passed to `action` is undefined. The Represents the empty string. This field is read-only. - , use the method. - + , use the method. + ]]> @@ -4528,12 +4528,12 @@ In application code, this field is most commonly used in assignments to initiali if matches the end of this instance; otherwise, . - @@ -4585,27 +4585,27 @@ This method performs an ordinal (case-sensitive and culture-insensitive) compari if matches the end of this instance; otherwise, . - method to remove HTML end tags from the end of a line. Note that the `StripEndTags` method is called recursively to ensure that multiple HTML end tags at the end of the line are removed. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringendswith/CPP/stringendswith.cpp" id="Snippet1"::: -:::code language="csharp" source="~/snippets/csharp/System/String/EndsWith/stringendswith.cs" interactive="try-dotnet" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/EndsWith/stringendswith.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringendswith/VB/stringendswith.vb" id="Snippet1"::: - + method to remove HTML end tags from the end of a line. Note that the `StripEndTags` method is called recursively to ensure that multiple HTML end tags at the end of the line are removed. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringendswith/CPP/stringendswith.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/EndsWith/stringendswith.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/EndsWith/stringendswith.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringendswith/VB/stringendswith.vb" id="Snippet1"::: + ]]> @@ -4675,19 +4675,19 @@ The following example defines a `StripEndTags` method that uses the if the parameter matches the end of this string; otherwise, . - method compares the `value` parameter to the substring at the end of this string and returns a value that indicates whether they are equal. To be equal, `value` must be a reference to this same string, must be the empty string (""), or must match the end of this string. The type of comparison performed by the method depends on the value of the `comparisonType` parameter. - -## Examples -The following example determines whether a string ends with a particular substring. The results are affected by the choice of culture, whether case is ignored, and whether an ordinal comparison is performed. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.EndsWithCmp/cpp/ewcmp.cpp" id="Snippet1"::: -:::code language="csharp" source="~/snippets/csharp/System/String/EndsWith/ewcmp.cs" interactive="try-dotnet" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/EndsWith/ewcmp.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.EndsWithCmp/vb/ewcmp.vb" id="Snippet1"::: - + method compares the `value` parameter to the substring at the end of this string and returns a value that indicates whether they are equal. To be equal, `value` must be a reference to this same string, must be the empty string (""), or must match the end of this string. The type of comparison performed by the method depends on the value of the `comparisonType` parameter. + +## Examples +The following example determines whether a string ends with a particular substring. The results are affected by the choice of culture, whether case is ignored, and whether an ordinal comparison is performed. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.EndsWithCmp/cpp/ewcmp.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/EndsWith/ewcmp.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/EndsWith/ewcmp.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.EndsWithCmp/vb/ewcmp.vb" id="Snippet1"::: + ]]> @@ -4732,9 +4732,9 @@ The following example determines whether a string ends with a particular substri System.Boolean - - - + + + [System.Runtime.CompilerServices.Nullable(2)] @@ -4752,20 +4752,20 @@ The following example determines whether a string ends with a particular substri if the parameter matches the end of this string; otherwise, . - method is called several times using case sensitivity, case insensitivity, and different cultures that influence the results of the search. - -:::code language="csharp" source="~/snippets/csharp/System/String/EndsWith/ewci.cs" interactive="try-dotnet" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/EndsWith/ewci.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.EndsWithCI/vb/ewci.vb" id="Snippet1"::: - + method is called several times using case sensitivity, case insensitivity, and different cultures that influence the results of the search. + +:::code language="csharp" source="~/snippets/csharp/System/String/EndsWith/ewci.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/EndsWith/ewci.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.EndsWithCI/vb/ewci.vb" id="Snippet1"::: + ]]> @@ -4805,12 +4805,12 @@ The following example determines whether a string occurs at the end of another s Returns an enumeration of from this string. A string rune enumerator. - . - + . + ]]> @@ -4893,19 +4893,19 @@ Invalid sequences are represented in the enumeration by if is a and its value is the same as this instance; otherwise, . If is , the method returns . - method. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.equals/CPP/equals.cpp" id="Snippet1"::: -:::code language="csharp" source="~/snippets/csharp/System/String/Equals/equals.cs" interactive="try-dotnet" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Equals/equals.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.equals/VB/equals.vb" id="Snippet1"::: - + method. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.equals/CPP/equals.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Equals/equals.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Equals/equals.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.equals/VB/equals.vb" id="Snippet1"::: + ]]> @@ -4986,18 +4986,18 @@ The following example demonstrates the method. if the value of the parameter is the same as the value of this instance; otherwise, . If is , the method returns . - method. It compares the title-cased word "File" with an equivalent word, its lowercase equivalent, its uppercase equivalent, and a word that contains LATIN SMALL LETTER DOTLESS I (U+0131) instead of LATIN SMALL LETTER I (U+0069). Because the method performs an ordinal comparison, only the comparison with an identical word returns `true`. - -:::code language="csharp" source="~/snippets/csharp/System/String/Equals/equalsex1.cs" id="Snippet2"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Equals/equalsex1.fs" id="Snippet2"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.equals/vb/equalsex1.vb" id="Snippet2"::: - + method. It compares the title-cased word "File" with an equivalent word, its lowercase equivalent, its uppercase equivalent, and a word that contains LATIN SMALL LETTER DOTLESS I (U+0131) instead of LATIN SMALL LETTER I (U+0069). Because the method performs an ordinal comparison, only the comparison with an identical word returns `true`. + +:::code language="csharp" source="~/snippets/csharp/System/String/Equals/equalsex1.cs" id="Snippet2"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Equals/equalsex1.fs" id="Snippet2"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.equals/vb/equalsex1.vb" id="Snippet2"::: + ]]> @@ -5063,19 +5063,19 @@ The following example demonstrates the method. It if the value of is the same as the value of ; otherwise, . If both and are , the method returns . - method. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.equals/CPP/equals.cpp" id="Snippet1"::: -:::code language="csharp" source="~/snippets/csharp/System/String/Equals/equals.cs" interactive="try-dotnet" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Equals/equals.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.equals/VB/equals.vb" id="Snippet1"::: - + method. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.equals/CPP/equals.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Equals/equals.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Equals/equals.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.equals/VB/equals.vb" id="Snippet1"::: + ]]> @@ -5147,18 +5147,18 @@ The following example demonstrates the method. if the value of the parameter is the same as this string; otherwise, . - method to compare them by using each possible enumeration value. - -:::code language="csharp" source="~/snippets/csharp/System/String/Equals/eqcmp.cs" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Equals/eqcmp.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.equals/vb/eqcmp.vb" id="Snippet1"::: - + method to compare them by using each possible enumeration value. + +:::code language="csharp" source="~/snippets/csharp/System/String/Equals/eqcmp.cs" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Equals/eqcmp.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.equals/vb/eqcmp.vb" id="Snippet1"::: + ]]> @@ -5227,18 +5227,18 @@ The following example creates a string array that consists of an uppercase "I", if the value of the parameter is equal to the value of the parameter; otherwise, . - enumeration. The comparisons use the conventions of the English (United States), Thai (Thailand) and Turkish (Turkey) cultures. Note that the strings "a" and "a-" are considered equivalent in the "th-TH" culture but not in the others, while "i" and "İ" are considered equivalent in the "tr-TR" culture when case is ignored but not in the other cultures. - -:::code language="csharp" source="~/snippets/csharp/System/String/Equals/equals_ex3.cs" interactive="try-dotnet" id="Snippet3"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Equals/equals_ex3.fs" id="Snippet3"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.equals/vb/equals_ex3.vb" id="Snippet3"::: - + enumeration. The comparisons use the conventions of the English (United States), Thai (Thailand) and Turkish (Turkey) cultures. Note that the strings "a" and "a-" are considered equivalent in the "th-TH" culture but not in the others, while "i" and "İ" are considered equivalent in the "tr-TR" culture when case is ignored but not in the other cultures. + +:::code language="csharp" source="~/snippets/csharp/System/String/Equals/equals_ex3.cs" interactive="try-dotnet" id="Snippet3"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Equals/equals_ex3.fs" id="Snippet3"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.equals/vb/equals_ex3.vb" id="Snippet3"::: + ]]> @@ -5253,8 +5253,8 @@ The following example compares three sets of strings by using each member of the 4.1.0.0 - Converts the value of objects to strings based on the formats specified and inserts them into another string. - + Converts the value of objects to strings based on the formats specified and inserts them into another string. + If you are new to the `String.Format` method, see [Get started with the String.Format method](/dotnet/fundamentals/runtime-libraries/system-string-format#get-started-with-the-stringformat-method) for a quick overview. For more information about this API, see Supplemental API remarks for String.Format. Formatting Types in .NET @@ -5329,33 +5329,33 @@ If you are new to the `String.Format` method, see [Get started with the String.F Replaces one or more format items in a string with the string representation of a specified object. A copy of in which any format items are replaced by the string representation of . - method to embed an individual's age in the middle of a string. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Format/cpp/format7.cpp" id="Snippet7"::: -:::code language="csharp" source="~/snippets/csharp/System/FormatException/Overview/format7.cs" interactive="try-dotnet-method" id="Snippet7"::: -:::code language="fsharp" source="~/snippets/fsharp/System/FormatException/Overview/format7.fs" id="Snippet7"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/format7.vb" id="Snippet7"::: - + method to embed an individual's age in the middle of a string. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Format/cpp/format7.cpp" id="Snippet7"::: +:::code language="csharp" source="~/snippets/csharp/System/FormatException/Overview/format7.cs" interactive="try-dotnet-method" id="Snippet7"::: +:::code language="fsharp" source="~/snippets/fsharp/System/FormatException/Overview/format7.fs" id="Snippet7"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/format7.vb" id="Snippet7"::: + ]]> is . - The format item in is invalid. - --or- - + The format item in is invalid. + +-or- + The index of a format item is not zero. Formatting Types in .NET Composite Formatting @@ -5435,41 +5435,41 @@ The index of a format item is not zero. Replaces the format item in a specified string with the string representation of a corresponding object in a specified array. A copy of in which the format items have been replaced by the string representation of the corresponding objects in . - attribute, you can pass the objects to the method as individual arguments or as an array. - -[!INCLUDE[simple-string-format](~/includes/remarks/System/String/simple-string-format.md)] - -## Example: Format more than three arguments - -This example creates a string that contains data on the high and low temperature on a particular date. The composite format string has five format items in the C# example and six in the Visual Basic example. Two of the format items define the width of their corresponding value's string representation, and the first format item also includes a standard date and time format string. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Format/cpp/format5.cpp" id="Snippet5"::: -:::code language="csharp" source="~/snippets/csharp/System/FormatException/Overview/format5.cs" id="Snippet5"::: -:::code language="fsharp" source="~/snippets/fsharp/System/FormatException/Overview/format5.fs" id="Snippet5"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/format5.vb" id="Snippet5"::: - -You can also pass the objects to be formatted as an array rather than as an argument list. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Format/cpp/format_paramarray1.cpp" id="Snippet10"::: -:::code language="csharp" source="~/snippets/csharp/System/FormatException/Overview/format_paramarray1.cs" interactive="try-dotnet" id="Snippet10"::: -:::code language="fsharp" source="~/snippets/fsharp/System/FormatException/Overview/format_paramarray1.fs" id="Snippet10"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/format_paramarray1.vb" id="Snippet10"::: - + attribute, you can pass the objects to the method as individual arguments or as an array. + +[!INCLUDE[simple-string-format](~/includes/remarks/System/String/simple-string-format.md)] + +## Example: Format more than three arguments + +This example creates a string that contains data on the high and low temperature on a particular date. The composite format string has five format items in the C# example and six in the Visual Basic example. Two of the format items define the width of their corresponding value's string representation, and the first format item also includes a standard date and time format string. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Format/cpp/format5.cpp" id="Snippet5"::: +:::code language="csharp" source="~/snippets/csharp/System/FormatException/Overview/format5.cs" id="Snippet5"::: +:::code language="fsharp" source="~/snippets/fsharp/System/FormatException/Overview/format5.fs" id="Snippet5"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/format5.vb" id="Snippet5"::: + +You can also pass the objects to be formatted as an array rather than as an argument list. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Format/cpp/format_paramarray1.cpp" id="Snippet10"::: +:::code language="csharp" source="~/snippets/csharp/System/FormatException/Overview/format_paramarray1.cs" interactive="try-dotnet" id="Snippet10"::: +:::code language="fsharp" source="~/snippets/fsharp/System/FormatException/Overview/format_paramarray1.fs" id="Snippet10"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/format_paramarray1.vb" id="Snippet10"::: + ]]> or is . - is invalid. - --or- - + is invalid. + +-or- + The index of a format item is less than zero, or greater than or equal to the length of the array. Formatting Types in .NET Composite Formatting @@ -5550,25 +5550,25 @@ The index of a format item is less than zero, or greater than or equal to the le Replaces the format item or items in a specified string with the string representation of the corresponding object. A parameter supplies culture-specific formatting information. A copy of in which the format item or items have been replaced by the string representation of . - is . - is invalid. - --or- - + is invalid. + +-or- + The index of a format item is not zero. @@ -5654,35 +5654,35 @@ The index of a format item is not zero. Replaces the format items in a string with the string representations of corresponding objects in a specified array. A parameter supplies culture-specific formatting information. A copy of in which the format items have been replaced by the string representation of the corresponding objects in . - argument to its string representation by calling its **ToString(IFormatProvider)** method or, if the object's corresponding format item includes a format string, by calling its **ToString(String,IFormatProvider)** method. If these methods don't exist, it calls the object's parameterless **ToString** method. - -[!INCLUDE[provider-string-format](~/includes/remarks/System/String/provider-string-format.md)] - - - -### Example: Culture-sensitive formatting - -This example uses the method to display the string representation of some date and time values and numeric values by using several different cultures. - -:::code language="csharp" source="~/snippets/csharp/System/String/Format/Example2.cs" interactive="try-dotnet-method" id="Snippet2"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Format/Example2.fs" id="Snippet2"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format2/vb/Example2.vb" id="Snippet2"::: - + argument to its string representation by calling its **ToString(IFormatProvider)** method or, if the object's corresponding format item includes a format string, by calling its **ToString(String,IFormatProvider)** method. If these methods don't exist, it calls the object's parameterless **ToString** method. + +[!INCLUDE[provider-string-format](~/includes/remarks/System/String/provider-string-format.md)] + + + +### Example: Culture-sensitive formatting + +This example uses the method to display the string representation of some date and time values and numeric values by using several different cultures. + +:::code language="csharp" source="~/snippets/csharp/System/String/Format/Example2.cs" interactive="try-dotnet-method" id="Snippet2"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Format/Example2.fs" id="Snippet2"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format2/vb/Example2.vb" id="Snippet2"::: + ]]> or is . - is invalid. - --or- - + is invalid. + +-or- + The index of a format item is less than zero, or greater than or equal to the length of the array. @@ -5879,34 +5879,34 @@ The index of a format item is less than zero, or greater than or equal to the le Replaces the format items in a string with the string representation of two specified objects. A copy of in which format items are replaced by the string representations of and . - method to display time and temperature data stored in a generic object. Note that the format string has three format items, although there are only two objects to format. This is because the first object in the list (a date and time value) is used by two format items: The first format item displays the time, and the second displays the date. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Format/cpp/formatexample4.cpp" id="Snippet6"::: -:::code language="csharp" source="~/snippets/csharp/System/FormatException/Overview/formatexample4.cs" id="Snippet6"::: -:::code language="fsharp" source="~/snippets/fsharp/System/FormatException/Overview/formatexample4.fs" id="Snippet6"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/formatexample4.vb" id="Snippet6"::: - + method to display time and temperature data stored in a generic object. Note that the format string has three format items, although there are only two objects to format. This is because the first object in the list (a date and time value) is used by two format items: The first format item displays the time, and the second displays the date. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Format/cpp/formatexample4.cpp" id="Snippet6"::: +:::code language="csharp" source="~/snippets/csharp/System/FormatException/Overview/formatexample4.cs" id="Snippet6"::: +:::code language="fsharp" source="~/snippets/fsharp/System/FormatException/Overview/formatexample4.fs" id="Snippet6"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/formatexample4.vb" id="Snippet6"::: + ]]> is . - is invalid. - --or- - + is invalid. + +-or- + The index of a format item is not zero or one. Formatting Types in .NET Composite Formatting @@ -5985,25 +5985,25 @@ The index of a format item is not zero or one. Replaces the format items in a string with the string representation of two specified objects. A parameter supplies culture-specific formatting information. A copy of in which format items are replaced by the string representations of and . - argument to its string representation by calling its **ToString(IFormatProvider)** method or, if the object's corresponding format item includes a format string, by calling its **ToString(String,IFormatProvider)** method. If these methods don't exist, it calls the object's parameterless **ToString** method. - -[!INCLUDE[provider-string-format](~/includes/remarks/System/String/provider-string-format.md)] - + argument to its string representation by calling its **ToString(IFormatProvider)** method or, if the object's corresponding format item includes a format string, by calling its **ToString(String,IFormatProvider)** method. If these methods don't exist, it calls the object's parameterless **ToString** method. + +[!INCLUDE[provider-string-format](~/includes/remarks/System/String/provider-string-format.md)] + ]]> is . - is invalid. - --or- - + is invalid. + +-or- + The index of a format item is not zero or one. @@ -6075,34 +6075,34 @@ The index of a format item is not zero or one. Replaces the format items in a string with the string representation of three specified objects. A copy of in which the format items have been replaced by the string representations of , , and . - method to create a string that illustrates the result of a Boolean `And` operation with two integer values. Note that the format string includes six format items, but the method has only three items in its parameter list, because each item is formatted in two different ways. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Format/cpp/format4.cpp" id="Snippet4"::: -:::code language="csharp" source="~/snippets/csharp/System/FormatException/Overview/format4.cs" interactive="try-dotnet-method" id="Snippet4"::: -:::code language="fsharp" source="~/snippets/fsharp/System/FormatException/Overview/format4.fs" id="Snippet4"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/format4.vb" id="Snippet4"::: - + method to create a string that illustrates the result of a Boolean `And` operation with two integer values. Note that the format string includes six format items, but the method has only three items in its parameter list, because each item is formatted in two different ways. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Format/cpp/format4.cpp" id="Snippet4"::: +:::code language="csharp" source="~/snippets/csharp/System/FormatException/Overview/format4.cs" interactive="try-dotnet-method" id="Snippet4"::: +:::code language="fsharp" source="~/snippets/fsharp/System/FormatException/Overview/format4.fs" id="Snippet4"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/format4.vb" id="Snippet4"::: + ]]> is . - is invalid. - --or- - + is invalid. + +-or- + The index of a format item is less than zero, or greater than two. Formatting Types in .NET Composite Formatting @@ -6176,25 +6176,25 @@ The index of a format item is less than zero, or greater than two. Replaces the format items in a string with the string representation of three specified objects. An parameter supplies culture-specific formatting information. A copy of in which the format items have been replaced by the string representations of , , and . - argument to its string representation by calling its **ToString(IFormatProvider)** method or, if the object's corresponding format item includes a format string, by calling its **ToString(String,IFormatProvider)** method. If these methods don't exist, it calls the object's parameterless **ToString** method. - -[!INCLUDE[provider-string-format](~/includes/remarks/System/String/provider-string-format.md)] - + argument to its string representation by calling its **ToString(IFormatProvider)** method or, if the object's corresponding format item includes a format string, by calling its **ToString(String,IFormatProvider)** method. If these methods don't exist, it calls the object's parameterless **ToString** method. + +[!INCLUDE[provider-string-format](~/includes/remarks/System/String/provider-string-format.md)] + ]]> is . - is invalid. - --or- - + is invalid. + +-or- + The index of a format item is less than zero, or greater than two. @@ -6441,23 +6441,23 @@ The index of a format item is less than zero, or greater than two. Retrieves an object that can iterate through the individual characters in this string. An enumerator object. - [!TIP] -> Rather than calling the method to retrieve a object that you then use to enumerate a string, you should instead use your language's iteration construct (in C#, in F#, in C++/CLR, and in Visual Basic). [foreach](/dotnet/csharp/language-reference/keywords/foreach-in) in C#, [for..in](/dotnet/fsharp/language-reference/loops-for-in-expression) in F#, [for each](/cpp/dotnet/for-each-in) in C++/CLR, and [For Each](/dotnet/visual-basic/language-reference/statements/for-each-next-statement) in Visual Basic). - -This method enables you to iterate the individual characters in a string. For example, the Visual Basic `For Each`, the F# `for..in` expression, and C# `foreach` statements invoke this method to return a object that can provide read-only access to the characters in this string instance. - -## Examples -The following example iterates the characters in several strings and displays information about their individual characters. It uses the language iteration construct rather than a call to the method. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.GetEnumerator/CPP/getenumerator.cpp" id="Snippet1"::: -:::code language="csharp" source="~/snippets/csharp/System/String/GetEnumerator/getenumerator.cs" interactive="try-dotnet" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/GetEnumerator/getenumerator.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.GetEnumerator/VB/getenumerator.vb" id="Snippet1"::: - + [!TIP] +> Rather than calling the method to retrieve a object that you then use to enumerate a string, you should instead use your language's iteration construct (in C#, in F#, in C++/CLR, and in Visual Basic). [foreach](/dotnet/csharp/language-reference/keywords/foreach-in) in C#, [for..in](/dotnet/fsharp/language-reference/loops-for-in-expression) in F#, [for each](/cpp/dotnet/for-each-in) in C++/CLR, and [For Each](/dotnet/visual-basic/language-reference/statements/for-each-next-statement) in Visual Basic). + +This method enables you to iterate the individual characters in a string. For example, the Visual Basic `For Each`, the F# `for..in` expression, and C# `foreach` statements invoke this method to return a object that can provide read-only access to the characters in this string instance. + +## Examples +The following example iterates the characters in several strings and displays information about their individual characters. It uses the language iteration construct rather than a call to the method. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.GetEnumerator/CPP/getenumerator.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/GetEnumerator/getenumerator.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/GetEnumerator/getenumerator.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.GetEnumerator/VB/getenumerator.vb" id="Snippet1"::: + ]]> @@ -6518,66 +6518,66 @@ The following example iterates the characters in several strings and displays in Returns the hash code for this string. A 32-bit signed integer hash code. - is dependent on its implementation, which might change from one version of the common language runtime to another. A reason why this might happen is to improve the performance of . - -> [!IMPORTANT] -> If two string objects are equal, the method returns identical values. However, there is not a unique hash code value for each unique string value. Different strings can return the same hash code. -> -> The hash code itself is not guaranteed to be stable. Hash codes for identical strings can differ across .NET implementations, across .NET versions, and across .NET platforms (such as 32-bit and 64-bit) for a single version of .NET. In some cases, they can even differ by application domain. This implies that two subsequent runs of the same program may return different hash codes. -> -> As a result, hash codes should never be used outside of the application domain in which they were created, they should never be used as key fields in a collection, and they should never be persisted. -> -> Finally, don't use the hash code instead of a value returned by a cryptographic hashing function if you need a cryptographically strong hash. For cryptographic hashes, use a class derived from the or class. -> -> For more information about hash codes, see . - -In .NET Framework desktop apps, you can use the [\ element](/dotnet/framework/configure-apps/file-schema/runtime/userandomizedstringhashalgorithm-element) to generate unique hash codes on a per-application domain basis. This can reduce the number of collisions and improve the overall performance of insertions and lookups that use hash tables. The following example shows how to use the [\ element](/dotnet/framework/configure-apps/file-schema/runtime/userandomizedstringhashalgorithm-element). It defines a `DisplayString` class that includes a private string constant, `s`, whose value is "This is a string." It also includes a `ShowStringHashCode` method that displays the string value and its hash code along with the name of the application domain in which the method is executing. - -:::code language="csharp" source="~/snippets/csharp/System/String/GetHashCode/perdomain.cs" id="Snippet2"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/GetHashCode/perdomain.fs" id="Snippet2"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.GetHashCode/VB/perdomain.vb" id="Snippet2"::: - -When you run the example without supplying a configuration file, it displays output similar to the following. Note that the hash codes for the string are identical in the two application domains. - -``` -String 'This is a string.' in domain 'PerDomain.exe': 941BCEAC -String 'This is a string.' in domain 'NewDomain': 941BCEAC -``` - -However, if you add the following configuration file to the example's directory and then run the example, the hash codes for the same string will differ by application domain. - -```xml - - - - - - -``` - -When the configuration file is present, the example displays the following output: - -``` -String 'This is a string.' in domain 'PerDomain.exe': 5435776D -String 'This is a string.' in domain 'NewDomain': 75CC8236 -``` - -> [!IMPORTANT] -> Hash codes are used to insert and retrieve keyed objects from hash tables efficiently. However, hash codes don't uniquely identify strings. Identical strings have equal hash codes, but the common language runtime can also assign the same hash code to different strings. In addition, hash codes can vary by version of .NET, by platform within a single version, and by application domain. Because of this, you should not serialize or persist hash code values, nor should you use them as keys in a hash table or dictionary. - -For additional information about the use of hash codes and the `GetHashCode` method, see . - -## Examples -The following example demonstrates the method using various input strings. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.GetHashCode/CPP/gethashcode.cpp" id="Snippet1"::: -:::code language="csharp" source="~/snippets/csharp/System/String/GetHashCode/gethashcode.cs" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/GetHashCode/gethashcode.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.GetHashCode/VB/gethashcode.vb" id="Snippet1"::: - + is dependent on its implementation, which might change from one version of the common language runtime to another. A reason why this might happen is to improve the performance of . + +> [!IMPORTANT] +> If two string objects are equal, the method returns identical values. However, there is not a unique hash code value for each unique string value. Different strings can return the same hash code. +> +> The hash code itself is not guaranteed to be stable. Hash codes for identical strings can differ across .NET implementations, across .NET versions, and across .NET platforms (such as 32-bit and 64-bit) for a single version of .NET. In some cases, they can even differ by application domain. This implies that two subsequent runs of the same program may return different hash codes. +> +> As a result, hash codes should never be used outside of the application domain in which they were created, they should never be used as key fields in a collection, and they should never be persisted. +> +> Finally, don't use the hash code instead of a value returned by a cryptographic hashing function if you need a cryptographically strong hash. For cryptographic hashes, use a class derived from the or class. +> +> For more information about hash codes, see . + +In .NET Framework desktop apps, you can use the [\ element](/dotnet/framework/configure-apps/file-schema/runtime/userandomizedstringhashalgorithm-element) to generate unique hash codes on a per-application domain basis. This can reduce the number of collisions and improve the overall performance of insertions and lookups that use hash tables. The following example shows how to use the [\ element](/dotnet/framework/configure-apps/file-schema/runtime/userandomizedstringhashalgorithm-element). It defines a `DisplayString` class that includes a private string constant, `s`, whose value is "This is a string." It also includes a `ShowStringHashCode` method that displays the string value and its hash code along with the name of the application domain in which the method is executing. + +:::code language="csharp" source="~/snippets/csharp/System/String/GetHashCode/perdomain.cs" id="Snippet2"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/GetHashCode/perdomain.fs" id="Snippet2"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.GetHashCode/VB/perdomain.vb" id="Snippet2"::: + +When you run the example without supplying a configuration file, it displays output similar to the following. Note that the hash codes for the string are identical in the two application domains. + +``` +String 'This is a string.' in domain 'PerDomain.exe': 941BCEAC +String 'This is a string.' in domain 'NewDomain': 941BCEAC +``` + +However, if you add the following configuration file to the example's directory and then run the example, the hash codes for the same string will differ by application domain. + +```xml + + + + + + +``` + +When the configuration file is present, the example displays the following output: + +``` +String 'This is a string.' in domain 'PerDomain.exe': 5435776D +String 'This is a string.' in domain 'NewDomain': 75CC8236 +``` + +> [!IMPORTANT] +> Hash codes are used to insert and retrieve keyed objects from hash tables efficiently. However, hash codes don't uniquely identify strings. Identical strings have equal hash codes, but the common language runtime can also assign the same hash code to different strings. In addition, hash codes can vary by version of .NET, by platform within a single version, and by application domain. Because of this, you should not serialize or persist hash code values, nor should you use them as keys in a hash table or dictionary. + +For additional information about the use of hash codes and the `GetHashCode` method, see . + +## Examples +The following example demonstrates the method using various input strings. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.GetHashCode/CPP/gethashcode.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/GetHashCode/gethashcode.cs" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/GetHashCode/gethashcode.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.GetHashCode/VB/gethashcode.vb" id="Snippet1"::: + ]]> @@ -6755,17 +6755,17 @@ The following example demonstrates the metho - Returns a reference to the element of the string at index zero. - + Returns a reference to the element of the string at index zero. + This method is intended to support .NET compilers and is not intended to be called by user code. A reference to the first character in the string, or a reference to the string's null terminator if the string is empty. - in memory. It is required to support the use of a within a fixed statement. - + in memory. It is required to support the use of a within a fixed statement. + ]]> The string is null. @@ -6819,16 +6819,16 @@ The `GetPinnableReference` method returns a character that can be used for pinni Returns the for the class. The enumerated constant, . - enumerated constant for the type. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.gettypecode/CPP/gtc.cpp" id="Snippet1"::: -:::code language="csharp" source="~/snippets/csharp/System/String/GetTypeCode/gtc.cs" interactive="try-dotnet" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/GetTypeCode/gtc.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.gettypecode/VB/gtc.vb" id="Snippet1"::: - + enumerated constant for the type. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.gettypecode/CPP/gtc.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/GetTypeCode/gtc.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/GetTypeCode/gtc.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.gettypecode/VB/gtc.vb" id="Snippet1"::: + ]]> @@ -6898,21 +6898,21 @@ The following example displays the enumerated constant fo Reports the zero-based index of the first occurrence of the specified Unicode character in this string. The zero-based index position of if that character is found, or -1 if it is not. - method, where a Unicode scalar value representing a precomposed character, such as the ligature "Æ" (U+00C6), might be considered equivalent to any occurrence of the character's components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. - -## Examples -The following example demonstrates how you can search a for a character using the method. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.IndexOf/CPP/indexof_c.cpp" id="Snippet5"::: -:::code language="csharp" source="~/snippets/csharp/System/String/IndexOf/indexof_c.cs" interactive="try-dotnet-method" id="Snippet5"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/IndexOf/indexof_c.fs" id="Snippet5"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.IndexOf/VB/indexof_c.vb" id="Snippet5"::: - + method, where a Unicode scalar value representing a precomposed character, such as the ligature "Æ" (U+00C6), might be considered equivalent to any occurrence of the character's components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. + +## Examples +The following example demonstrates how you can search a for a character using the method. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.IndexOf/CPP/indexof_c.cpp" id="Snippet5"::: +:::code language="csharp" source="~/snippets/csharp/System/String/IndexOf/indexof_c.cs" interactive="try-dotnet-method" id="Snippet5"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/IndexOf/indexof_c.fs" id="Snippet5"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.IndexOf/VB/indexof_c.vb" id="Snippet5"::: + ]]> @@ -6967,34 +6967,34 @@ The following example demonstrates how you can search a for Reports the zero-based index of the first occurrence of the specified string in this instance. The zero-based index position of if that string is found, or -1 if it is not. If is , the return value is 0. - method always returns 0 (zero) to indicate that the match is found at the beginning of the current instance. In the following example, the method is used to find three substrings (a soft hyphen (U+00AD), a soft hyphen followed by "n", and a soft hyphen followed by "m") in two strings. Only one of the strings contains a soft hyphen. If the example is run on the .NET Framework 4 or later, in each case, because the soft hyphen is an ignorable character, the result is the same as if the soft hyphen had not been included in `value`. When searching for a soft hyphen only, the method returns 0 (zero) to indicate that it has found a match at the beginning of the string. - -:::code language="csharp" source="~/snippets/csharp/System/String/IndexOf/ignorable21.cs" id="Snippet21"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/IndexOf/ignorable21.fs" id="Snippet21"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.IndexOf/VB/ignorable21.vb" id="Snippet21"::: - -## Examples -The following example searches for the "n" in "animal". Because string indexes begin at zero rather than one, the method indicates that the "n" is at position 1. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.IndexOf/CPP/simple1.cpp" id="Snippet12"::: -:::code language="csharp" source="~/snippets/csharp/System/String/IndexOf/simple1.cs" interactive="try-dotnet-method" id="Snippet12"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/IndexOf/simple1.fs" id="Snippet12"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.IndexOf/VB/simple1.vb" id="Snippet12"::: - -The following example uses the method to determine the starting position of an animal name in a sentence. It then uses this position to insert an adjective that describes the animal into the sentence. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringinsert/CPP/stringinsert.cpp" id="Snippet1"::: -:::code language="csharp" source="~/snippets/csharp/System/String/IndexOf/stringinsert.cs" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/IndexOf/stringinsert.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringinsert/VB/stringinsert.vb" id="Snippet1"::: - + method always returns 0 (zero) to indicate that the match is found at the beginning of the current instance. In the following example, the method is used to find three substrings (a soft hyphen (U+00AD), a soft hyphen followed by "n", and a soft hyphen followed by "m") in two strings. Only one of the strings contains a soft hyphen. If the example is run on the .NET Framework 4 or later, in each case, because the soft hyphen is an ignorable character, the result is the same as if the soft hyphen had not been included in `value`. When searching for a soft hyphen only, the method returns 0 (zero) to indicate that it has found a match at the beginning of the string. + +:::code language="csharp" source="~/snippets/csharp/System/String/IndexOf/ignorable21.cs" id="Snippet21"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/IndexOf/ignorable21.fs" id="Snippet21"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.IndexOf/VB/ignorable21.vb" id="Snippet21"::: + +## Examples +The following example searches for the "n" in "animal". Because string indexes begin at zero rather than one, the method indicates that the "n" is at position 1. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.IndexOf/CPP/simple1.cpp" id="Snippet12"::: +:::code language="csharp" source="~/snippets/csharp/System/String/IndexOf/simple1.cs" interactive="try-dotnet-method" id="Snippet12"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/IndexOf/simple1.fs" id="Snippet12"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.IndexOf/VB/simple1.vb" id="Snippet12"::: + +The following example uses the method to determine the starting position of an animal name in a sentence. It then uses this position to insert an adjective that describes the animal into the sentence. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringinsert/CPP/stringinsert.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/IndexOf/stringinsert.cs" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/IndexOf/stringinsert.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringinsert/VB/stringinsert.vb" id="Snippet1"::: + ]]> @@ -7063,23 +7063,23 @@ The following example uses the method to determi Reports the zero-based index of the first occurrence of the specified Unicode character in this string. The search starts at a specified character position. The zero-based index position of from the start of the string if that character is found, or -1 if it is not. - method, where a Unicode scalar value representing a precomposed character, such as the ligature "Æ" (U+00C6), might be considered equivalent to any occurrence of the character's components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. - -## Examples -The following example demonstrates the method. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.indexof1/CPP/ixof1.cpp" id="Snippet1"::: -:::code language="csharp" source="~/snippets/csharp/System/String/IndexOf/ixof1.cs" interactive="try-dotnet-method" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/IndexOf/ixof1.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.indexof1/VB/ixof1.vb" id="Snippet1"::: - + method, where a Unicode scalar value representing a precomposed character, such as the ligature "Æ" (U+00C6), might be considered equivalent to any occurrence of the character's components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. + +## Examples +The following example demonstrates the method. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.indexof1/CPP/ixof1.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/IndexOf/ixof1.cs" interactive="try-dotnet-method" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/IndexOf/ixof1.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.indexof1/VB/ixof1.vb" id="Snippet1"::: + ]]> @@ -7129,14 +7129,14 @@ The following example demonstrates the method. Reports the zero-based index of the first occurrence of the specified Unicode character in this string. A parameter specifies the type of search to use for the specified character. The zero-based index of if that character is found, or -1 if it is not. - enumeration member that specifies whether the search for the `value` argument uses the current or invariant culture, is case-sensitive or case-insensitive, or uses word or ordinal comparison rules. - + enumeration member that specifies whether the search for the `value` argument uses the current or invariant culture, is case-sensitive or case-insensitive, or uses word or ordinal comparison rules. + ]]> @@ -7191,27 +7191,27 @@ The `comparisonType` parameter is a enumeration m Reports the zero-based index of the first occurrence of the specified string in this instance. The search starts at a specified character position. The zero-based index position of from the start of the current instance if that string is found, or -1 if it is not. If is , the return value is . - method always returns `startIndex`, which is the character position at which the search begins. In the following example, the method is used to find the position of a soft hyphen (U+00AD) followed by an "m" in two strings. Only one of the strings contains the required substring. If the example is run on the .NET Framework 4 or later, in both cases, because the soft hyphen is an ignorable character, the method returns the index of "m" in the string. Note that in the case of the first string, which includes the soft hyphen followed by an "m", the method fails to return the index of the soft hyphen but instead returns the index of the "m". - -:::code language="csharp" source="~/snippets/csharp/System/String/IndexOf/ignorable22.cs" id="Snippet22"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/IndexOf/ignorable22.fs" id="Snippet22"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.IndexOf/VB/ignorable22.vb" id="Snippet22"::: - -## Examples -The following example searches for all occurrences of a specified string within a target string. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringindexof4/CPP/stringindexof4.cpp" id="Snippet1"::: -:::code language="csharp" source="~/snippets/csharp/System/String/IndexOf/stringindexof4.cs" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/IndexOf/stringindexof4.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringindexof4/VB/stringindexof4.vb" id="Snippet1"::: - + method always returns `startIndex`, which is the character position at which the search begins. In the following example, the method is used to find the position of a soft hyphen (U+00AD) followed by an "m" in two strings. Only one of the strings contains the required substring. If the example is run on the .NET Framework 4 or later, in both cases, because the soft hyphen is an ignorable character, the method returns the index of "m" in the string. Note that in the case of the first string, which includes the soft hyphen followed by an "m", the method fails to return the index of the soft hyphen but instead returns the index of the "m". + +:::code language="csharp" source="~/snippets/csharp/System/String/IndexOf/ignorable22.cs" id="Snippet22"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/IndexOf/ignorable22.fs" id="Snippet22"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.IndexOf/VB/ignorable22.vb" id="Snippet22"::: + +## Examples +The following example searches for all occurrences of a specified string within a target string. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringindexof4/CPP/stringindexof4.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/IndexOf/stringindexof4.cs" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/IndexOf/stringindexof4.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringindexof4/VB/stringindexof4.vb" id="Snippet1"::: + ]]> @@ -7285,20 +7285,20 @@ The following example searches for all occurrences of a specified string within Reports the zero-based index of the first occurrence of the specified string in the current object. A parameter specifies the type of search to use for the specified string. The index position of the parameter if that string is found, or -1 if it is not. If is , the return value is 0. - method that find the first occurrence of a string within another string using different values of the enumeration. - -:::code language="csharp" source="~/snippets/csharp/System/String/IndexOf/iocmp.cs" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/IndexOf/iocmp.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.IndexOfCmp/vb/iocmp.vb" id="Snippet1"::: - + method that find the first occurrence of a string within another string using different values of the enumeration. + +:::code language="csharp" source="~/snippets/csharp/System/String/IndexOf/iocmp.cs" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/IndexOf/iocmp.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.IndexOfCmp/vb/iocmp.vb" id="Snippet1"::: + ]]> @@ -7306,12 +7306,12 @@ The following example demonstrates three overloads of the is not a valid value. - Character sets include ignorable characters, which are characters that are not considered when performing a linguistic or culture-sensitive comparison. In a culture-sensitive search (that is, if is not or ), if contains an ignorable character, the result is equivalent to searching with that character removed. If consists only of one or more ignorable characters, the method always returns 0 (zero) to indicate that the match is found at the beginning of the current instance. - -In the following example, the method is used to find three substrings (a soft hyphen (U+00AD), a soft hyphen followed by "n", and a soft hyphen followed by "m") in two strings. Only one of the strings contains a soft hyphen. If the example is run on the .NET Framework 4 or later, because the soft hyphen is an ignorable character, a culture-sensitive search returns the same value that it would return if the soft hyphen were not included in the search string. An ordinal search, however, successfully finds the soft hyphen in one string and reports that it is absent from the second string. - -:::code language="csharp" source="~/snippets/csharp/System/String/IndexOf/ignorable26.cs" id="Snippet26"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/IndexOf/ignorable26.fs" id="Snippet26"::: + Character sets include ignorable characters, which are characters that are not considered when performing a linguistic or culture-sensitive comparison. In a culture-sensitive search (that is, if is not or ), if contains an ignorable character, the result is equivalent to searching with that character removed. If consists only of one or more ignorable characters, the method always returns 0 (zero) to indicate that the match is found at the beginning of the current instance. + +In the following example, the method is used to find three substrings (a soft hyphen (U+00AD), a soft hyphen followed by "n", and a soft hyphen followed by "m") in two strings. Only one of the strings contains a soft hyphen. If the example is run on the .NET Framework 4 or later, because the soft hyphen is an ignorable character, a culture-sensitive search returns the same value that it would return if the soft hyphen were not included in the search string. An ordinal search, however, successfully finds the soft hyphen in one string and reports that it is absent from the second string. + +:::code language="csharp" source="~/snippets/csharp/System/String/IndexOf/ignorable26.cs" id="Snippet26"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/IndexOf/ignorable26.fs" id="Snippet26"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.IndexOf/VB/ignorable26.vb" id="Snippet26"::: @@ -7372,34 +7372,34 @@ In the following example, the from the start of the string if that character is found, or -1 if it is not. - method, where a Unicode scalar value representing a precomposed character, such as the ligature "Æ" (U+00C6), might be considered equivalent to any occurrence of the character's components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. - -## Examples -The following example demonstrates the method. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.IndexOf/CPP/indexofcii.cpp" id="Snippet1"::: -:::code language="csharp" source="~/snippets/csharp/System/String/IndexOf/indexofcii.cs" interactive="try-dotnet" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/IndexOf/indexofcii.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.IndexOf/VB/indexofcii.vb" id="Snippet1"::: - + method, where a Unicode scalar value representing a precomposed character, such as the ligature "Æ" (U+00C6), might be considered equivalent to any occurrence of the character's components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. + +## Examples +The following example demonstrates the method. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.IndexOf/CPP/indexofcii.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/IndexOf/indexofcii.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/IndexOf/indexofcii.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.IndexOf/VB/indexofcii.vb" id="Snippet1"::: + ]]> - or is negative. - --or- - - is greater than the length of this string. - --or- - + or is negative. + +-or- + + is greater than the length of this string. + +-or- + is greater than the length of this string minus . @@ -7458,40 +7458,40 @@ The following example demonstrates the method. Reports the zero-based index of the first occurrence of the specified string in this instance. The search starts at a specified character position and examines a specified number of character positions. The zero-based index position of from the start of the current instance if that string is found, or -1 if it is not. If is , the return value is . - method always returns `startIndex`, which is the character position at which the search begins. In the following example, the method is used to find the position of a soft hyphen (U+00AD) followed by an "m" starting in the third through sixth character positions in two strings. Only one of the strings contains the required substring. If the example is run on the .NET Framework 4 or later, in both cases, because the soft hyphen is an ignorable character, the method returns the index of "m" in the string when it performs a culture-sensitive comparison. Note that in the case of the first string, which includes the soft hyphen followed by an "m", the method fails to return the index of the soft hyphen but instead returns the index of the "m". - -:::code language="csharp" source="~/snippets/csharp/System/String/IndexOf/ignorable23.cs" id="Snippet23"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/IndexOf/ignorable23.fs" id="Snippet23"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.IndexOf/VB/ignorable23.vb" id="Snippet23"::: - -## Examples -The following example finds the index of all occurrences of the string "he" within a substring of another string. Note that the number of characters to be searched must be recalculated for each search iteration. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.indexof8/CPP/ixof8.cpp" id="Snippet1"::: -:::code language="csharp" source="~/snippets/csharp/System/String/IndexOf/ixof8.cs" interactive="try-dotnet-method" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/IndexOf/ixof8.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.indexof8/VB/ixof8.vb" id="Snippet1"::: - + method always returns `startIndex`, which is the character position at which the search begins. In the following example, the method is used to find the position of a soft hyphen (U+00AD) followed by an "m" starting in the third through sixth character positions in two strings. Only one of the strings contains the required substring. If the example is run on the .NET Framework 4 or later, in both cases, because the soft hyphen is an ignorable character, the method returns the index of "m" in the string when it performs a culture-sensitive comparison. Note that in the case of the first string, which includes the soft hyphen followed by an "m", the method fails to return the index of the soft hyphen but instead returns the index of the "m". + +:::code language="csharp" source="~/snippets/csharp/System/String/IndexOf/ignorable23.cs" id="Snippet23"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/IndexOf/ignorable23.fs" id="Snippet23"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.IndexOf/VB/ignorable23.vb" id="Snippet23"::: + +## Examples +The following example finds the index of all occurrences of the string "he" within a substring of another string. Note that the number of characters to be searched must be recalculated for each search iteration. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.indexof8/CPP/ixof8.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/IndexOf/ixof8.cs" interactive="try-dotnet-method" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/IndexOf/ixof8.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.indexof8/VB/ixof8.vb" id="Snippet1"::: + ]]> is . - or is negative. - --or- - - is greater than the length of this string. - --or- - + or is negative. + +-or- + + is greater than the length of this string. + +-or- + is greater than the length of this string minus . As explained in [Best Practices for Using Strings](/dotnet/standard/base-types/best-practices-strings), we recommend that you avoid calling string comparison methods that substitute default values and instead call methods that require parameters to be explicitly specified. To use the comparison rules of the current culture to perform this operation, signal your intention explicitly by calling the method overload with a value of for its `comparisonType` parameter. If you don't need linguistic-aware comparison, consider using . @@ -7558,20 +7558,20 @@ The following example finds the index of all occurrences of the string "he" with Reports the zero-based index of the first occurrence of the specified string in the current object. Parameters specify the starting search position in the current string and the type of search to use for the specified string. The zero-based index position of the parameter from the start of the current instance if that string is found, or -1 if it is not. If is , the return value is . - method that find the first occurrence of a string within another string using different values of the enumeration. - -:::code language="csharp" source="~/snippets/csharp/System/String/IndexOf/iocmp.cs" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/IndexOf/iocmp.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.IndexOfCmp/vb/iocmp.vb" id="Snippet1"::: - + method that find the first occurrence of a string within another string using different values of the enumeration. + +:::code language="csharp" source="~/snippets/csharp/System/String/IndexOf/iocmp.cs" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/IndexOf/iocmp.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.IndexOfCmp/vb/iocmp.vb" id="Snippet1"::: + ]]> @@ -7581,12 +7581,12 @@ The following example demonstrates three overloads of the is not a valid value. - Character sets include ignorable characters, which are characters that are not considered when performing a linguistic or culture-sensitive comparison. In a culture-sensitive search (that is, if is not or ), if contains an ignorable character, the result is equivalent to searching with that character removed. If consists only of one or more ignorable characters, the method always returns , which is the character position at which the search begins. - -In the following example, the method is used to find the position of a soft hyphen (U+00AD) followed by an "m" starting with the third character position in two strings. Only one of the strings contains the required substring. If the example is run on the .NET Framework 4 or later, in both cases, because the soft hyphen is an ignorable character, the method returns the index of "m" in the string when it performs a culture-sensitive comparison. Note that in the case of the first string, which includes the soft hyphen followed by an "m", the method fails to return the index of the soft hyphen but instead returns the index of the "m". The method returns the index of the soft hyphen in the first string only when it performs an ordinal comparison. - -:::code language="csharp" source="~/snippets/csharp/System/String/IndexOf/ignorable25.cs" id="Snippet25"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/IndexOf/ignorable25.fs" id="Snippet25"::: + Character sets include ignorable characters, which are characters that are not considered when performing a linguistic or culture-sensitive comparison. In a culture-sensitive search (that is, if is not or ), if contains an ignorable character, the result is equivalent to searching with that character removed. If consists only of one or more ignorable characters, the method always returns , which is the character position at which the search begins. + +In the following example, the method is used to find the position of a soft hyphen (U+00AD) followed by an "m" starting with the third character position in two strings. Only one of the strings contains the required substring. If the example is run on the .NET Framework 4 or later, in both cases, because the soft hyphen is an ignorable character, the method returns the index of "m" in the string when it performs a culture-sensitive comparison. Note that in the case of the first string, which includes the soft hyphen followed by an "m", the method fails to return the index of the soft hyphen but instead returns the index of the "m". The method returns the index of the soft hyphen in the first string only when it performs an ordinal comparison. + +:::code language="csharp" source="~/snippets/csharp/System/String/IndexOf/ignorable25.cs" id="Snippet25"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/IndexOf/ignorable25.fs" id="Snippet25"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.IndexOf/VB/ignorable25.vb" id="Snippet25"::: @@ -7648,45 +7648,45 @@ In the following example, the object. Parameters specify the starting search position in the current string, the number of characters in the current string to search, and the type of search to use for the specified string. The zero-based index position of the parameter from the start of the current instance if that string is found, or -1 if it is not. If is , the return value is . - method that find the first occurrence of a string within another string using different values of the enumeration. - -:::code language="csharp" source="~/snippets/csharp/System/String/IndexOf/iocmp.cs" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/IndexOf/iocmp.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.IndexOfCmp/vb/iocmp.vb" id="Snippet1"::: - + method that find the first occurrence of a string within another string using different values of the enumeration. + +:::code language="csharp" source="~/snippets/csharp/System/String/IndexOf/iocmp.cs" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/IndexOf/iocmp.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.IndexOfCmp/vb/iocmp.vb" id="Snippet1"::: + ]]> is . - or is negative. - --or- - - is greater than the length of this instance. - --or- - + or is negative. + +-or- + + is greater than the length of this instance. + +-or- + is greater than the length of this string minus . is not a valid value. - Character sets include ignorable characters, which are characters that are not considered when performing a linguistic or culture-sensitive comparison. In a culture-sensitive search (that is, if is not or ), if contains an ignorable character, the result is equivalent to searching with that character removed. If consists only of one or more ignorable characters, the method always returns , which is the character position at which the search begins. - -In the following example, the method is used to find the position of a soft hyphen (U+00AD) followed by an "m" starting in the third through sixth character positions in two strings. Only one of the strings contains the required substring. If the example is run on the .NET Framework 4 or later, in both cases, because the soft hyphen is an ignorable character, the method returns the index of "m" in the string when it performs a culture-sensitive comparison. When it performs an ordinal comparison, however, it finds the substring only in the first string. Note that in the case of the first string, which includes the soft hyphen followed by an "m", the method fails to return the index of the soft hyphen but instead returns the index of the "m" when it performs a culture-sensitive comparison. The method returns the index of the soft hyphen in the first string only when it performs an ordinal comparison. - -:::code language="csharp" source="~/snippets/csharp/System/String/IndexOf/ignorable24.cs" id="Snippet24"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/IndexOf/ignorable24.fs" id="Snippet24"::: + Character sets include ignorable characters, which are characters that are not considered when performing a linguistic or culture-sensitive comparison. In a culture-sensitive search (that is, if is not or ), if contains an ignorable character, the result is equivalent to searching with that character removed. If consists only of one or more ignorable characters, the method always returns , which is the character position at which the search begins. + +In the following example, the method is used to find the position of a soft hyphen (U+00AD) followed by an "m" starting in the third through sixth character positions in two strings. Only one of the strings contains the required substring. If the example is run on the .NET Framework 4 or later, in both cases, because the soft hyphen is an ignorable character, the method returns the index of "m" in the string when it performs a culture-sensitive comparison. When it performs an ordinal comparison, however, it finds the substring only in the first string. Note that in the case of the first string, which includes the soft hyphen followed by an "m", the method fails to return the index of the soft hyphen but instead returns the index of the "m" when it performs a culture-sensitive comparison. The method returns the index of the soft hyphen in the first string only when it performs an ordinal comparison. + +:::code language="csharp" source="~/snippets/csharp/System/String/IndexOf/ignorable24.cs" id="Snippet24"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/IndexOf/ignorable24.fs" id="Snippet24"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.IndexOf/VB/ignorable24.vb" id="Snippet24"::: @@ -7756,22 +7756,22 @@ In the following example, the was found; -1 if no character in was found. - method, where a Unicode scalar value representing a precomposed character, such as the ligature "Æ" (U+00C6), might be considered equivalent to any occurrence of the character's components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. - -## Examples -The following example finds the first vowel in a string. - -:::code language="csharp" source="~/snippets/csharp/System/String/IndexOfAny/IndexOfAny1.cs" interactive="try-dotnet" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/IndexOfAny/IndexOfAny1.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/System.String.IndexOfAny/vb/IndexOfAny1.vb" id="Snippet1"::: - + method, where a Unicode scalar value representing a precomposed character, such as the ligature "Æ" (U+00C6), might be considered equivalent to any occurrence of the character's components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. + +## Examples +The following example finds the first vowel in a string. + +:::code language="csharp" source="~/snippets/csharp/System/String/IndexOfAny/IndexOfAny1.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/IndexOfAny/IndexOfAny1.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/System.String.IndexOfAny/vb/IndexOfAny1.vb" id="Snippet1"::: + ]]> @@ -7835,34 +7835,34 @@ The following example finds the first vowel in a string. Reports the zero-based index of the first occurrence in this instance of any character in a specified array of Unicode characters. The search starts at a specified character position. The zero-based index position of the first occurrence in this instance where any character in was found; -1 if no character in was found. - method, where a Unicode scalar value representing a precomposed character, such as the ligature "Æ" (U+00C6), might be considered equivalent to any occurrence of the character's components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. - -## Examples -The following example finds the index of the occurrence of any character of the string "is" within a substring of another string. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.indexofany2/CPP/ixany2.cpp" id="Snippet1"::: -:::code language="csharp" source="~/snippets/csharp/System/String/IndexOfAny/ixany2.cs" interactive="try-dotnet" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/IndexOfAny/ixany2.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.indexofany2/VB/ixany2.vb" id="Snippet1"::: - + method, where a Unicode scalar value representing a precomposed character, such as the ligature "Æ" (U+00C6), might be considered equivalent to any occurrence of the character's components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. + +## Examples +The following example finds the index of the occurrence of any character of the string "is" within a substring of another string. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.indexofany2/CPP/ixany2.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/IndexOfAny/ixany2.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/IndexOfAny/ixany2.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.indexofany2/VB/ixany2.vb" id="Snippet1"::: + ]]> is . - is negative. - --or- - + is negative. + +-or- + is greater than the number of characters in this instance. @@ -7928,34 +7928,34 @@ The following example finds the index of the occurrence of any character of the Reports the zero-based index of the first occurrence in this instance of any character in a specified array of Unicode characters. The search starts at a specified character position and examines a specified number of character positions. The zero-based index position of the first occurrence in this instance where any character in was found; -1 if no character in was found. - method, where a Unicode scalar value representing a precomposed character, such as the ligature "Æ" (U+00C6), might be considered equivalent to any occurrence of the character's components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. - -## Examples -The following example finds the index of the occurrence of any character of the string "aid" within a substring of another string. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.indexofany3/CPP/ixany3.cpp" id="Snippet1"::: -:::code language="csharp" source="~/snippets/csharp/System/String/IndexOfAny/ixany3.cs" interactive="try-dotnet" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/IndexOfAny/ixany3.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.indexofany3/VB/ixany3.vb" id="Snippet1"::: - + method, where a Unicode scalar value representing a precomposed character, such as the ligature "Æ" (U+00C6), might be considered equivalent to any occurrence of the character's components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. + +## Examples +The following example finds the index of the occurrence of any character of the string "aid" within a substring of another string. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.indexofany3/CPP/ixany3.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/IndexOfAny/ixany3.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/IndexOfAny/ixany3.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.indexofany3/VB/ixany3.vb" id="Snippet1"::: + ]]> is . - or is negative. - --or- - + or is negative. + +-or- + + is greater than the number of characters in this instance. @@ -8019,30 +8019,30 @@ The following example finds the index of the occurrence of any character of the Returns a new string in which a specified string is inserted at a specified index position in this instance. A new string that is equivalent to this instance, but with inserted at position . - [!NOTE] -> This method does not modify the value of the current instance. Instead, it returns a new string in which `value` is inserted into the current instance. - -For example, the return value of `"abc".Insert(2, "XYZ")` is "abXYZc". - -## Examples -The following example inserts a space character in the fourth character position (the character at index 3) of a string. - -:::code language="csharp" source="~/snippets/csharp/System/String/Insert/Insert1.cs" interactive="try-dotnet" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Insert/Insert1.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/System.String.Insert/vb/Insert1.vb" id="Snippet1"::: - -The following console application prompts the users to enter one or more adjectives to describe two animals. It then calls the method to insert the text entered by the user into a string. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringinsert/CPP/stringinsert.cpp" id="Snippet1"::: -:::code language="csharp" source="~/snippets/csharp/System/String/IndexOf/stringinsert.cs" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/IndexOf/stringinsert.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringinsert/VB/stringinsert.vb" id="Snippet1"::: - + [!NOTE] +> This method does not modify the value of the current instance. Instead, it returns a new string in which `value` is inserted into the current instance. + +For example, the return value of `"abc".Insert(2, "XYZ")` is "abXYZc". + +## Examples +The following example inserts a space character in the fourth character position (the character at index 3) of a string. + +:::code language="csharp" source="~/snippets/csharp/System/String/Insert/Insert1.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Insert/Insert1.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/System.String.Insert/vb/Insert1.vb" id="Snippet1"::: + +The following console application prompts the users to enter one or more adjectives to describe two animals. It then calls the method to insert the text entered by the user into a string. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringinsert/CPP/stringinsert.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/IndexOf/stringinsert.cs" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/IndexOf/stringinsert.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringinsert/VB/stringinsert.vb" id="Snippet1"::: + ]]> @@ -8106,7 +8106,7 @@ The following console application prompts the users to enter one or more adjecti System.String - + A string to search for in the intern pool. @@ -8114,13 +8114,13 @@ The following console application prompts the users to enter one or more adjecti The system's reference to , if it is interned; otherwise, a new reference to a string with the value of . For more information about this API, see Supplemental API remarks for String.Intern. - @@ -8170,41 +8170,41 @@ The following example uses three strings that are equal in value to determine wh System.String - + The string to search for in the intern pool. Retrieves a reference to a specified . A reference to if it is in the common language runtime intern pool; otherwise, . - you add programmatically by calling the method. - -The intern pool conserves string storage. If you assign a literal string constant to several variables, each variable is set to reference the same constant in the intern pool instead of referencing several different instances of that have identical values. - -This method looks up `str` in the intern pool. If `str` has already been interned, a reference to that instance is returned; otherwise, `null` is returned. - -Compare this method to the method. - -This method does not return a Boolean value. If you call the method because you want a Boolean value that indicates whether a particular string is interned, you can use code such as the following. - -:::code language="csharp" source="~/snippets/csharp/System/String/IsInterned/isinternedex1.cs" interactive="try-dotnet" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/IsInterned/isinternedex1.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.isinterned/vb/isinternedex1.vb" id="Snippet1"::: - -> [!NOTE] -> You can override the use of the intern pool when you use [Ngen.exe (Native Image Generator)](/dotnet/framework/tools/ngen-exe-native-image-generator) to install an assembly to the native image cache on a local computer. For more information, see Performance Considerations in the Remarks section for the property. - -## Examples -The following example demonstrates that literal strings are interned automatically by the compiler. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.isinterned/CPP/isin.cpp" id="Snippet1"::: -:::code language="csharp" source="~/snippets/csharp/System/String/IsInterned/isin.cs" interactive="try-dotnet" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/IsInterned/isin.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.isinterned/VB/isin.vb" id="Snippet1"::: - + you add programmatically by calling the method. + +The intern pool conserves string storage. If you assign a literal string constant to several variables, each variable is set to reference the same constant in the intern pool instead of referencing several different instances of that have identical values. + +This method looks up `str` in the intern pool. If `str` has already been interned, a reference to that instance is returned; otherwise, `null` is returned. + +Compare this method to the method. + +This method does not return a Boolean value. If you call the method because you want a Boolean value that indicates whether a particular string is interned, you can use code such as the following. + +:::code language="csharp" source="~/snippets/csharp/System/String/IsInterned/isinternedex1.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/IsInterned/isinternedex1.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.isinterned/vb/isinternedex1.vb" id="Snippet1"::: + +> [!NOTE] +> You can override the use of the intern pool when you use [Ngen.exe (Native Image Generator)](/dotnet/framework/tools/ngen-exe-native-image-generator) to install an assembly to the native image cache on a local computer. For more information, see Performance Considerations in the Remarks section for the property. + +## Examples +The following example demonstrates that literal strings are interned automatically by the compiler. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.isinterned/CPP/isin.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/IsInterned/isin.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/IsInterned/isin.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.isinterned/VB/isin.vb" id="Snippet1"::: + ]]> @@ -8221,16 +8221,16 @@ The following example demonstrates that literal strings are interned automatical Indicates whether this string is in a particular Unicode normalization form. - @@ -8274,15 +8274,15 @@ The following example determines whether a string is successfully normalized to if this string is in normalization form C; otherwise, . - . - + . + ]]> The current instance contains invalid Unicode characters. @@ -8332,7 +8332,7 @@ For a description of supported Unicode normalization forms, see System.Boolean - + A Unicode normalization form. @@ -8340,15 +8340,15 @@ For a description of supported Unicode normalization forms, see if this string is in the normalization form specified by the parameter; otherwise, . - . - + . + ]]> The current instance contains invalid Unicode characters. @@ -8423,13 +8423,13 @@ For a description of supported Unicode normalization forms, see if the parameter is or an empty string (""); otherwise, . For more information about this API, see Supplemental API remarks for String.IsNullOrEmpty. - @@ -8494,24 +8494,24 @@ The following example examines three strings and determines whether each string if the parameter is or , or if consists exclusively of white-space characters. - is a convenience method that is similar to the following code, except that it offers superior performance: - -:::code language="csharp" source="~/snippets/csharp/System/String/IsNullOrWhiteSpace/isnullorwhitespace.cs" id="Snippet2"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/IsNullOrWhiteSpace/isnullorwhitespace.fs" id="Snippet2"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.isnullorwhitespace/vb/isnullorwhitespace.vb" id="Snippet2"::: - -White-space characters are defined by the Unicode standard. The method interprets any character that returns a value of `true` when it is passed to the method as a white-space character. - -## Examples -The following example creates a string array, and then passes each element of the array to the method. - -:::code language="csharp" source="~/snippets/csharp/System/String/IsNullOrWhiteSpace/isnullorwhitespace1.cs" interactive="try-dotnet" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/IsNullOrWhiteSpace/isnullorwhitespace1.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.isnullorwhitespace/vb/isnullorwhitespace1.vb" id="Snippet1"::: - + is a convenience method that is similar to the following code, except that it offers superior performance: + +:::code language="csharp" source="~/snippets/csharp/System/String/IsNullOrWhiteSpace/isnullorwhitespace.cs" id="Snippet2"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/IsNullOrWhiteSpace/isnullorwhitespace.fs" id="Snippet2"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.isnullorwhitespace/vb/isnullorwhitespace.vb" id="Snippet2"::: + +White-space characters are defined by the Unicode standard. The method interprets any character that returns a value of `true` when it is passed to the method as a white-space character. + +## Examples +The following example creates a string array, and then passes each element of the array to the method. + +:::code language="csharp" source="~/snippets/csharp/System/String/IsNullOrWhiteSpace/isnullorwhitespace1.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/IsNullOrWhiteSpace/isnullorwhitespace1.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.isnullorwhitespace/vb/isnullorwhitespace1.vb" id="Snippet1"::: + ]]> @@ -8576,10 +8576,10 @@ The following example creates a string array, and then passes each element of th The character to use as a separator. is included in the returned string only if has more than one element. An array of objects whose string representations will be concatenated. Concatenates the string representations of an array of objects, using the specified separator between each member. - A string that consists of the elements of delimited by the character. - --or- - + A string that consists of the elements of delimited by the character. + +-or- + if has zero elements. To be added. @@ -8636,10 +8636,10 @@ The following example creates a string array, and then passes each element of th The character to use as a separator. is included in the returned string only if has more than one element. An array of strings to concatenate. Concatenates an array of strings, using the specified separator between each member. - A string that consists of the elements of delimited by the character. - --or- - + A string that consists of the elements of delimited by the character. + +-or- + if has zero elements. To be added. @@ -8712,30 +8712,30 @@ The following example creates a string array, and then passes each element of th The string to use as a separator. is included in the returned string only if has more than one element. A collection that contains the strings to concatenate. Concatenates the members of a constructed collection of type , using the specified separator between each member. - A string that consists of the elements of delimited by the string. - --or- - + A string that consists of the elements of delimited by the string. + +-or- + if has zero elements. - ) is used instead. If any member of `values` is `null`, an empty string is used instead. - - is a convenience method that lets you concatenate each element in an `IEnumerable(Of String)` collection without first converting the elements to a string array. It is particularly useful with Language-Integrated Query (LINQ) query expressions. The following example passes a `List(Of String)` object that contains either the uppercase or lowercase letters of the alphabet to a lambda expression that selects letters that are equal to or greater than a particular letter (which, in the example, is "M"). The `IEnumerable(Of String)` collection returned by the method is passed to the method to display the result as a single string. - -:::code language="csharp" source="~/snippets/csharp/System/String/Join/join4.cs" interactive="try-dotnet" id="Snippet4"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Join/join4.fs" id="Snippet4"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.join/vb/join4.vb" id="Snippet4"::: - -## Examples -The following example uses the Sieve of Eratosthenes algorithm to calculate the prime numbers that are less than or equal to 100. It assigns the result to a object of type , which it then passes to the method. - -:::code language="csharp" source="~/snippets/csharp/System/String/Join/join3.cs" interactive="try-dotnet" id="Snippet3"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Join/join3.fs" id="Snippet3"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.join/vb/join3.vb" id="Snippet3"::: - + ) is used instead. If any member of `values` is `null`, an empty string is used instead. + + is a convenience method that lets you concatenate each element in an `IEnumerable(Of String)` collection without first converting the elements to a string array. It is particularly useful with Language-Integrated Query (LINQ) query expressions. The following example passes a `List(Of String)` object that contains either the uppercase or lowercase letters of the alphabet to a lambda expression that selects letters that are equal to or greater than a particular letter (which, in the example, is "M"). The `IEnumerable(Of String)` collection returned by the method is passed to the method to display the result as a single string. + +:::code language="csharp" source="~/snippets/csharp/System/String/Join/join4.cs" interactive="try-dotnet" id="Snippet4"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Join/join4.fs" id="Snippet4"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.join/vb/join4.vb" id="Snippet4"::: + +## Examples +The following example uses the Sieve of Eratosthenes algorithm to calculate the prime numbers that are less than or equal to 100. It assigns the result to a object of type , which it then passes to the method. + +:::code language="csharp" source="~/snippets/csharp/System/String/Join/join3.cs" interactive="try-dotnet" id="Snippet3"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Join/join3.fs" id="Snippet3"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.join/vb/join3.vb" id="Snippet3"::: + ]]> @@ -8813,40 +8813,40 @@ The following example uses the Sieve of Eratosthenes algorithm to calculate the The string to use as a separator. is included in the returned string only if has more than one element. An array that contains the elements to concatenate. Concatenates the elements of an object array, using the specified separator between each element. - A string that consists of the elements of delimited by the string. - --or- - - if has zero elements. - --or- - + A string that consists of the elements of delimited by the string. + +-or- + + if has zero elements. + +-or- + .NET Framework only: if the first element of is . - ) is used instead. See the Notes for Callers section if the first element of `values` is `null`. - - is a convenience method that lets you concatenate each element in an object array without explicitly converting its elements to strings. The string representation of each object in the array is derived by calling that object's `ToString` method. - -## Examples -The following example uses the Sieve of Eratosthenes algorithm to calculate the prime numbers that are less than or equal to 100. It assigns the result to a integer array, which it then passes to the method. - -:::code language="csharp" source="~/snippets/csharp/System/String/Join/join1.cs" interactive="try-dotnet" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Join/join1.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.join/vb/join1.vb" id="Snippet1"::: - + ) is used instead. See the Notes for Callers section if the first element of `values` is `null`. + + is a convenience method that lets you concatenate each element in an object array without explicitly converting its elements to strings. The string representation of each object in the array is derived by calling that object's `ToString` method. + +## Examples +The following example uses the Sieve of Eratosthenes algorithm to calculate the prime numbers that are less than or equal to 100. It assigns the result to a integer array, which it then passes to the method. + +:::code language="csharp" source="~/snippets/csharp/System/String/Join/join1.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Join/join1.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.join/vb/join1.vb" id="Snippet1"::: + ]]> is . The length of the resulting string overflows the maximum allowed length (Int32.MaxValue). - .NET Framework only: If the first element of is , the method does not concatenate the elements in but instead returns . A number of workarounds for this issue are available. The easiest is to assign a value of to the first element of the array, as the following example shows. - -:::code language="csharp" source="~/snippets/csharp/System/String/Join/joinfix1.cs" interactive="try-dotnet-method" id="Snippet6"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Join/joinfix1.fs" id="Snippet6"::: + .NET Framework only: If the first element of is , the method does not concatenate the elements in but instead returns . A number of workarounds for this issue are available. The easiest is to assign a value of to the first element of the array, as the following example shows. + +:::code language="csharp" source="~/snippets/csharp/System/String/Join/joinfix1.cs" interactive="try-dotnet-method" id="Snippet6"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Join/joinfix1.fs" id="Snippet6"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.join/vb/joinfix1.vb" id="Snippet6"::: @@ -8920,27 +8920,27 @@ The following example uses the Sieve of Eratosthenes algorithm to calculate the The string to use as a separator. is included in the returned string only if has more than one element. An array that contains the elements to concatenate. Concatenates all the elements of a string array, using the specified separator between each element. - A string that consists of the elements in delimited by the string. - --or- - + A string that consists of the elements in delimited by the string. + +-or- + if has zero elements. - ) is used instead. If any element in `value` is `null`, an empty string is used instead. - -## Examples -The following example demonstrates the method. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringjoin/CPP/stringjoin.cpp" id="Snippet1"::: -:::code language="csharp" source="~/snippets/csharp/System/String/Join/stringjoin.cs" interactive="try-dotnet" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Join/stringjoin.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringjoin/VB/stringjoin.vb" id="Snippet1"::: - + ) is used instead. If any element in `value` is `null`, an empty string is used instead. + +## Examples +The following example demonstrates the method. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringjoin/CPP/stringjoin.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Join/stringjoin.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Join/stringjoin.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringjoin/VB/stringjoin.vb" id="Snippet1"::: + ]]> @@ -8998,19 +8998,19 @@ The following example demonstrates the method. The first item in to concatenate. The number of elements from to concatenate, starting with the element in the position. Concatenates an array of strings, using the specified separator between each member, starting with the element in located at the position, and concatenating up to elements. - A string that consists of elements of starting at delimited by the character. - --or- - + A string that consists of elements of starting at delimited by the character. + +-or- + if is zero. To be added. is . - or are negative. - --or- - + or are negative. + +-or- + is greater than the length of - . The length of the resulting string overflows the maximum allowed length (Int32.MaxValue). @@ -9086,36 +9086,36 @@ The following example demonstrates the method. The first element in to use. The number of elements of to use. Concatenates the specified elements of a string array, using the specified separator between each element. - A string that consists of elements of starting at delimited by the character. - --or- - + A string that consists of elements of starting at delimited by the character. + +-or- + if is zero. - ) is used instead. If any element in `value` is `null`, an empty string is used instead. - -## Examples -The following example concatenates two elements from an array of names of fruit. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.join2/CPP/join2.cpp" id="Snippet1"::: -:::code language="csharp" source="~/snippets/csharp/System/String/Join/join2.cs" interactive="try-dotnet-method" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Join/join2.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.join2/VB/join2.vb" id="Snippet1"::: - + ) is used instead. If any element in `value` is `null`, an empty string is used instead. + +## Examples +The following example concatenates two elements from an array of names of fruit. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.join2/CPP/join2.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Join/join2.cs" interactive="try-dotnet-method" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Join/join2.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.join2/VB/join2.vb" id="Snippet1"::: + ]]> is . - or is less than 0. - --or- - + or is less than 0. + +-or- + plus is greater than the number of elements in . Out of memory. @@ -9169,10 +9169,10 @@ The following example concatenates two elements from an array of names of fruit. The character to use as a separator. is included in the returned string only if has more than one element. A collection that contains the objects to concatenate. Concatenates the members of a collection, using the specified separator between each member. - A string that consists of the members of delimited by the character. - --or- - + A string that consists of the members of delimited by the character. + +-or- + if has no elements. To be added. @@ -9249,32 +9249,32 @@ The following example concatenates two elements from an array of names of fruit. The string to use as a separator. is included in the returned string only if has more than one element. A collection that contains the objects to concatenate. Concatenates the members of a collection, using the specified separator between each member. - A string that consists of the elements of delimited by the string. - --or- - + A string that consists of the elements of delimited by the string. + +-or- + if has no elements. - ) is used instead. If any member of `values` is `null`, an empty string is used instead. - - is a convenience method that lets you concatenate each member of an collection without first converting them to strings. The string representation of each object in the collection is derived by calling that object's `ToString` method. - -This method is particular useful with Language-Integrated Query (LINQ) query expressions. For example, the following code defines a very simple `Animal` class that contains the name of an animal and the order to which it belongs. It then defines a object that contains a number of `Animal` objects. The extension method is called to extract the `Animal` objects whose `Order` property equals "Rodent". The result is passed to the method. - -:::code language="csharp" source="~/snippets/csharp/System/String/Join/join5.cs" interactive="try-dotnet" id="Snippet5"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Join/join5.fs" id="Snippet5"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.join/vb/join5.vb" id="Snippet5"::: - -## Examples -The following example uses the Sieve of Eratosthenes algorithm to calculate the prime numbers that are less than or equal to 100. It assigns the result to a object of type integer, which it then passes to the method. - -:::code language="csharp" source="~/snippets/csharp/System/String/Join/join6.cs" interactive="try-dotnet" id="Snippet2"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Join/join6.fs" id="Snippet2"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.join/vb/join2.vb" id="Snippet2"::: - + ) is used instead. If any member of `values` is `null`, an empty string is used instead. + + is a convenience method that lets you concatenate each member of an collection without first converting them to strings. The string representation of each object in the collection is derived by calling that object's `ToString` method. + +This method is particular useful with Language-Integrated Query (LINQ) query expressions. For example, the following code defines a very simple `Animal` class that contains the name of an animal and the order to which it belongs. It then defines a object that contains a number of `Animal` objects. The extension method is called to extract the `Animal` objects whose `Order` property equals "Rodent". The result is passed to the method. + +:::code language="csharp" source="~/snippets/csharp/System/String/Join/join5.cs" interactive="try-dotnet" id="Snippet5"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Join/join5.fs" id="Snippet5"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.join/vb/join5.vb" id="Snippet5"::: + +## Examples +The following example uses the Sieve of Eratosthenes algorithm to calculate the prime numbers that are less than or equal to 100. It assigns the result to a object of type integer, which it then passes to the method. + +:::code language="csharp" source="~/snippets/csharp/System/String/Join/join6.cs" interactive="try-dotnet" id="Snippet2"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Join/join6.fs" id="Snippet2"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.join/vb/join2.vb" id="Snippet2"::: + ]]> @@ -9348,22 +9348,22 @@ The following example uses the Sieve of Eratosthenes algorithm to calculate the Reports the zero-based index position of the last occurrence of a specified Unicode character within this instance. The zero-based index position of if that character is found, or -1 if it is not. - - 1. - -This method begins searching at the last character position of this instance and proceeds backward toward the beginning until either `value` is found or the first character position has been examined. The search is case-sensitive. - -This method performs an ordinal (culture-insensitive) search, where a character is considered equivalent to another character only if their Unicode scalar values are the same. To perform a culture-sensitive search, use the method, where a Unicode scalar value representing a precomposed character, such as the ligature "Æ" (U+00C6), might be considered equivalent to any occurrence of the character's components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. - -## Examples -The following example defines an `ExtractFilename` method that uses the method to find the last directory separator character in a string and to extract the string's file name. If the file exists, the method returns the file name without its path. - -:::code language="csharp" source="~/snippets/csharp/System/String/LastIndexOf/LastIndexOf_Example.cs" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/LastIndexOf/LastIndexOf_Example.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.LastIndexOf/vb/LastIndexOf_Example.vb" id="Snippet1"::: - + - 1. + +This method begins searching at the last character position of this instance and proceeds backward toward the beginning until either `value` is found or the first character position has been examined. The search is case-sensitive. + +This method performs an ordinal (culture-insensitive) search, where a character is considered equivalent to another character only if their Unicode scalar values are the same. To perform a culture-sensitive search, use the method, where a Unicode scalar value representing a precomposed character, such as the ligature "Æ" (U+00C6), might be considered equivalent to any occurrence of the character's components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. + +## Examples +The following example defines an `ExtractFilename` method that uses the method to find the last directory separator character in a string and to extract the string's file name. If the file exists, the method returns the file name without its path. + +:::code language="csharp" source="~/snippets/csharp/System/String/LastIndexOf/LastIndexOf_Example.cs" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/LastIndexOf/LastIndexOf_Example.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.LastIndexOf/vb/LastIndexOf_Example.vb" id="Snippet1"::: + ]]> @@ -9424,31 +9424,31 @@ The following example defines an `ExtractFilename` method that uses the Reports the zero-based index position of the last occurrence of a specified string within this instance. The zero-based starting index position of if that string is found, or -1 if it is not. - - 1. - -The search begins at the last character position of this instance and proceeds backward toward the beginning until either `value` is found or the first character position has been examined. - -This method performs a word (case-sensitive and culture-sensitive) search using the current culture. - -Character sets include ignorable characters, which are characters that are not considered when performing a linguistic or culture-sensitive comparison. In a culture-sensitive search, if `value` contains an ignorable character, the result is equivalent to searching with that character removed. - -In the following example, the method is used to find two substrings (a soft hyphen followed by "n" and a soft hyphen followed by "m") in two strings. Only one of the strings contains a soft hyphen. If the example is run on .NET Framework 4 or later, in each case, because the soft hyphen is an ignorable character, the result is the same as if the soft hyphen had not been included in `value`. - -:::code language="csharp" source="~/snippets/csharp/System/String/LastIndexOf/lastindexof21.cs" id="Snippet21"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/LastIndexOf/lastindexof21.fs" id="Snippet21"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.LastIndexOf/vb/lastindexof21.vb" id="Snippet21"::: - -## Examples -The following example removes opening and closing HTML tags from a string if the tags begin and end the string. If a string ends with a closing bracket character (">"), the example uses the method to locate the start of the end tag. - -:::code language="csharp" source="~/snippets/csharp/System/String/LastIndexOf/lastindexof_example2.cs" id="Snippet2"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/LastIndexOf/lastindexof_example2.fs" id="Snippet2"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.LastIndexOf/vb/lastindexof_example2.vb" id="Snippet2"::: - + - 1. + +The search begins at the last character position of this instance and proceeds backward toward the beginning until either `value` is found or the first character position has been examined. + +This method performs a word (case-sensitive and culture-sensitive) search using the current culture. + +Character sets include ignorable characters, which are characters that are not considered when performing a linguistic or culture-sensitive comparison. In a culture-sensitive search, if `value` contains an ignorable character, the result is equivalent to searching with that character removed. + +In the following example, the method is used to find two substrings (a soft hyphen followed by "n" and a soft hyphen followed by "m") in two strings. Only one of the strings contains a soft hyphen. If the example is run on .NET Framework 4 or later, in each case, because the soft hyphen is an ignorable character, the result is the same as if the soft hyphen had not been included in `value`. + +:::code language="csharp" source="~/snippets/csharp/System/String/LastIndexOf/lastindexof21.cs" id="Snippet21"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/LastIndexOf/lastindexof21.fs" id="Snippet21"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.LastIndexOf/vb/lastindexof21.vb" id="Snippet21"::: + +## Examples +The following example removes opening and closing HTML tags from a string if the tags begin and end the string. If a string ends with a closing bracket character (">"), the example uses the method to locate the start of the end tag. + +:::code language="csharp" source="~/snippets/csharp/System/String/LastIndexOf/lastindexof_example2.cs" id="Snippet2"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/LastIndexOf/lastindexof_example2.fs" id="Snippet2"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.LastIndexOf/vb/lastindexof_example2.vb" id="Snippet2"::: + ]]> @@ -9510,21 +9510,21 @@ The following example removes opening and closing HTML tags from a string if the Reports the zero-based index position of the last occurrence of a specified Unicode character within this instance. The search starts at a specified character position and proceeds backward toward the beginning of the string. The zero-based index position of if that character is found, or -1 if it is not found or if the current instance equals . - - 1. This method begins searching at the `startIndex` character position of this instance and proceeds backward toward the beginning of the current instance until either `value` is found or the first character position has been examined. For example, if `startIndex` is - 1, the method searches every character from the last character in the string to the beginning. The search is case-sensitive. - -This method performs an ordinal (culture-insensitive) search, where a character is considered equivalent to another character only if their Unicode scalar values are the same. To perform a culture-sensitive search, use the method, where a Unicode scalar value representing a precomposed character, such as the ligature "Æ" (U+00C6), might be considered equivalent to any occurrence of the character's components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. - -## Examples -The following example finds the index of all occurrences of a character in a string, working from the end of the string to the start of the string. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.lastindexof1/CPP/lastixof1.cpp" id="Snippet1"::: -:::code language="csharp" source="~/snippets/csharp/System/String/LastIndexOf/lastixof1.cs" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/LastIndexOf/lastixof1.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.lastindexof1/VB/lastixof1.vb" id="Snippet1"::: - + - 1. This method begins searching at the `startIndex` character position of this instance and proceeds backward toward the beginning of the current instance until either `value` is found or the first character position has been examined. For example, if `startIndex` is - 1, the method searches every character from the last character in the string to the beginning. The search is case-sensitive. + +This method performs an ordinal (culture-insensitive) search, where a character is considered equivalent to another character only if their Unicode scalar values are the same. To perform a culture-sensitive search, use the method, where a Unicode scalar value representing a precomposed character, such as the ligature "Æ" (U+00C6), might be considered equivalent to any occurrence of the character's components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. + +## Examples +The following example finds the index of all occurrences of a character in a string, working from the end of the string to the start of the string. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.lastindexof1/CPP/lastixof1.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/LastIndexOf/lastixof1.cs" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/LastIndexOf/lastixof1.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.lastindexof1/VB/lastixof1.vb" id="Snippet1"::: + ]]> The current instance does not equal , and is less than zero or greater than or equal to the length of this instance. @@ -9583,37 +9583,37 @@ The following example finds the index of all occurrences of a character in a str Reports the zero-based index position of the last occurrence of a specified string within this instance. The search starts at a specified character position and proceeds backward toward the beginning of the string. The zero-based starting index position of if that string is found, or -1 if it is not found or if the current instance equals . - - 1. - -The search begins at the `startIndex` character position of this instance and proceeds backward toward the beginning until either `value` is found or the first character position has been examined. For example, if `startIndex` is - 1, the method searches every character from the last character in the string to the beginning. - -This method performs a word (case-sensitive and culture-sensitive) search using the current culture. - -Character sets include ignorable characters, which are characters that are not considered when performing a linguistic or culture-sensitive comparison. In a culture-sensitive search, if `value` contains an ignorable character, the result is equivalent to searching with that character removed. In the following example, the method is used to find a substring that includes a soft hyphen (U+00AD) and that precedes or includes the final "m" in a string. If the example is run on .NET Framework 4 or later, because the soft hyphen in the search string is ignored, calling the method to find a substring that consists of the soft hyphen and "m" returns the position of the "m" in the string, whereas calling it to find a substring that consists of the soft hyphen and "n" returns the position of the "n". - -:::code language="csharp" source="~/snippets/csharp/System/String/LastIndexOf/lastindexof22.cs" id="Snippet22"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/LastIndexOf/lastindexof22.fs" id="Snippet22"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.LastIndexOf/vb/lastindexof22.vb" id="Snippet22"::: - -## Examples -The following example finds the index of all occurrences of a string in target string, working from the end of the target string to the start of the target string. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.LastIndexOf7/CPP/lastixof7.cpp" id="Snippet1"::: -:::code language="csharp" source="~/snippets/csharp/System/String/LastIndexOf/lastixof7.cs" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/LastIndexOf/lastixof7.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.LastIndexOf7/VB/lastixof7.vb" id="Snippet1"::: - + - 1. + +The search begins at the `startIndex` character position of this instance and proceeds backward toward the beginning until either `value` is found or the first character position has been examined. For example, if `startIndex` is - 1, the method searches every character from the last character in the string to the beginning. + +This method performs a word (case-sensitive and culture-sensitive) search using the current culture. + +Character sets include ignorable characters, which are characters that are not considered when performing a linguistic or culture-sensitive comparison. In a culture-sensitive search, if `value` contains an ignorable character, the result is equivalent to searching with that character removed. In the following example, the method is used to find a substring that includes a soft hyphen (U+00AD) and that precedes or includes the final "m" in a string. If the example is run on .NET Framework 4 or later, because the soft hyphen in the search string is ignored, calling the method to find a substring that consists of the soft hyphen and "m" returns the position of the "m" in the string, whereas calling it to find a substring that consists of the soft hyphen and "n" returns the position of the "n". + +:::code language="csharp" source="~/snippets/csharp/System/String/LastIndexOf/lastindexof22.cs" id="Snippet22"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/LastIndexOf/lastindexof22.fs" id="Snippet22"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.LastIndexOf/vb/lastindexof22.vb" id="Snippet22"::: + +## Examples +The following example finds the index of all occurrences of a string in target string, working from the end of the target string to the start of the target string. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.LastIndexOf7/CPP/lastixof7.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/LastIndexOf/lastixof7.cs" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/LastIndexOf/lastixof7.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.LastIndexOf7/VB/lastixof7.vb" id="Snippet1"::: + ]]> is . - The current instance does not equal , and is less than zero or greater than the length of the current instance. - --or- - + The current instance does not equal , and is less than zero or greater than the length of the current instance. + +-or- + The current instance equals , and is less than -1 or greater than zero. As explained in [Best Practices for Using Strings](/dotnet/standard/base-types/best-practices-strings), we recommend that you avoid calling string comparison methods that substitute default values and instead call methods that require parameters to be explicitly specified. To find the index of a substring that precedes a particular character position by using the comparison rules of the current culture, signal your intention explicitly by calling the method overload with a value of for its parameter. If you don't need linguistic-aware comparison, consider using . @@ -9681,27 +9681,27 @@ The current instance equals , and Reports the zero-based index of the last occurrence of a specified string within the current object. A parameter specifies the type of search to use for the specified string. The zero-based starting index position of the parameter if that string is found, or -1 if it is not. - - 1. - -The `comparisonType` parameter specifies to search for the `value` parameter using: - -- The current or invariant culture. -- A case-sensitive or case-insensitive search. -- Word or ordinal comparison rules. - -The search begins at the last character position of this instance and proceeds backward toward the beginning until either `value` is found or the first character position has been examined. - -## Examples -The following example demonstrates three overloads of the method that find the last occurrence of a string within another string using different values of the enumeration. - -:::code language="csharp" source="~/snippets/csharp/System/String/LastIndexOf/liocmp.cs" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/LastIndexOf/liocmp.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.LastIndexOfCmp/vb/liocmp.vb" id="Snippet1"::: - + - 1. + +The `comparisonType` parameter specifies to search for the `value` parameter using: + +- The current or invariant culture. +- A case-sensitive or case-insensitive search. +- Word or ordinal comparison rules. + +The search begins at the last character position of this instance and proceeds backward toward the beginning until either `value` is found or the first character position has been examined. + +## Examples +The following example demonstrates three overloads of the method that find the last occurrence of a string within another string using different values of the enumeration. + +:::code language="csharp" source="~/snippets/csharp/System/String/LastIndexOf/liocmp.cs" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/LastIndexOf/liocmp.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.LastIndexOfCmp/vb/liocmp.vb" id="Snippet1"::: + ]]> @@ -9709,12 +9709,12 @@ The following example demonstrates three overloads of the is not a valid value. - Character sets include ignorable characters, which are characters that are not considered when performing a linguistic or culture-sensitive comparison. In a culture-sensitive search (that is, if is not or ), if contains an ignorable character, the result is equivalent to searching with that character removed. - -In the following example, the method is used to find two substrings (a soft hyphen followed by "n", and a soft hyphen followed by "m") in two strings. Only one of the strings contains a soft hyphen. If the example is run on .NET Framework 4 or later, because the soft hyphen is an ignorable character, a culture-sensitive search returns the same value that it would return if the soft hyphen were not included in the search string. An ordinal search, however, successfully finds the soft hyphen in one string and reports that it is absent from the second string. - -:::code language="csharp" source="~/snippets/csharp/System/String/LastIndexOf/lastindexof26.cs" id="Snippet26"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/LastIndexOf/lastindexof26.fs" id="Snippet26"::: + Character sets include ignorable characters, which are characters that are not considered when performing a linguistic or culture-sensitive comparison. In a culture-sensitive search (that is, if is not or ), if contains an ignorable character, the result is equivalent to searching with that character removed. + +In the following example, the method is used to find two substrings (a soft hyphen followed by "n", and a soft hyphen followed by "m") in two strings. Only one of the strings contains a soft hyphen. If the example is run on .NET Framework 4 or later, because the soft hyphen is an ignorable character, a culture-sensitive search returns the same value that it would return if the soft hyphen were not included in the search string. An ordinal search, however, successfully finds the soft hyphen in one string and reports that it is absent from the second string. + +:::code language="csharp" source="~/snippets/csharp/System/String/LastIndexOf/lastindexof26.cs" id="Snippet26"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/LastIndexOf/lastindexof26.fs" id="Snippet26"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.LastIndexOf/vb/lastindexof26.vb" id="Snippet26"::: @@ -9775,29 +9775,29 @@ In the following example, the if that character is found, or -1 if it is not found or if the current instance equals . - - 1. - -This method begins searching at the `startIndex` character position and proceeds backward toward the beginning of this instance until either `value` is found or `count` character positions have been examined. For example, if `startIndex` is - 1, the method searches backward `count` characters from the last character in the string. The search is case-sensitive. - -This method performs an ordinal (culture-insensitive) search, where a character is considered equivalent to another character only if their Unicode scalar value are the same. To perform a culture-sensitive search, use the method, where a Unicode scalar value representing a precomposed character, such as the ligature "Æ" (U+00C6), might be considered equivalent to any occurrence of the character's components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. - -## Examples -The following example finds the index of all occurrences of a character in a substring, working from the end of the substring to the start of the substring. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.lastindexof2/CPP/lastixof2.cpp" id="Snippet1"::: -:::code language="csharp" source="~/snippets/csharp/System/String/LastIndexOf/lastixof2.cs" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/LastIndexOf/lastixof2.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.lastindexof2/VB/lastixof2.vb" id="Snippet1"::: - - ]]> - - The current instance does not equal , and is less than zero or greater than or equal to the length of this instance. - --or- - + - 1. + +This method begins searching at the `startIndex` character position and proceeds backward toward the beginning of this instance until either `value` is found or `count` character positions have been examined. For example, if `startIndex` is - 1, the method searches backward `count` characters from the last character in the string. The search is case-sensitive. + +This method performs an ordinal (culture-insensitive) search, where a character is considered equivalent to another character only if their Unicode scalar value are the same. To perform a culture-sensitive search, use the method, where a Unicode scalar value representing a precomposed character, such as the ligature "Æ" (U+00C6), might be considered equivalent to any occurrence of the character's components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. + +## Examples +The following example finds the index of all occurrences of a character in a substring, working from the end of the substring to the start of the substring. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.lastindexof2/CPP/lastixof2.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/LastIndexOf/lastixof2.cs" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/LastIndexOf/lastixof2.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.lastindexof2/VB/lastixof2.vb" id="Snippet1"::: + + ]]> + + The current instance does not equal , and is less than zero or greater than or equal to the length of this instance. + +-or- + The current instance does not equal , and - + 1 is less than zero. @@ -9856,56 +9856,56 @@ The current instance does not equal , and

Reports the zero-based index position of the last occurrence of a specified string within this instance. The search starts at a specified character position and proceeds backward toward the beginning of the string for a specified number of character positions. The zero-based starting index position of if that string is found, or -1 if it is not found or if the current instance equals . - - 1. - -The search begins at the `startIndex` character position of this instance and proceeds backward toward the beginning until either `value` is found or `count` character positions have been examined. For example, if `startIndex` is - 1, the method searches backward `count` characters from the last character in the string. - -This method performs a word (case-sensitive and culture-sensitive) search using the current culture. - -Character sets include ignorable characters, which are characters that are not considered when performing a linguistic or culture-sensitive comparison. In a culture-sensitive search, if `value` contains an ignorable character, the result is equivalent to searching with that character removed. - -In the following example, the method is used to find the position of a soft hyphen (U+00AD) followed by an "m" or "n" in two strings. Only one of the strings contains a soft hyphen. In the case of the string that includes the soft hyphen followed by an "m", `LastIndexOf` returns the index of the "m" when searching for the soft hyphen followed by "m". - -:::code language="csharp" source="~/snippets/csharp/System/String/LastIndexOf/lastindexof23.cs" id="Snippet23"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/LastIndexOf/lastindexof23.fs" id="Snippet23"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.LastIndexOf/vb/lastindexof23.vb" id="Snippet23"::: - -## Examples -The following example finds the index of all occurrences of a string in substring, working from the end of the substring to the start of the substring. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.LastIndexOf8/CPP/lastixof8.cpp" id="Snippet1"::: -:::code language="csharp" source="~/snippets/csharp/System/String/LastIndexOf/lastixof8.cs" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/LastIndexOf/lastixof8.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.LastIndexOf8/VB/lastixof8.vb" id="Snippet1"::: - + - 1. + +The search begins at the `startIndex` character position of this instance and proceeds backward toward the beginning until either `value` is found or `count` character positions have been examined. For example, if `startIndex` is - 1, the method searches backward `count` characters from the last character in the string. + +This method performs a word (case-sensitive and culture-sensitive) search using the current culture. + +Character sets include ignorable characters, which are characters that are not considered when performing a linguistic or culture-sensitive comparison. In a culture-sensitive search, if `value` contains an ignorable character, the result is equivalent to searching with that character removed. + +In the following example, the method is used to find the position of a soft hyphen (U+00AD) followed by an "m" or "n" in two strings. Only one of the strings contains a soft hyphen. In the case of the string that includes the soft hyphen followed by an "m", `LastIndexOf` returns the index of the "m" when searching for the soft hyphen followed by "m". + +:::code language="csharp" source="~/snippets/csharp/System/String/LastIndexOf/lastindexof23.cs" id="Snippet23"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/LastIndexOf/lastindexof23.fs" id="Snippet23"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.LastIndexOf/vb/lastindexof23.vb" id="Snippet23"::: + +## Examples +The following example finds the index of all occurrences of a string in substring, working from the end of the substring to the start of the substring. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.LastIndexOf8/CPP/lastixof8.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/LastIndexOf/lastixof8.cs" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/LastIndexOf/lastixof8.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.LastIndexOf8/VB/lastixof8.vb" id="Snippet1"::: + ]]> is . - is negative. - --or- - -The current instance does not equal , and is negative. - --or- - -The current instance does not equal , and is greater than the length of this instance. - --or- - -The current instance does not equal , and - + 1 specifies a position that is not within this instance. - --or- - -The current instance equals and is less than -1 or greater than zero. - --or- - + is negative. + +-or- + +The current instance does not equal , and is negative. + +-or- + +The current instance does not equal , and is greater than the length of this instance. + +-or- + +The current instance does not equal , and - + 1 specifies a position that is not within this instance. + +-or- + +The current instance equals and is less than -1 or greater than zero. + +-or- + The current instance equals and is greater than 1. As explained in [Best Practices for Using Strings](/dotnet/standard/base-types/best-practices-strings), we recommend that you avoid calling string comparison methods that substitute default values and instead call methods that require parameters to be explicitly specified. To perform this operation by using the comparison rules of the current culture, signal your intention explicitly by calling the method overload with a value of for its parameter. If you don't need linguistic-aware comparison, consider using . @@ -9965,40 +9965,40 @@ The current instance equals and Reports the zero-based index of the last occurrence of a specified string within the current object. The search starts at a specified character position and proceeds backward toward the beginning of the string. A parameter specifies the type of comparison to perform when searching for the specified string. The zero-based starting index position of the parameter if that string is found, or -1 if it is not found or if the current instance equals . - - 1. - -The search begins at the `startIndex` character position and proceeds backward until either `value` is found or the first character position has been examined. For example, if `startIndex` is - 1, the method searches every character from the last character in the string to the beginning. - -The `comparisonType` parameter specifies to search for the `value` parameter using the current or invariant culture, using a case-sensitive or case-insensitive search, and using word or ordinal comparison rules. - -## Examples -The following example demonstrates three overloads of the method that find the last occurrence of a string within another string using different values of the enumeration. - -:::code language="csharp" source="~/snippets/csharp/System/String/LastIndexOf/liocmp.cs" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/LastIndexOf/liocmp.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.LastIndexOfCmp/vb/liocmp.vb" id="Snippet1"::: - + - 1. + +The search begins at the `startIndex` character position and proceeds backward until either `value` is found or the first character position has been examined. For example, if `startIndex` is - 1, the method searches every character from the last character in the string to the beginning. + +The `comparisonType` parameter specifies to search for the `value` parameter using the current or invariant culture, using a case-sensitive or case-insensitive search, and using word or ordinal comparison rules. + +## Examples +The following example demonstrates three overloads of the method that find the last occurrence of a string within another string using different values of the enumeration. + +:::code language="csharp" source="~/snippets/csharp/System/String/LastIndexOf/liocmp.cs" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/LastIndexOf/liocmp.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.LastIndexOfCmp/vb/liocmp.vb" id="Snippet1"::: + ]]> is . - The current instance does not equal , and is less than zero or greater than the length of the current instance. - --or- - + The current instance does not equal , and is less than zero or greater than the length of the current instance. + +-or- + The current instance equals , and is less than -1 or greater than zero. is not a valid value. - Character sets include ignorable characters, which are characters that are not considered when performing a linguistic or culture-sensitive comparison. In a culture-sensitive search (that is, if is not or ), if contains an ignorable character, the result is equivalent to searching with that character removed. - -In the following example, the method is used to find the position of a soft hyphen (U+00AD) followed by an "m", starting with the final "m" in two strings. Only one of the strings contains the required substring. If the example is run on .NET Framework 4 or later, in both cases, because the soft hyphen is an ignorable character, the method returns the index of "m" in the string when it performs a culture-sensitive comparison. Note that in the case of the first string, which includes the soft hyphen followed by an "m", the method returns the index of the "m" and not the index of the soft hyphen. The method returns the index of the soft hyphen in the first string only when it performs an ordinal comparison. - -:::code language="csharp" source="~/snippets/csharp/System/String/LastIndexOf/lastindexof25.cs" id="Snippet25"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/LastIndexOf/lastindexof25.fs" id="Snippet25"::: + Character sets include ignorable characters, which are characters that are not considered when performing a linguistic or culture-sensitive comparison. In a culture-sensitive search (that is, if is not or ), if contains an ignorable character, the result is equivalent to searching with that character removed. + +In the following example, the method is used to find the position of a soft hyphen (U+00AD) followed by an "m", starting with the final "m" in two strings. Only one of the strings contains the required substring. If the example is run on .NET Framework 4 or later, in both cases, because the soft hyphen is an ignorable character, the method returns the index of "m" in the string when it performs a culture-sensitive comparison. Note that in the case of the first string, which includes the soft hyphen followed by an "m", the method returns the index of the "m" and not the index of the soft hyphen. The method returns the index of the soft hyphen in the first string only when it performs an ordinal comparison. + +:::code language="csharp" source="~/snippets/csharp/System/String/LastIndexOf/lastindexof25.cs" id="Snippet25"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/LastIndexOf/lastindexof25.fs" id="Snippet25"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.LastIndexOf/vb/lastindexof25.vb" id="Snippet25"::: @@ -10060,61 +10060,61 @@ In the following example, the parameter if that string is found, or -1 if it is not found or if the current instance equals . - - 1. - -The search begins at the `startIndex` character position and proceeds backward until either `value` is found or `count` character positions have been examined. For example, if `startIndex` is - 1, the method searches backward `count` characters from the last character in the string. - -The `comparisonType` parameter specifies to search for the `value` parameter using: - -- The current or invariant culture. -- A case-sensitive or case-insensitive search. -- Word or ordinal comparison rules. - -## Examples -The following example demonstrates three overloads of the method that find the last occurrence of a string within another string using different values of the enumeration. - -:::code language="csharp" source="~/snippets/csharp/System/String/LastIndexOf/liocmp.cs" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/LastIndexOf/liocmp.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.LastIndexOfCmp/vb/liocmp.vb" id="Snippet1"::: - + - 1. + +The search begins at the `startIndex` character position and proceeds backward until either `value` is found or `count` character positions have been examined. For example, if `startIndex` is - 1, the method searches backward `count` characters from the last character in the string. + +The `comparisonType` parameter specifies to search for the `value` parameter using: + +- The current or invariant culture. +- A case-sensitive or case-insensitive search. +- Word or ordinal comparison rules. + +## Examples +The following example demonstrates three overloads of the method that find the last occurrence of a string within another string using different values of the enumeration. + +:::code language="csharp" source="~/snippets/csharp/System/String/LastIndexOf/liocmp.cs" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/LastIndexOf/liocmp.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.LastIndexOfCmp/vb/liocmp.vb" id="Snippet1"::: + ]]> is . - is negative. - --or- - -The current instance does not equal , and is negative. - --or- - -The current instance does not equal , and is greater than the length of this instance. - --or- - -The current instance does not equal , and + 1 - specifies a position that is not within this instance. - --or- - -The current instance equals and is less than -1 or greater than zero. - --or- - + is negative. + +-or- + +The current instance does not equal , and is negative. + +-or- + +The current instance does not equal , and is greater than the length of this instance. + +-or- + +The current instance does not equal , and + 1 - specifies a position that is not within this instance. + +-or- + +The current instance equals and is less than -1 or greater than zero. + +-or- + The current instance equals and is greater than 1. is not a valid value. - Character sets include ignorable characters, which are characters that are not considered when performing a linguistic or culture-sensitive comparison. In a culture-sensitive search (that is, if is not or ), if contains an ignorable character, the result is equivalent to searching with that character removed. - -In the following example, the method is used to find the position of a soft hyphen (U+00AD) followed by an "m" in all but the first character position before the final "m" in two strings. Only one of the strings contains the required substring. If the example is run on .NET Framework 4 or later, in both cases, because the soft hyphen is an ignorable character, the method returns the index of "m" in the string when it performs a culture-sensitive comparison. When it performs an ordinal comparison, however, it finds the substring only in the first string. Note that in the case of the first string, which includes the soft hyphen followed by an "m", the method returns the index of the "m" when it performs a culture-sensitive comparison. The method returns the index of the soft hyphen in the first string only when it performs an ordinal comparison. - -:::code language="csharp" source="~/snippets/csharp/System/String/LastIndexOf/lastindexof24.cs" id="Snippet24"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/LastIndexOf/lastindexof24.fs" id="Snippet24"::: + Character sets include ignorable characters, which are characters that are not considered when performing a linguistic or culture-sensitive comparison. In a culture-sensitive search (that is, if is not or ), if contains an ignorable character, the result is equivalent to searching with that character removed. + +In the following example, the method is used to find the position of a soft hyphen (U+00AD) followed by an "m" in all but the first character position before the final "m" in two strings. Only one of the strings contains the required substring. If the example is run on .NET Framework 4 or later, in both cases, because the soft hyphen is an ignorable character, the method returns the index of "m" in the string when it performs a culture-sensitive comparison. When it performs an ordinal comparison, however, it finds the substring only in the first string. Note that in the case of the first string, which includes the soft hyphen followed by an "m", the method returns the index of the "m" when it performs a culture-sensitive comparison. The method returns the index of the soft hyphen in the first string only when it performs an ordinal comparison. + +:::code language="csharp" source="~/snippets/csharp/System/String/LastIndexOf/lastindexof24.cs" id="Snippet24"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/LastIndexOf/lastindexof24.fs" id="Snippet24"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.LastIndexOf/vb/lastindexof24.vb" id="Snippet24"::: @@ -10178,23 +10178,23 @@ In the following example, the was found; -1 if no character in was found. - method, where a Unicode scalar value representing a precomposed character, such as the ligature "Æ" (U+00C6), might be considered equivalent to any occurrence of the character's components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. - -## Examples -The following example finds the index of the last occurrence of any character in the string "is" within another string. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.LastIndexOfAny1/CPP/lastixany1.cpp" id="Snippet1"::: -:::code language="csharp" source="~/snippets/csharp/System/String/LastIndexOfAny/lastixany1.cs" interactive="try-dotnet" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/LastIndexOfAny/lastixany1.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.LastIndexOfAny1/VB/lastixany1.vb" id="Snippet1"::: - + method, where a Unicode scalar value representing a precomposed character, such as the ligature "Æ" (U+00C6), might be considered equivalent to any occurrence of the character's components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. + +## Examples +The following example finds the index of the last occurrence of any character in the string "is" within another string. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.LastIndexOfAny1/CPP/lastixany1.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/LastIndexOfAny/lastixany1.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/LastIndexOfAny/lastixany1.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.LastIndexOfAny1/VB/lastixany1.vb" id="Snippet1"::: + ]]> @@ -10255,23 +10255,23 @@ The following example finds the index of the last occurrence of any character in

Reports the zero-based index position of the last occurrence in this instance of one or more characters specified in a Unicode array. The search starts at a specified character position and proceeds backward toward the beginning of the string. The index position of the last occurrence in this instance where any character in was found; -1 if no character in was found or if the current instance equals . - method, where a Unicode scalar value representing a precomposed character, such as the ligature "Æ" (U+00C6), might be considered equivalent to any occurrence of the character's components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. - -## Examples -The following example finds the index of the last occurrence of any character in the string "is" within a substring of another string. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.LastIndexOfAny2/CPP/lastixany2.cpp" id="Snippet1"::: -:::code language="csharp" source="~/snippets/csharp/System/String/LastIndexOfAny/lastixany2.cs" interactive="try-dotnet" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/LastIndexOfAny/lastixany2.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.LastIndexOfAny2/VB/lastixany2.vb" id="Snippet1"::: - + method, where a Unicode scalar value representing a precomposed character, such as the ligature "Æ" (U+00C6), might be considered equivalent to any occurrence of the character's components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. + +## Examples +The following example finds the index of the last occurrence of any character in the string "is" within a substring of another string. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.LastIndexOfAny2/CPP/lastixany2.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/LastIndexOfAny/lastixany2.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/LastIndexOfAny/lastixany2.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.LastIndexOfAny2/VB/lastixany2.vb" id="Snippet1"::: + ]]> @@ -10341,31 +10341,31 @@ The following example finds the index of the last occurrence of any character in Reports the zero-based index position of the last occurrence in this instance of one or more characters specified in a Unicode array. The search starts at a specified character position and proceeds backward toward the beginning of the string for a specified number of character positions. The index position of the last occurrence in this instance where any character in was found; -1 if no character in was found or if the current instance equals . - method, where a Unicode scalar value representing a precomposed character, such as the ligature "Æ" (U+00C6), might be considered equivalent to any occurrence of the character's components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. - -## Examples -The following example finds the index of the last occurrence of any character in the string "aid" within a substring of another string. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.LastIndexOfAny3/CPP/lastixany3.cpp" id="Snippet1"::: -:::code language="csharp" source="~/snippets/csharp/System/String/LastIndexOfAny/lastixany3.cs" interactive="try-dotnet" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/LastIndexOfAny/lastixany3.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.LastIndexOfAny3/VB/lastixany3.vb" id="Snippet1"::: - + method, where a Unicode scalar value representing a precomposed character, such as the ligature "Æ" (U+00C6), might be considered equivalent to any occurrence of the character's components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. + +## Examples +The following example finds the index of the last occurrence of any character in the string "aid" within a substring of another string. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.LastIndexOfAny3/CPP/lastixany3.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/LastIndexOfAny/lastixany3.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/LastIndexOfAny/lastixany3.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.LastIndexOfAny3/VB/lastixany3.vb" id="Snippet1"::: + ]]> is . - The current instance does not equal , and or is negative. - --or- - + The current instance does not equal , and or is negative. + +-or- + The current instance does not equal , and minus + 1 is less than zero. @@ -10423,26 +10423,26 @@ The current instance does not equal , and

Gets the number of characters in the current object. The number of characters in the current string. - property returns the number of objects in this instance, not the number of Unicode characters. The reason is that a Unicode character might be represented by more than one . Use the class to work with each Unicode character instead of each . - -In some languages, such as C and C++, a null character indicates the end of a string. In .NET, a null character can be embedded in a string. When a string includes one or more null characters, they are included in the length of the total string. For example, in the following string, the substrings "abc" and "def" are separated by a null character. The property returns 7, which indicates that it includes the six alphabetic characters as well as the null character. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Class/cpp/system.string.class.cpp" id="Snippet1"::: -:::code language="csharp" source="~/snippets/csharp/System/String/Overview/System.String.Class.cs" interactive="try-dotnet-method" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Overview/System.String.Class.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Class/vb/System.String.Class.vb" id="Snippet1"::: - -## Examples -The following example demonstrates the property. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.length/CPP/length.cpp" id="Snippet1"::: -:::code language="csharp" source="~/snippets/csharp/System/String/Length/length.cs" interactive="try-dotnet-method" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Length/length.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.length/VB/length.vb" id="Snippet1"::: - + property returns the number of objects in this instance, not the number of Unicode characters. The reason is that a Unicode character might be represented by more than one . Use the class to work with each Unicode character instead of each . + +In some languages, such as C and C++, a null character indicates the end of a string. In .NET, a null character can be embedded in a string. When a string includes one or more null characters, they are included in the length of the total string. For example, in the following string, the substrings "abc" and "def" are separated by a null character. The property returns 7, which indicates that it includes the six alphabetic characters as well as the null character. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Class/cpp/system.string.class.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Overview/System.String.Class.cs" interactive="try-dotnet-method" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Overview/System.String.Class.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Class/vb/System.String.Class.vb" id="Snippet1"::: + +## Examples +The following example demonstrates the property. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.length/CPP/length.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Length/length.cs" interactive="try-dotnet-method" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Length/length.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.length/VB/length.vb" id="Snippet1"::: + ]]> @@ -10457,16 +10457,16 @@ The following example demonstrates the property.

Returns a new string whose binary representation is in a particular Unicode normalization form. - @@ -10509,33 +10509,33 @@ The following example normalizes a string to each of four normalization forms, c Returns a new string whose textual value is the same as this string, but whose binary representation is in Unicode normalization form C. A new, normalized string whose textual value is the same as this string, but whose binary representation is in normalization form C. - method to normalize the strings to normalization form C. - -3. To compare two strings, call a method that supports ordinal string comparison, such as the method, and supply a value of or as the argument. To sort an array of normalized strings, pass a `comparer` value of or to an appropriate overload of . - -4. Emit the strings in the sorted output based on the order indicated by the previous step. - -For a description of supported Unicode normalization forms, see . - + method to normalize the strings to normalization form C. + +3. To compare two strings, call a method that supports ordinal string comparison, such as the method, and supply a value of or as the argument. To sort an array of normalized strings, pass a `comparer` value of or to an appropriate overload of . + +4. Emit the strings in the sorted output based on the order indicated by the previous step. + +For a description of supported Unicode normalization forms, see . + ]]> The current instance contains invalid Unicode characters. @@ -10585,32 +10585,32 @@ For a description of supported Unicode normalization forms, see System.String - + A Unicode normalization form. Returns a new string whose textual value is the same as this string, but whose binary representation is in the specified Unicode normalization form. A new string whose textual value is the same as this string, but whose binary representation is in the normalization form specified by the parameter. - method to normalize the strings to a specified normalization form. - -3. To compare two strings, call a method that supports ordinal string comparison, such as the method, and supply a value of or as the argument. To sort an array of normalized strings, pass a `comparer` value of or to an appropriate overload of . - -4. Emit the strings in the sorted output based on the order indicated by the previous step. - -For a description of supported Unicode normalization forms, see . - + method to normalize the strings to a specified normalization form. + +3. To compare two strings, call a method that supports ordinal string comparison, such as the method, and supply a value of or as the argument. To sort an array of normalized strings, pass a `comparer` value of or to an appropriate overload of . + +4. Emit the strings in the sorted output based on the order indicated by the previous step. + +For a description of supported Unicode normalization forms, see . + ]]> The current instance contains invalid Unicode characters. @@ -10680,21 +10680,21 @@ For a description of supported Unicode normalization forms, see if the value of is the same as the value of ; otherwise, .
- method defines the operation of the equality operator for the class. It enables code such as that shown in the Example section. The operator, in turn, calls the static method, which performs an ordinal (case-sensitive and culture-insensitive) comparison. - -> [!NOTE] -> The Visual Basic compiler does not resolve the equality operator as a call to the method. Instead, the equality operator wraps a call to the method. - -## Examples -The following example demonstrates the equality operator. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Equality/CPP/equalityop.cpp" id="Snippet1"::: -:::code language="csharp" source="~/snippets/csharp/System/String/op_Equality/equalityop.cs" interactive="try-dotnet" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/op_Equality/equalityop.fs" id="Snippet1"::: - + method defines the operation of the equality operator for the class. It enables code such as that shown in the Example section. The operator, in turn, calls the static method, which performs an ordinal (case-sensitive and culture-insensitive) comparison. + +> [!NOTE] +> The Visual Basic compiler does not resolve the equality operator as a call to the method. Instead, the equality operator wraps a call to the method. + +## Examples +The following example demonstrates the equality operator. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Equality/CPP/equalityop.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/op_Equality/equalityop.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/op_Equality/equalityop.fs" id="Snippet1"::: + ]]> @@ -10811,23 +10811,23 @@ The following example demonstrates the equality operator. if the value of is different from the value of ; otherwise, . - method defines the operation of the inequality operator for the class. It enables code such as that shown in the Examples section. - -The operator in turn calls the static method, which performs an ordinal (case-sensitive and culture-insensitive) comparison. - -> [!NOTE] -> The Visual Basic compiler does not resolve the inequality operator as a call to the method. Instead, the inequality operator wraps a call to the method. - -## Examples -The following example demonstrates the inequality operator. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Inequality/CPP/inequalityop.cpp" id="Snippet1"::: -:::code language="csharp" source="~/snippets/csharp/System/String/op_Inequality/inequalityop.cs" interactive="try-dotnet" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/op_Inequality/inequalityop.fs" id="Snippet1"::: - + method defines the operation of the inequality operator for the class. It enables code such as that shown in the Examples section. + +The operator in turn calls the static method, which performs an ordinal (case-sensitive and culture-insensitive) comparison. + +> [!NOTE] +> The Visual Basic compiler does not resolve the inequality operator as a call to the method. Instead, the inequality operator wraps a call to the method. + +## Examples +The following example demonstrates the inequality operator. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Inequality/CPP/inequalityop.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/op_Inequality/inequalityop.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/op_Inequality/inequalityop.fs" id="Snippet1"::: + ]]> @@ -10891,24 +10891,24 @@ The following example demonstrates the inequality operator. Returns a new string that right-aligns the characters in this instance by padding them with spaces on the left, for a specified total length. A new string that is equivalent to this instance, but right-aligned and padded on the left with as many spaces as needed to create a length of . However, if is less than the length of this instance, the method returns a reference to the existing instance. If is equal to the length of this instance, the method returns a new string that is identical to this instance. - method pads the beginning of the returned string. This means that, when used with right-to-left languages, it pads the right portion of the string. - -> [!NOTE] -> If the method pads the current instance with white-space characters, this method does not modify the value of the current instance. Instead, it returns a new string that is padded with leading white space so that its total length is `totalWidth` characters. - -## Examples -The following example demonstrates the method. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic String.PadLeft Example/CPP/source.cpp" id="Snippet1"::: -:::code language="csharp" source="~/snippets/csharp/System/String/PadLeft/source.cs" interactive="try-dotnet-method" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/PadLeft/source.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic String.PadLeft Example/VB/source.vb" id="Snippet1"::: - + method pads the beginning of the returned string. This means that, when used with right-to-left languages, it pads the right portion of the string. + +> [!NOTE] +> If the method pads the current instance with white-space characters, this method does not modify the value of the current instance. Instead, it returns a new string that is padded with leading white space so that its total length is `totalWidth` characters. + +## Examples +The following example demonstrates the method. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic String.PadLeft Example/CPP/source.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/PadLeft/source.cs" interactive="try-dotnet-method" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/PadLeft/source.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic String.PadLeft Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -10966,22 +10966,22 @@ The following example demonstrates the method. Returns a new string that right-aligns the characters in this instance by padding them on the left with a specified Unicode character, for a specified total length. A new string that is equivalent to this instance, but right-aligned and padded on the left with as many characters as needed to create a length of . However, if is less than the length of this instance, the method returns a reference to the existing instance. If is equal to the length of this instance, the method returns a new string that is identical to this instance. - method pads the beginning of the returned string. This means that, when used with right-to-left languages, it pads the right portion of the string. - -> [!NOTE] -> If the method pads the current instance with white-space characters, this method does not modify the value of the current instance. Instead, it returns a new string that is padded with leading `paddingChar` characters so that its total length is `totalWidth` characters. - -## Examples -The following example demonstrates the method. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic String.PadLeft1 Example/CPP/source.cpp" id="Snippet1"::: -:::code language="csharp" source="~/snippets/csharp/System/String/PadLeft/source1.cs" interactive="try-dotnet" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/PadLeft/source1.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic String.PadLeft1 Example/VB/source.vb" id="Snippet1"::: - + method pads the beginning of the returned string. This means that, when used with right-to-left languages, it pads the right portion of the string. + +> [!NOTE] +> If the method pads the current instance with white-space characters, this method does not modify the value of the current instance. Instead, it returns a new string that is padded with leading `paddingChar` characters so that its total length is `totalWidth` characters. + +## Examples +The following example demonstrates the method. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic String.PadLeft1 Example/CPP/source.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/PadLeft/source1.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/PadLeft/source1.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic String.PadLeft1 Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -11051,24 +11051,24 @@ The following example demonstrates the method. Returns a new string that left-aligns the characters in this string by padding them with spaces on the right, for a specified total length. A new string that is equivalent to this instance, but left-aligned and padded on the right with as many spaces as needed to create a length of . However, if is less than the length of this instance, the method returns a reference to the existing instance. If is equal to the length of this instance, the method returns a new string that is identical to this instance. - method pads the end of the returned string. This means that, when used with right-to-left languages, it pads the left portion of the string. - -> [!NOTE] -> If the method pads the current instance with white-space characters, this method does not modify the value of the current instance. Instead, it returns a new string that is padded with trailing white space so that its total length is `totalWidth` characters. - -## Examples -The following example demonstrates the method. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic String.PadRight Example/CPP/source.cpp" id="Snippet1"::: -:::code language="csharp" source="~/snippets/csharp/System/String/PadRight/source.cs" interactive="try-dotnet-method" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/PadRight/source.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic String.PadRight Example/VB/source.vb" id="Snippet1"::: - + method pads the end of the returned string. This means that, when used with right-to-left languages, it pads the left portion of the string. + +> [!NOTE] +> If the method pads the current instance with white-space characters, this method does not modify the value of the current instance. Instead, it returns a new string that is padded with trailing white space so that its total length is `totalWidth` characters. + +## Examples +The following example demonstrates the method. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic String.PadRight Example/CPP/source.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/PadRight/source.cs" interactive="try-dotnet-method" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/PadRight/source.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic String.PadRight Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -11126,22 +11126,22 @@ The following example demonstrates the method. Returns a new string that left-aligns the characters in this string by padding them on the right with a specified Unicode character, for a specified total length. A new string that is equivalent to this instance, but left-aligned and padded on the right with as many characters as needed to create a length of . However, if is less than the length of this instance, the method returns a reference to the existing instance. If is equal to the length of this instance, the method returns a new string that is identical to this instance. - method pads the end of the returned string. This means that, when used with right-to-left languages, it pads the left portion of the string. - -> [!NOTE] -> If the method pads the current instance with white-space characters, this method does not modify the value of the current instance. Instead, it returns a new string that is padded with trailing `paddingChar` characters so that its total length is `totalWidth` characters. - -## Examples -The following example demonstrates the method. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic String.PadRight1 Example/CPP/source.cpp" id="Snippet1"::: -:::code language="csharp" source="~/snippets/csharp/System/String/PadRight/source1.cs" interactive="try-dotnet-method" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/PadRight/source1.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic String.PadRight1 Example/VB/source.vb" id="Snippet1"::: - + method pads the end of the returned string. This means that, when used with right-to-left languages, it pads the left portion of the string. + +> [!NOTE] +> If the method pads the current instance with white-space characters, this method does not modify the value of the current instance. Instead, it returns a new string that is padded with trailing `paddingChar` characters so that its total length is `totalWidth` characters. + +## Examples +The following example demonstrates the method. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic String.PadRight1 Example/CPP/source.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/PadRight/source1.cs" interactive="try-dotnet-method" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/PadRight/source1.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic String.PadRight1 Example/VB/source.vb" id="Snippet1"::: + ]]> @@ -11210,29 +11210,29 @@ The following example demonstrates the method. Returns a new string in which all the characters in the current instance, beginning at a specified position and continuing through the last position, have been deleted. A new string that is equivalent to this string except for the removed characters. - [!NOTE] -> This method does not modify the value of the current instance. Instead, it returns a new string in which all characters from position `startIndex` to the end of the original string have been removed. - -## Examples -The following example demonstrates the method. The next-to-last case removes all text starting from the specified index through the end of the string. The last case removes three characters starting from the specified index. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.remove/CPP/r.cpp" id="Snippet1"::: -:::code language="csharp" source="~/snippets/csharp/System/String/Remove/r.cs" interactive="try-dotnet" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Remove/r.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.remove/VB/r.vb" id="Snippet1"::: - + [!NOTE] +> This method does not modify the value of the current instance. Instead, it returns a new string in which all characters from position `startIndex` to the end of the original string have been removed. + +## Examples +The following example demonstrates the method. The next-to-last case removes all text starting from the specified index through the end of the string. The last case removes three characters starting from the specified index. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.remove/CPP/r.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Remove/r.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Remove/r.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.remove/VB/r.vb" id="Snippet1"::: + ]]> - is less than zero. - --or- - + is less than zero. + +-or- + specifies a position that is not within this string. @@ -11298,28 +11298,28 @@ The following example demonstrates the method. Th Returns a new string in which a specified number of characters in the current instance beginning at a specified position have been deleted. A new string that is equivalent to this instance except for the removed characters. - [!NOTE] -> This method does not modify the value of the current instance. Instead, it returns a new string in which the number of characters specified by the `count` parameter have been removed. The characters are removed at the position specified by `startIndex`. - -## Examples -The following example demonstrates how you can remove the middle name from a complete name. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringremove/CPP/stringremove.cpp" id="Snippet1"::: -:::code language="csharp" source="~/snippets/csharp/System/String/Remove/stringremove.cs" interactive="try-dotnet" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Remove/stringremove.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringremove/VB/stringremove.vb" id="Snippet1"::: - - ]]> - - Either or is less than zero. - --or- - + [!NOTE] +> This method does not modify the value of the current instance. Instead, it returns a new string in which the number of characters specified by the `count` parameter have been removed. The characters are removed at the position specified by `startIndex`. + +## Examples +The following example demonstrates how you can remove the middle name from a complete name. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringremove/CPP/stringremove.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Remove/stringremove.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Remove/stringremove.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringremove/VB/stringremove.vb" id="Snippet1"::: + + ]]> + + Either or is less than zero. + +-or- + plus specify a position outside this instance. @@ -11398,28 +11398,28 @@ The following example demonstrates how you can remove the middle name from a com Returns a new string in which all occurrences of a specified Unicode character in this instance are replaced with another specified Unicode character. A string that is equivalent to this instance except that all instances of are replaced with . If is not found in the current instance, the method returns the current instance unchanged. - [!NOTE] -> This method does not modify the value of the current instance. Instead, it returns a new string in which all occurrences of `oldChar` are replaced by `newChar`. - -Because this method returns the modified string, you can chain together successive calls to the method to perform multiple replacements on the original string. Method calls are executed from left to right. The following example provides an illustration. - -:::code language="csharp" source="~/snippets/csharp/System/String/Replace/replace2.cs" interactive="try-dotnet-method" id="Snippet2"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Replace/replace2.fs" id="Snippet2"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.replace/vb/replace2.vb" id="Snippet2"::: - -## Examples -The following example creates a comma separated value list by substituting commas for the blanks between a series of numbers. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.replace1/CPP/string.replace1.cpp" id="Snippet1"::: -:::code language="csharp" source="~/snippets/csharp/System/String/Replace/string.replace1.cs" interactive="try-dotnet-method" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Replace/string.replace1.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.replace1/VB/string.replace1.vb" id="Snippet1"::: - + [!NOTE] +> This method does not modify the value of the current instance. Instead, it returns a new string in which all occurrences of `oldChar` are replaced by `newChar`. + +Because this method returns the modified string, you can chain together successive calls to the method to perform multiple replacements on the original string. Method calls are executed from left to right. The following example provides an illustration. + +:::code language="csharp" source="~/snippets/csharp/System/String/Replace/replace2.cs" interactive="try-dotnet-method" id="Snippet2"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Replace/replace2.fs" id="Snippet2"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.replace/vb/replace2.vb" id="Snippet2"::: + +## Examples +The following example creates a comma separated value list by substituting commas for the blanks between a series of numbers. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.replace1/CPP/string.replace1.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Replace/string.replace1.cs" interactive="try-dotnet-method" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Replace/string.replace1.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.replace1/VB/string.replace1.vb" id="Snippet1"::: + ]]> @@ -11498,30 +11498,30 @@ The following example creates a comma separated value list by substituting comma Returns a new string in which all occurrences of a specified string in the current instance are replaced with another specified string. A string that is equivalent to the current string except that all instances of are replaced with . If is not found in the current instance, the method returns the current instance unchanged. - [!NOTE] -> This method does not modify the value of the current instance. Instead, it returns a new string in which all occurrences of `oldValue` are replaced by `newValue`. - -This method performs an ordinal (case-sensitive and culture-insensitive) search to find `oldValue`. - -Because this method returns the modified string, you can chain together successive calls to the method to perform multiple replacements on the original string. Method calls are executed from left to right. The following example provides an illustration. - -:::code language="csharp" source="~/snippets/csharp/System/String/Replace/replace1.cs" interactive="try-dotnet-method" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Replace/replace1.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.replace/vb/replace1.vb" id="Snippet1"::: - -## Examples -The following example demonstrates how you can use the method to correct a spelling error. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringreplace/CPP/stringreplace.cpp" id="Snippet1"::: -:::code language="csharp" source="~/snippets/csharp/System/String/Replace/stringreplace.cs" interactive="try-dotnet-method" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Replace/stringreplace.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringreplace/VB/stringreplace.vb" id="Snippet1"::: - + [!NOTE] +> This method does not modify the value of the current instance. Instead, it returns a new string in which all occurrences of `oldValue` are replaced by `newValue`. + +This method performs an ordinal (case-sensitive and culture-insensitive) search to find `oldValue`. + +Because this method returns the modified string, you can chain together successive calls to the method to perform multiple replacements on the original string. Method calls are executed from left to right. The following example provides an illustration. + +:::code language="csharp" source="~/snippets/csharp/System/String/Replace/replace1.cs" interactive="try-dotnet-method" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Replace/replace1.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.replace/vb/replace1.vb" id="Snippet1"::: + +## Examples +The following example demonstrates how you can use the method to correct a spelling error. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringreplace/CPP/stringreplace.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Replace/stringreplace.cs" interactive="try-dotnet-method" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Replace/stringreplace.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringreplace/VB/stringreplace.vb" id="Snippet1"::: + ]]> @@ -11586,22 +11586,22 @@ The following example demonstrates how you can use the Returns a new string in which all occurrences of a specified string in the current instance are replaced with another specified string, using the provided comparison type. A string that is equivalent to the current string except that all instances of are replaced with . If is not found in the current instance, the method returns the current instance unchanged. - [!NOTE] -> This method does not modify the value of the current instance. Instead, it returns a new string in which all occurrences of `oldValue` are replaced by `newValue`. - -This method performs a search to find `oldValue` using the culture and case sensitivity described by `comparisonType`. - -Because this method returns the modified string, you can chain together successive calls to the method to perform multiple replacements on the original string. Method calls are executed from left to right. The following example provides an illustration. - -:::code language="csharp" source="~/snippets/csharp/System/String/Replace/replace1.cs" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Replace/replace1.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.replace/vb/replace1.vb" id="Snippet1"::: - + [!NOTE] +> This method does not modify the value of the current instance. Instead, it returns a new string in which all occurrences of `oldValue` are replaced by `newValue`. + +This method performs a search to find `oldValue` using the culture and case sensitivity described by `comparisonType`. + +Because this method returns the modified string, you can chain together successive calls to the method to perform multiple replacements on the original string. Method calls are executed from left to right. The following example provides an illustration. + +:::code language="csharp" source="~/snippets/csharp/System/String/Replace/replace1.cs" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Replace/replace1.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.replace/vb/replace1.vb" id="Snippet1"::: + ]]> @@ -11669,22 +11669,22 @@ Because this method returns the modified string, you can chain together successi Returns a new string in which all occurrences of a specified string in the current instance are replaced with another specified string, using the provided culture and case sensitivity. A string that is equivalent to the current string except that all instances of are replaced with . If is not found in the current instance, the method returns the current instance unchanged. - [!NOTE] -> This method does not modify the value of the current instance. Instead, it returns a new string in which all occurrences of `oldValue` are replaced by `newValue`. - -This method performs a search to find `oldValue` using the provided `culture` and `ignoreCase` case sensitivity. - -Because this method returns the modified string, you can chain together successive calls to the method to perform multiple replacements on the original string. Method calls are executed from left to right. The following example provides an illustration. - -:::code language="csharp" source="~/snippets/csharp/System/String/Replace/replace1.cs" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Replace/replace1.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.replace/vb/replace1.vb" id="Snippet1"::: - + [!NOTE] +> This method does not modify the value of the current instance. Instead, it returns a new string in which all occurrences of `oldValue` are replaced by `newValue`. + +This method performs a search to find `oldValue` using the provided `culture` and `ignoreCase` case sensitivity. + +Because this method returns the modified string, you can chain together successive calls to the method to perform multiple replacements on the original string. Method calls are executed from left to right. The following example provides an illustration. + +:::code language="csharp" source="~/snippets/csharp/System/String/Replace/replace1.cs" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Replace/replace1.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.replace/vb/replace1.vb" id="Snippet1"::: + ]]> @@ -11722,18 +11722,18 @@ Because this method returns the modified string, you can chain together successi Replaces all newline sequences in the current string with . A string whose contents match the current string, but with all newline sequences replaced with . - , passing as the replacementText parameter. - -This method is guaranteed O(n) complexity, where n is the length of the input string. - + , passing as the replacementText parameter. + +This method is guaranteed O(n) complexity, where n is the length of the input string. + ]]> @@ -11770,18 +11770,18 @@ This method is guaranteed O(n) complexity, where n is the length of the Replaces all newline sequences in the current string with . A string whose contents match the current string, but with all newline sequences replaced with . - , all newline sequences within the string will be removed. - -It is not recommended that protocol parsers utilize this API. Protocol specifications often mandate specific newline sequences. For example, HTTP/1.1 (RFC 8615) mandates that the request line, status line, and headers lines end with CRLF. Since this API operates over a wide range of newline sequences, a protocol parser utilizing this API could exhibit behaviors unintended by the protocol's authors. - -The list of recognized newline sequences is CR (U+000D), LF (U+000A), CRLF (U+000D U+000A), NEL (U+0085), LS (U+2028), FF (U+000C), and PS (U+2029). This list is given by the Unicode Standard, Sec. 5.8, Recommendation R4 and Table 5-2. - -This method is guaranteed O(n * r) complexity, where n is the length of the input string, and where r is the length of `replacementText`. - + , all newline sequences within the string will be removed. + +It is not recommended that protocol parsers utilize this API. Protocol specifications often mandate specific newline sequences. For example, HTTP/1.1 (RFC 8615) mandates that the request line, status line, and headers lines end with CRLF. Since this API operates over a wide range of newline sequences, a protocol parser utilizing this API could exhibit behaviors unintended by the protocol's authors. + +The list of recognized newline sequences is CR (U+000D), LF (U+000A), CRLF (U+000D U+000A), NEL (U+0085), LS (U+2028), FF (U+000C), and PS (U+2029). This list is given by the Unicode Standard, Sec. 5.8, Recommendation R4 and Table 5-2. + +This method is guaranteed O(n * r) complexity, where n is the length of the input string, and where r is the length of `replacementText`. + ]]> @@ -11797,41 +11797,41 @@ This method is guaranteed O(n * r) complexity, where n is the length of Returns a string array that contains the substrings in this instance that are delimited by elements of a specified string or Unicode character array. - is used to break a delimited string into substrings. You can use either a character array or a string array to specify zero or more delimiting characters or strings. If no delimiting characters are specified, the string is split at white-space characters. - -Overloads of the method allow you to limit the number of substrings returned by the method (the method), to specify whether to include empty strings and/or trim substrings in the result (the and methods), or to do both (the and methods). - -> [!TIP] -> The method is not always the best way to break a delimited string into substrings. If you don't want to extract all of the substrings of a delimited string, or if you want to parse a string based on a pattern instead of a set of delimiter characters, consider using regular expressions, or combine one of the search methods that returns the index of a character with the method. For more information, see [Extract substrings from a string](/dotnet/standard/base-types/divide-up-strings). - -## Example - -The following examples show three different overloads of `String.Split()`. The first example calls the overload and passes in a single delimiter. - -:::code language="csharp" source="~/snippets/csharp/System/String/Split/intro.cs" interactive="try-dotnet-method" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Split/intro.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/system/string.split/intro.vb" id="Snippet1"::: - -As you can see, the period characters (`.`) are included in two of the substrings. If you want to exclude the period characters, you can add the period character as an additional delimiting character. The next example shows how to do this. - -:::code language="csharp" source="~/snippets/csharp/System/String/Split/intro.cs" interactive="try-dotnet-method" id="Snippet2"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Split/intro.fs" id="Snippet2"::: -:::code language="vb" source="~/snippets/visualbasic/system/string.split/intro.vb" id="Snippet2"::: - -The periods are gone from the substrings, but now two extra empty substrings have been included. These empty substring represent the substring between a word and the period that follows it. To omit empty substrings from the resulting array, you can call the - overload and specify - for the `options` parameter. - -:::code language="csharp" source="~/snippets/csharp/System/String/Split/intro.cs" interactive="try-dotnet-method" id="Snippet3"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Split/intro.fs" id="Snippet3"::: -:::code language="vb" source="~/snippets/visualbasic/system/string.split/intro.vb" id="Snippet3"::: - -The sections for the individual overloads of `String.Split()` contain further examples. - + is used to break a delimited string into substrings. You can use either a character array or a string array to specify zero or more delimiting characters or strings. If no delimiting characters are specified, the string is split at white-space characters. + +Overloads of the method allow you to limit the number of substrings returned by the method (the method), to specify whether to include empty strings and/or trim substrings in the result (the and methods), or to do both (the and methods). + +> [!TIP] +> The method is not always the best way to break a delimited string into substrings. If you don't want to extract all of the substrings of a delimited string, or if you want to parse a string based on a pattern instead of a set of delimiter characters, consider using regular expressions, or combine one of the search methods that returns the index of a character with the method. For more information, see [Extract substrings from a string](/dotnet/standard/base-types/divide-up-strings). + +## Example + +The following examples show three different overloads of `String.Split()`. The first example calls the overload and passes in a single delimiter. + +:::code language="csharp" source="~/snippets/csharp/System/String/Split/intro.cs" interactive="try-dotnet-method" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Split/intro.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/system/string.split/intro.vb" id="Snippet1"::: + +As you can see, the period characters (`.`) are included in two of the substrings. If you want to exclude the period characters, you can add the period character as an additional delimiting character. The next example shows how to do this. + +:::code language="csharp" source="~/snippets/csharp/System/String/Split/intro.cs" interactive="try-dotnet-method" id="Snippet2"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Split/intro.fs" id="Snippet2"::: +:::code language="vb" source="~/snippets/visualbasic/system/string.split/intro.vb" id="Snippet2"::: + +The periods are gone from the substrings, but now two extra empty substrings have been included. These empty substring represent the substring between a word and the period that follows it. To omit empty substrings from the resulting array, you can call the + overload and specify + for the `options` parameter. + +:::code language="csharp" source="~/snippets/csharp/System/String/Split/intro.cs" interactive="try-dotnet-method" id="Snippet3"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Split/intro.fs" id="Snippet3"::: +:::code language="vb" source="~/snippets/visualbasic/system/string.split/intro.vb" id="Snippet3"::: + +The sections for the individual overloads of `String.Split()` contain further examples. + ]]> @@ -11894,71 +11894,71 @@ The sections for the individual overloads of `String.Split()` contain further ex Splits a string into substrings based on specified delimiting characters. An array whose elements contain the substrings from this instance that are delimited by one or more characters in . For more information, see the Remarks section. - method to separate it into substrings. - -Delimiter characters are not included in the elements of the returned array. For example, if the separator array includes the character "-" and the value of the current string instance is "aa-bb-cc", the method returns an array that contains three elements: "aa", "bb", and "cc". - -If this instance does not contain any of the characters in `separator`, the returned array consists of a single element that contains this instance. - -Each element of `separator` defines a separate delimiter character. If two delimiters are adjacent, or a delimiter is found at the beginning or end of this instance, the corresponding element in the returned array contains . - -The following table shows some examples. - -| Language | String value | Separator | Returned array | -|--------------|--------------------------|------------------------|--------------------------------| -| C# | "42, 12, 19" | new Char[] {',', ' '} | {"42", "", "12", "", "19"} | -| Visual Basic | "42, 12, 19" | Char() = {","c, " "c}) | {"42", "", "12", "", "19"} | -| C# | "42..12..19." | new Char[] {'.'} | {"42", "", "12", "", "19", ""} | -| Visual Basic | "42..12..19." | Char() = {"."c} | {"42", "", "12", "", "19", ""} | -| C# | "Banana" | new Char[] {'.'} | {"Banana"} | -| Visual Basic | "Banana" | Char() = {"."c} | {"Banana"} | -| C# | "Darb\nSmarba" | new Char[] {} | {"Darb", "Smarba"} | -| Visual Basic | "Darb" & vbLf & "Smarba" | Char() = {} | {"Darb", "Smarba"} | -| C# | "Darb\nSmarba" | null | {"Darb", "Smarba"} | -| Visual Basic | "Darb" & vbLf & "Smarba" | Nothing | {"Darb", "Smarba"} | - -### The separator array - -Each element of separator defines a separate delimiter that consists of a single character. - -If the `separator` argument is `null` or contains no characters, the method treats white-space characters as the delimiters. White-space characters are defined by the Unicode standard, and the method returns `true` if a white-space character is passed to it. - -### String.Split(Char[]) and compiler overload resolution - -Although the single parameter for this overload of is a character array, you can call it with a single character, as the following example shows. - -:::code language="csharp" source="~/snippets/csharp/System/String/Split/compiler-resolution.cs" interactive="try-dotnet-method" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Split/compiler-resolution.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/system/string.split/compiler-resolution.vb" id="Snippet12"::: - -Because the `separator` parameter is decorated with the attribute, compilers will interpret a single character as a single-element character array. This is not the case for other overloads that include a `separator` parameter; you must explicitly pass these overloads a character array as the `separator` argument. - -### Comparison details - -The method extracts the substrings in this string that are delimited by one or more of the characters in the `separator` array, and returns those substrings as elements of an array. - -The method looks for delimiters by performing comparisons using case-sensitive ordinal sort rules. For more information about word, string, and ordinal sorts, see the enumeration. - -### Performance considerations - -The methods allocate memory for the returned array object and a object for each array element. If your application requires optimal performance or if managing memory allocation is critical in your application, consider using the or method. You also have the option of using the method to locate a substring within a string. - -To split a string at a separator character, use the or method to locate a separator character in the string. To split a string at a separator string, use the or method to locate the first character of the separator string. Then use the method to determine whether the characters after that first character are equal to the remaining characters of the separator string. - -In addition, if the same set of characters is used to split strings in multiple method calls, consider creating a single array and referencing it in each method call. This significantly reduces the additional overhead of each method call. - -## Examples - -The following example demonstrates how to extract individual words from a block of text by treating the space character (` `) and tab character (`\t`) as delimiters. The string being split includes both of these characters. - -:::code language="csharp" source="~/snippets/csharp/System/String/Split/basic.cs" interactive="try-dotnet-method" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Split/basic.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/system/string.split/basic.vb" id="Snippet1"::: - + method to separate it into substrings. + +Delimiter characters are not included in the elements of the returned array. For example, if the separator array includes the character "-" and the value of the current string instance is "aa-bb-cc", the method returns an array that contains three elements: "aa", "bb", and "cc". + +If this instance does not contain any of the characters in `separator`, the returned array consists of a single element that contains this instance. + +Each element of `separator` defines a separate delimiter character. If two delimiters are adjacent, or a delimiter is found at the beginning or end of this instance, the corresponding element in the returned array contains . + +The following table shows some examples. + +| Language | String value | Separator | Returned array | +|--------------|--------------------------|------------------------|--------------------------------| +| C# | "42, 12, 19" | new Char[] {',', ' '} | {"42", "", "12", "", "19"} | +| Visual Basic | "42, 12, 19" | Char() = {","c, " "c}) | {"42", "", "12", "", "19"} | +| C# | "42..12..19." | new Char[] {'.'} | {"42", "", "12", "", "19", ""} | +| Visual Basic | "42..12..19." | Char() = {"."c} | {"42", "", "12", "", "19", ""} | +| C# | "Banana" | new Char[] {'.'} | {"Banana"} | +| Visual Basic | "Banana" | Char() = {"."c} | {"Banana"} | +| C# | "Darb\nSmarba" | new Char[] {} | {"Darb", "Smarba"} | +| Visual Basic | "Darb" & vbLf & "Smarba" | Char() = {} | {"Darb", "Smarba"} | +| C# | "Darb\nSmarba" | null | {"Darb", "Smarba"} | +| Visual Basic | "Darb" & vbLf & "Smarba" | Nothing | {"Darb", "Smarba"} | + +### The separator array + +Each element of separator defines a separate delimiter that consists of a single character. + +If the `separator` argument is `null` or contains no characters, the method treats white-space characters as the delimiters. White-space characters are defined by the Unicode standard, and the method returns `true` if a white-space character is passed to it. + +### String.Split(Char[]) and compiler overload resolution + +Although the single parameter for this overload of is a character array, you can call it with a single character, as the following example shows. + +:::code language="csharp" source="~/snippets/csharp/System/String/Split/compiler-resolution.cs" interactive="try-dotnet-method" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Split/compiler-resolution.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/system/string.split/compiler-resolution.vb" id="Snippet12"::: + +Because the `separator` parameter is decorated with the attribute, compilers will interpret a single character as a single-element character array. This is not the case for other overloads that include a `separator` parameter; you must explicitly pass these overloads a character array as the `separator` argument. + +### Comparison details + +The method extracts the substrings in this string that are delimited by one or more of the characters in the `separator` array, and returns those substrings as elements of an array. + +The method looks for delimiters by performing comparisons using case-sensitive ordinal sort rules. For more information about word, string, and ordinal sorts, see the enumeration. + +### Performance considerations + +The methods allocate memory for the returned array object and a object for each array element. If your application requires optimal performance or if managing memory allocation is critical in your application, consider using the or method. You also have the option of using the method to locate a substring within a string. + +To split a string at a separator character, use the or method to locate a separator character in the string. To split a string at a separator string, use the or method to locate the first character of the separator string. Then use the method to determine whether the characters after that first character are equal to the remaining characters of the separator string. + +In addition, if the same set of characters is used to split strings in multiple method calls, consider creating a single array and referencing it in each method call. This significantly reduces the additional overhead of each method call. + +## Examples + +The following example demonstrates how to extract individual words from a block of text by treating the space character (` `) and tab character (`\t`) as delimiters. The string being split includes both of these characters. + +:::code language="csharp" source="~/snippets/csharp/System/String/Split/basic.cs" interactive="try-dotnet-method" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Split/basic.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/system/string.split/basic.vb" id="Snippet1"::: + ]]> @@ -12070,50 +12070,50 @@ The following example demonstrates how to extract individual words from a block Splits a string into a maximum number of substrings based on specified delimiting characters. An array whose elements contain the substrings in this instance that are delimited by one or more characters in . For more information, see the Remarks section. - method returns `true` if they are passed to it. - -Each element of `separator` defines a separate delimiter character. If two delimiters are adjacent, or a delimiter is found at the beginning or end of this instance, the corresponding array element contains . - -If there are more than `count` substrings in this instance, the first `count - 1` substrings are returned in the first `count - 1` elements of the return value, and the remaining characters in this instance are returned in the last element of the return value. - -If `count` is greater than the number of substrings, the available substrings are returned and no exception is thrown. - -The following table shows some examples. - -| Language | String value | Separator | Returned array | -|--------------|--------------------------|------------------------|--------------------------------| -| C# | "42, 12, 19" | new Char[] {',', ' '} | {"42", "", "12", "", "19"} | -| Visual Basic | "42, 12, 19" | Char() = {","c, " "c}) | {"42", "", "12", "", "19"} | -| C# | "42..12..19." | new Char[] {'.'} | {"42", "", "12", "", "19", ""} | -| Visual Basic | "42..12..19." | Char() = {"."c} | {"42", "", "12", "", "19", ""} | -| C# | "Banana" | new Char[] {'.'} | {"Banana"} | -| Visual Basic | "Banana" | Char() = {"."c} | {"Banana"} | -| C# | "Darb\nSmarba" | new Char[] {} | {"Darb", "Smarba"} | -| Visual Basic | "Darb" & vbLf & "Smarba" | Char() = {} | {"Darb", "Smarba"} | -| C# | "Darb\nSmarba" | null | {"Darb", "Smarba"} | -| Visual Basic | "Darb" & vbLf & "Smarba" | Nothing | {"Darb", "Smarba"} | - -### Performance considerations -The methods allocate memory for the returned array object and a object for each array element. If your application requires optimal performance or if managing memory allocation is critical in your application, consider using the or method, and optionally the method, to locate a substring within a string. - -If you are splitting a string at a separator character, use the or method to locate a separator character in the string. If you are splitting a string at a separator string, use the or method to locate the first character of the separator string. Then use the method to determine whether the characters after that first character are equal to the remaining characters of the separator string. - -In addition, if the same set of characters is used to split strings in multiple method calls, consider creating a single array and referencing it in each method call. This significantly reduces the additional overhead of each method call. - -## Examples -The following example demonstrates how `count` can be used to limit the number of strings returned by . - -:::code language="csharp" source="~/snippets/csharp/System/String/Split/limit.cs" interactive="try-dotnet-method" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Split/limit.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/system/string.split/limit.vb" id="Snippet1"::: - + method returns `true` if they are passed to it. + +Each element of `separator` defines a separate delimiter character. If two delimiters are adjacent, or a delimiter is found at the beginning or end of this instance, the corresponding array element contains . + +If there are more than `count` substrings in this instance, the first `count - 1` substrings are returned in the first `count - 1` elements of the return value, and the remaining characters in this instance are returned in the last element of the return value. + +If `count` is greater than the number of substrings, the available substrings are returned and no exception is thrown. + +The following table shows some examples. + +| Language | String value | Separator | Returned array | +|--------------|--------------------------|------------------------|--------------------------------| +| C# | "42, 12, 19" | new Char[] {',', ' '} | {"42", "", "12", "", "19"} | +| Visual Basic | "42, 12, 19" | Char() = {","c, " "c}) | {"42", "", "12", "", "19"} | +| C# | "42..12..19." | new Char[] {'.'} | {"42", "", "12", "", "19", ""} | +| Visual Basic | "42..12..19." | Char() = {"."c} | {"42", "", "12", "", "19", ""} | +| C# | "Banana" | new Char[] {'.'} | {"Banana"} | +| Visual Basic | "Banana" | Char() = {"."c} | {"Banana"} | +| C# | "Darb\nSmarba" | new Char[] {} | {"Darb", "Smarba"} | +| Visual Basic | "Darb" & vbLf & "Smarba" | Char() = {} | {"Darb", "Smarba"} | +| C# | "Darb\nSmarba" | null | {"Darb", "Smarba"} | +| Visual Basic | "Darb" & vbLf & "Smarba" | Nothing | {"Darb", "Smarba"} | + +### Performance considerations +The methods allocate memory for the returned array object and a object for each array element. If your application requires optimal performance or if managing memory allocation is critical in your application, consider using the or method, and optionally the method, to locate a substring within a string. + +If you are splitting a string at a separator character, use the or method to locate a separator character in the string. If you are splitting a string at a separator string, use the or method to locate the first character of the separator string. Then use the method to determine whether the characters after that first character are equal to the remaining characters of the separator string. + +In addition, if the same set of characters is used to split strings in multiple method calls, consider creating a single array and referencing it in each method call. This significantly reduces the additional overhead of each method call. + +## Examples +The following example demonstrates how `count` can be used to limit the number of strings returned by . + +:::code language="csharp" source="~/snippets/csharp/System/String/Split/limit.cs" interactive="try-dotnet-method" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Split/limit.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/system/string.split/limit.vb" id="Snippet1"::: + ]]> @@ -12194,58 +12194,58 @@ The following example demonstrates how `count` can be used to limit the number o Splits a string into substrings based on specified delimiting characters and options. An array whose elements contain the substrings in this string that are delimited by one or more characters in . For more information, see the Remarks section. - and the length of this instance is zero, the method returns an empty array. - -Each element of `separator` defines a separate delimiter that consists of a single character. If the `options` argument is , and two delimiters are adjacent or a delimiter is found at the beginning or end of this instance, the corresponding array element contains . For example, if `separator` includes two elements, `'-'` and `'_'`, the value of the string instance is "-\_aa-\_", and the value of the `options` argument is , the method returns a string array with the following five elements: - -1. , which represents the empty string that precedes the "-" character at index 0. - -2. , which represents the empty string between the "-" character at index 0 and the "_" character at index 1. - -3. "aa". - -4. , which represents the empty string that follows the "-" character at index 4. - -5. , which represents the empty string that follows the "_" character at index 5. - -### The separator array - -If the `separator` parameter is `null` or contains no characters, white-space characters are assumed to be the delimiters. White-space characters are defined by the Unicode standard and the method returns `true` if they are passed to it. - -To pass `null` for the `char[] separator` parameter, you must indicate the type of the `null` to disambiguate the call from some other overloads, such as . The following example shows several ways to unambiguously identify this overload. - -:::code language="csharp" source="~/snippets/csharp/System/String/Split/identify.cs" interactive="try-dotnet-method" id="Snippet5"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Split/identify.fs" id="Snippet5"::: -:::code language="vb" source="~/snippets/visualbasic/system/string.split/identify.vb" id="Snippet5"::: - -### Comparison details -The method extracts the substrings in this string that are delimited by one or more of the characters in the `separator` parameter, and returns those substrings as elements of an array. - -The method looks for delimiters by performing comparisons using case-sensitive ordinal sort rules. For more information about word, string, and ordinal sorts, see the enumeration. - -### Performance considerations -The methods allocate memory for the returned array object and a object for each array element. If your application requires optimal performance or if managing memory allocation is critical in your application, consider using the or method, and optionally the method, to locate a substring within a string. - -If you are splitting a string at a separator character, use the or method to locate a separator character in the string. If you are splitting a string at a separator string, use the or method to locate the first character of the separator string. Then use the method to determine whether the characters after that first character are equal to the remaining characters of the separator string. - -In addition, if the same set of characters is used to split strings in multiple method calls, consider creating a single array and referencing it in each method call. This significantly reduces the additional overhead of each method call. - -## Examples -The following example uses the enumeration to include or exclude substrings generated by the method. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.split3/CPP/omit.cpp" id="Snippet1"::: -:::code language="csharp" source="~/snippets/csharp/System/String/Split/options.cs" interactive="try-dotnet-method" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Split/options.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/system/string.split/omit.vb" id="Snippet1"::: - + and the length of this instance is zero, the method returns an empty array. + +Each element of `separator` defines a separate delimiter that consists of a single character. If the `options` argument is , and two delimiters are adjacent or a delimiter is found at the beginning or end of this instance, the corresponding array element contains . For example, if `separator` includes two elements, `'-'` and `'_'`, the value of the string instance is "-\_aa-\_", and the value of the `options` argument is , the method returns a string array with the following five elements: + +1. , which represents the empty string that precedes the "-" character at index 0. + +2. , which represents the empty string between the "-" character at index 0 and the "_" character at index 1. + +3. "aa". + +4. , which represents the empty string that follows the "-" character at index 4. + +5. , which represents the empty string that follows the "_" character at index 5. + +### The separator array + +If the `separator` parameter is `null` or contains no characters, white-space characters are assumed to be the delimiters. White-space characters are defined by the Unicode standard and the method returns `true` if they are passed to it. + +To pass `null` for the `char[] separator` parameter, you must indicate the type of the `null` to disambiguate the call from some other overloads, such as . The following example shows several ways to unambiguously identify this overload. + +:::code language="csharp" source="~/snippets/csharp/System/String/Split/identify.cs" interactive="try-dotnet-method" id="Snippet5"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Split/identify.fs" id="Snippet5"::: +:::code language="vb" source="~/snippets/visualbasic/system/string.split/identify.vb" id="Snippet5"::: + +### Comparison details +The method extracts the substrings in this string that are delimited by one or more of the characters in the `separator` parameter, and returns those substrings as elements of an array. + +The method looks for delimiters by performing comparisons using case-sensitive ordinal sort rules. For more information about word, string, and ordinal sorts, see the enumeration. + +### Performance considerations +The methods allocate memory for the returned array object and a object for each array element. If your application requires optimal performance or if managing memory allocation is critical in your application, consider using the or method, and optionally the method, to locate a substring within a string. + +If you are splitting a string at a separator character, use the or method to locate a separator character in the string. If you are splitting a string at a separator string, use the or method to locate the first character of the separator string. Then use the method to determine whether the characters after that first character are equal to the remaining characters of the separator string. + +In addition, if the same set of characters is used to split strings in multiple method calls, consider creating a single array and referencing it in each method call. This significantly reduces the additional overhead of each method call. + +## Examples +The following example uses the enumeration to include or exclude substrings generated by the method. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.split3/CPP/omit.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Split/options.cs" interactive="try-dotnet-method" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Split/options.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/system/string.split/omit.vb" id="Snippet1"::: + ]]> @@ -12364,78 +12364,78 @@ The following example uses the enumeration to i Splits a string into substrings based on a specified delimiting string and, optionally, options. An array whose elements contain the substrings in this string that are delimited by one or more strings in . For more information, see the Remarks section. - method to separate it into substrings. - -Delimiter strings are not included in the elements of the returned array. For example, if the `separator` array includes the string "--" and the value of the current string instance is "aa--bb--cc", the method returns an array that contains three elements: "aa", "bb", and "cc". - -If this instance does not contain any of the strings in `separator`, the returned array consists of a single element that contains this instance. - -If the `options` parameter is and the length of this instance is zero, the method returns an empty array. - -Each element of `separator` defines a separate delimiter that consists of one or more characters. If the `options` argument is , and two delimiters are adjacent or a delimiter is found at the beginning or end of this instance, the corresponding array element contains . For example, if `separator` includes two elements, "-" and "\_", the value of the string instance is "-\_aa-\_", and the value of the `options` argument is , the method returns a string array with the following five elements: - -1. , which represents the empty string that precedes the "-" substring at index 0. - -2. , which represents the empty string between the "-" substring at index 0 and the "_" substring at index 1. - -3. "aa". - -4. , which represents the empty string that follows the "-" substring at index 4. - -5. , which represents the empty string that follows the "_" substring at index 5. - -### The separator array - -If any of the elements in `separator` consists of multiple characters, the entire substring is considered a delimiter. For example, if one of the elements in `separator` is "10", attempting to split the string "This10is10a10string." returns the following four-element array: { "This", "is", "a", "string." }. - -If the `separator` parameter is `null` or contains no non-empty strings, white-space characters are assumed to be the delimiters. White-space characters are defined by the Unicode standard and the method returns `true` if they are passed to it. - -To pass `null` for the `string[] separator` parameter, you must indicate the type of the `null` to disambiguate the call from some other overloads, such as . The following example shows several ways to unambiguously identify this overload. - -:::code language="csharp" source="~/snippets/csharp/System/String/Split/identify.cs" interactive="try-dotnet-method" id="Snippet6"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Split/identify.fs" id="Snippet6"::: -:::code language="vb" source="~/snippets/visualbasic/system/string.split/identify.vb" id="Snippet6"::: - -### Comparison details -The method extracts the substrings in this string that are delimited by one or more of the strings in the `separator` parameter, and returns those substrings as elements of an array. - -The method looks for delimiters by performing comparisons using case-sensitive ordinal sort rules. For more information about word, string, and ordinal sorts, see the enumeration. - -The method ignores any element of `separator` whose value is `null` or the empty string (""). - -To avoid ambiguous results when strings in `separator` have characters in common, the operation proceeds from the beginning to the end of the value of the instance, and matches the first element in `separator` that is equal to a delimiter in the instance. The order in which substrings are encountered in the instance takes precedence over the order of elements in `separator`. - -For example, consider an instance whose value is "abcdef". If the first element in `separator` was "ef" and the second element was "bcde", the result of the split operation would be a string array that contains two elements, "a" and "f". This is because the substring in the instance, "bcde", is encountered and matches an element in `separator` before the substring "f" is encountered. - -However, if the first element of `separator` was "bcd" and the second element was "bc", the result of the split operation would be a string array that contains two elements, "a" and "ef". This is because "bcd" is the first delimiter in `separator` that matches a delimiter in the instance. If the order of the separators was reversed so the first element was "bc" and the second element was "bcd", the result would be a string array that contains two elements, "a" and "def". - -### Performance considerations -The methods allocate memory for the returned array object and a object for each array element. If your application requires optimal performance or if managing memory allocation is critical in your application, consider using the or method, and optionally the method, to locate a substring within a string. - -If you are splitting a string at a separator character, use the or method to locate a separator character in the string. If you are splitting a string at a separator string, use the or method to locate the first character of the separator string. Then use the method to determine whether the characters after that first character are equal to the remaining characters of the separator string. - -In addition, if the same set of characters is used to split strings in multiple method calls, consider creating a single array and referencing it in each method call. This significantly reduces the additional overhead of each method call. - -## Examples - -The following example illustrates the difference in the arrays returned by calling a string's method with its `options` parameter equal to and . - -:::code language="csharp" source="~/snippets/csharp/System/String/Split/options.cs" interactive="try-dotnet-method" id="Snippet2"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Split/options.fs" id="Snippet2"::: -:::code language="vb" source="~/snippets/visualbasic/system/string.split/options.vb" id="Snippet1"::: - -The following example defines an array of separators that include punctuation and white-space characters. Passing this array along with a value of to the method returns an array that consists of the individual words from the string. - -:::code language="csharp" source="~/snippets/csharp/System/String/Split/options.cs" interactive="try-dotnet-method" id="Snippet3"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Split/options.fs" id="Snippet3"::: -:::code language="vb" source="~/snippets/visualbasic/system/string.split/options.vb" id="Snippet7"::: - -Note that the method is called with the `options` argument set to . This prevents the returned array from including values that represent empty substring matches between punctuation marks and white-space characters. - + method to separate it into substrings. + +Delimiter strings are not included in the elements of the returned array. For example, if the `separator` array includes the string "--" and the value of the current string instance is "aa--bb--cc", the method returns an array that contains three elements: "aa", "bb", and "cc". + +If this instance does not contain any of the strings in `separator`, the returned array consists of a single element that contains this instance. + +If the `options` parameter is and the length of this instance is zero, the method returns an empty array. + +Each element of `separator` defines a separate delimiter that consists of one or more characters. If the `options` argument is , and two delimiters are adjacent or a delimiter is found at the beginning or end of this instance, the corresponding array element contains . For example, if `separator` includes two elements, "-" and "\_", the value of the string instance is "-\_aa-\_", and the value of the `options` argument is , the method returns a string array with the following five elements: + +1. , which represents the empty string that precedes the "-" substring at index 0. + +2. , which represents the empty string between the "-" substring at index 0 and the "_" substring at index 1. + +3. "aa". + +4. , which represents the empty string that follows the "-" substring at index 4. + +5. , which represents the empty string that follows the "_" substring at index 5. + +### The separator array + +If any of the elements in `separator` consists of multiple characters, the entire substring is considered a delimiter. For example, if one of the elements in `separator` is "10", attempting to split the string "This10is10a10string." returns the following four-element array: { "This", "is", "a", "string." }. + +If the `separator` parameter is `null` or contains no non-empty strings, white-space characters are assumed to be the delimiters. White-space characters are defined by the Unicode standard and the method returns `true` if they are passed to it. + +To pass `null` for the `string[] separator` parameter, you must indicate the type of the `null` to disambiguate the call from some other overloads, such as . The following example shows several ways to unambiguously identify this overload. + +:::code language="csharp" source="~/snippets/csharp/System/String/Split/identify.cs" interactive="try-dotnet-method" id="Snippet6"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Split/identify.fs" id="Snippet6"::: +:::code language="vb" source="~/snippets/visualbasic/system/string.split/identify.vb" id="Snippet6"::: + +### Comparison details +The method extracts the substrings in this string that are delimited by one or more of the strings in the `separator` parameter, and returns those substrings as elements of an array. + +The method looks for delimiters by performing comparisons using case-sensitive ordinal sort rules. For more information about word, string, and ordinal sorts, see the enumeration. + +The method ignores any element of `separator` whose value is `null` or the empty string (""). + +To avoid ambiguous results when strings in `separator` have characters in common, the operation proceeds from the beginning to the end of the value of the instance, and matches the first element in `separator` that is equal to a delimiter in the instance. The order in which substrings are encountered in the instance takes precedence over the order of elements in `separator`. + +For example, consider an instance whose value is "abcdef". If the first element in `separator` was "ef" and the second element was "bcde", the result of the split operation would be a string array that contains two elements, "a" and "f". This is because the substring in the instance, "bcde", is encountered and matches an element in `separator` before the substring "f" is encountered. + +However, if the first element of `separator` was "bcd" and the second element was "bc", the result of the split operation would be a string array that contains two elements, "a" and "ef". This is because "bcd" is the first delimiter in `separator` that matches a delimiter in the instance. If the order of the separators was reversed so the first element was "bc" and the second element was "bcd", the result would be a string array that contains two elements, "a" and "def". + +### Performance considerations +The methods allocate memory for the returned array object and a object for each array element. If your application requires optimal performance or if managing memory allocation is critical in your application, consider using the or method, and optionally the method, to locate a substring within a string. + +If you are splitting a string at a separator character, use the or method to locate a separator character in the string. If you are splitting a string at a separator string, use the or method to locate the first character of the separator string. Then use the method to determine whether the characters after that first character are equal to the remaining characters of the separator string. + +In addition, if the same set of characters is used to split strings in multiple method calls, consider creating a single array and referencing it in each method call. This significantly reduces the additional overhead of each method call. + +## Examples + +The following example illustrates the difference in the arrays returned by calling a string's method with its `options` parameter equal to and . + +:::code language="csharp" source="~/snippets/csharp/System/String/Split/options.cs" interactive="try-dotnet-method" id="Snippet2"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Split/options.fs" id="Snippet2"::: +:::code language="vb" source="~/snippets/visualbasic/system/string.split/options.vb" id="Snippet1"::: + +The following example defines an array of separators that include punctuation and white-space characters. Passing this array along with a value of to the method returns an array that consists of the individual words from the string. + +:::code language="csharp" source="~/snippets/csharp/System/String/Split/options.cs" interactive="try-dotnet-method" id="Snippet3"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Split/options.fs" id="Snippet3"::: +:::code language="vb" source="~/snippets/visualbasic/system/string.split/options.vb" id="Snippet7"::: + +Note that the method is called with the `options` argument set to . This prevents the returned array from including values that represent empty substring matches between punctuation marks and white-space characters. + ]]> @@ -12482,16 +12482,16 @@ Note that the method is called with the `options` argument set to A character that delimits the substrings in this instance. The maximum number of elements expected in the array. A bitwise combination of the enumeration values that specifies whether to trim substrings and include empty substrings. - Splits a string into a maximum number of substrings based on a specified delimiting character and, optionally, options. + Splits a string into a maximum number of substrings based on a specified delimiting character and, optionally, options. Splits a string into a maximum number of substrings based on the provided character separator, optionally omitting empty substrings from the result. An array that contains at most substrings from this instance that are delimited by . - @@ -12559,46 +12559,46 @@ If the string has already been split `count` - 1 times, but the end of the strin Splits a string into a maximum number of substrings based on specified delimiting characters and, optionally, options. An array that contains the substrings in this string that are delimited by one or more characters in . For more information, see the Remarks section. - method returns `true` if they are passed to it. - -To pass `null` for the `char[] separator` parameter, you must indicate the type of the `null` to disambiguate the call from some other overloads, such as . The following example shows several ways to unambiguously identify this overload. - -:::code language="csharp" source="~/snippets/csharp/System/String/Split/identify.cs" interactive="try-dotnet-method" id="Snippet3"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Split/identify.fs" id="Snippet3"::: -:::code language="vb" source="~/snippets/visualbasic/system/string.split/identify.vb" id="Snippet3"::: - -If the `count` parameter is zero, or the `options` parameter is and the length of this instance is zero, an empty array is returned. - -Each element of `separator` defines a separate delimiter character. If the `options` parameter is , and two delimiters are adjacent or a delimiter is found at the beginning or end of this instance, the corresponding array element contains . - -If there are more than `count` substrings in this instance, the first `count` minus 1 substrings are returned in the first `count` minus 1 elements of the return value, and the remaining characters in this instance are returned in the last element of the return value. - -If `count` is greater than the number of substrings, the available substrings are returned and no exception is thrown. - -### Performance considerations -The methods allocate memory for the returned array object and a object for each array element. If your application requires optimal performance or if managing memory allocation is critical in your application, consider using the or method, and optionally the method, to locate a substring within a string. - -If you are splitting a string at a separator character, use the or method to locate a separator character in the string. If you are splitting a string at a separator string, use the or method to locate the first character of the separator string. Then use the method to determine whether the characters after that first character are equal to the remaining characters of the separator string. - -In addition, if the same set of characters is used to split strings in multiple method calls, consider creating a single array and referencing it in each method call. This significantly reduces the additional overhead of each method call. - -## Examples - -The following example uses the enumeration to include or exclude substrings generated by the method. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.split3/CPP/omit.cpp" id="Snippet1"::: -:::code language="csharp" source="~/snippets/csharp/System/String/Split/options.cs" interactive="try-dotnet-method" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Split/options.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/system/string.split/omit.vb" id="Snippet1"::: - + method returns `true` if they are passed to it. + +To pass `null` for the `char[] separator` parameter, you must indicate the type of the `null` to disambiguate the call from some other overloads, such as . The following example shows several ways to unambiguously identify this overload. + +:::code language="csharp" source="~/snippets/csharp/System/String/Split/identify.cs" interactive="try-dotnet-method" id="Snippet3"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Split/identify.fs" id="Snippet3"::: +:::code language="vb" source="~/snippets/visualbasic/system/string.split/identify.vb" id="Snippet3"::: + +If the `count` parameter is zero, or the `options` parameter is and the length of this instance is zero, an empty array is returned. + +Each element of `separator` defines a separate delimiter character. If the `options` parameter is , and two delimiters are adjacent or a delimiter is found at the beginning or end of this instance, the corresponding array element contains . + +If there are more than `count` substrings in this instance, the first `count` minus 1 substrings are returned in the first `count` minus 1 elements of the return value, and the remaining characters in this instance are returned in the last element of the return value. + +If `count` is greater than the number of substrings, the available substrings are returned and no exception is thrown. + +### Performance considerations +The methods allocate memory for the returned array object and a object for each array element. If your application requires optimal performance or if managing memory allocation is critical in your application, consider using the or method, and optionally the method, to locate a substring within a string. + +If you are splitting a string at a separator character, use the or method to locate a separator character in the string. If you are splitting a string at a separator string, use the or method to locate the first character of the separator string. Then use the method to determine whether the characters after that first character are equal to the remaining characters of the separator string. + +In addition, if the same set of characters is used to split strings in multiple method calls, consider creating a single array and referencing it in each method call. This significantly reduces the additional overhead of each method call. + +## Examples + +The following example uses the enumeration to include or exclude substrings generated by the method. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.split3/CPP/omit.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Split/options.cs" interactive="try-dotnet-method" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Split/options.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/system/string.split/omit.vb" id="Snippet1"::: + ]]> @@ -12658,12 +12658,12 @@ The following example uses the enumeration to i Splits a string into a maximum number of substrings based on a specified delimiting string and, optionally, options. An array that contains at most substrings from this instance that are delimited by . - @@ -12731,63 +12731,63 @@ If the string has already been split `count` - 1 times, but the end of the strin Splits a string into a maximum number of substrings based on specified delimiting strings and, optionally, options. An array whose elements contain the substrings in this string that are delimited by one or more strings in . For more information, see the Remarks section. - method returns `true` if they are passed to it. - -To pass `null` for the `string[] separator` parameter, you must indicate the type of the `null` to disambiguate the call from some other overloads, such as . The following example shows several ways to unambiguously identify this overload. - -:::code language="csharp" source="~/snippets/csharp/System/String/Split/identify.cs" interactive="try-dotnet-method" id="Snippet4"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Split/identify.fs" id="Snippet4"::: -:::code language="vb" source="~/snippets/visualbasic/system/string.split/identify.vb" id="Snippet4"::: - -If the `count` parameter is zero, or the `options` parameter is and the length of this instance is zero, an empty array is returned. - -Each element of `separator` defines a separate delimiter that consists of one or more characters. If the `options` parameter is , and two delimiters are adjacent or a delimiter is found at the beginning or end of this instance, the corresponding array element contains . - -If there are more than `count` substrings in this instance, the first `count` minus 1 substrings are returned in the first `count` minus 1 elements of the return value, and the remaining characters in this instance are returned in the last element of the return value. - -If `count` is greater than the number of substrings, the available substrings are returned and no exception is thrown. - -### The separator array - -If any of the elements in `separator` consists of multiple characters, the entire substring is considered a delimiter. For example, if one of the elements in `separator` is "10", attempting to split the string "This10is10a10string." returns this four-element array: { "This", "is", "a", "string." }. - -### Comparison details -The method extracts the substrings in this string that are delimited by one or more of the strings in the `separator` parameter, and returns those substrings as elements of an array. - -The method looks for delimiters by performing comparisons using case-sensitive ordinal sort rules. For more information about word, string, and ordinal sorts, see the enumeration. - -The method ignores any element of `separator` whose value is `null` or the empty string (""). - -To avoid ambiguous results when strings in `separator` have characters in common, the method proceeds from the beginning to the end of the value of the instance, and matches the first element in `separator` that is equal to a delimiter in the instance. The order in which substrings are encountered in the instance takes precedence over the order of elements in `separator`. - -For example, consider an instance whose value is "abcdef". If the first element in `separator` was "ef" and the second element was "bcde", the result of the split operation would be "a" and "f". This is because the substring in the instance, "bcde", is encountered and matches an element in `separator` before the substring "f" is encountered. - -However, if the first element of `separator` was "bcd" and the second element was "bc", the result of the split operation would be "a" and "ef". This is because "bcd" is the first delimiter in `separator` that matches a delimiter in the instance. If the order of the separators was reversed so the first element was "bc" and the second element was "bcd", the result would be "a" and "def". - -### Performance considerations -The methods allocate memory for the returned array object and a object for each array element. If your application requires optimal performance or if managing memory allocation is critical in your application, consider using the or method, and optionally the method, to locate a substring within a string. - -If you are splitting a string at a separator character, use the or method to locate a separator character in the string. If you are splitting a string at a separator string, use the or method to locate the first character of the separator string. Then use the method to determine whether the characters after that first character are equal to the remaining characters of the separator string. - -In addition, if the same set of characters is used to split strings in multiple method calls, consider creating a single array and referencing it in each method call. This significantly reduces the additional overhead of each method call. - -## Examples - -The following example uses the enumeration to include or exclude substrings generated by the method. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.split3/CPP/omit.cpp" id="Snippet1"::: -:::code language="csharp" source="~/snippets/csharp/System/String/Split/options.cs" interactive="try-dotnet-method" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Split/options.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/system/string.split/omit.vb" id="Snippet1"::: - + method returns `true` if they are passed to it. + +To pass `null` for the `string[] separator` parameter, you must indicate the type of the `null` to disambiguate the call from some other overloads, such as . The following example shows several ways to unambiguously identify this overload. + +:::code language="csharp" source="~/snippets/csharp/System/String/Split/identify.cs" interactive="try-dotnet-method" id="Snippet4"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Split/identify.fs" id="Snippet4"::: +:::code language="vb" source="~/snippets/visualbasic/system/string.split/identify.vb" id="Snippet4"::: + +If the `count` parameter is zero, or the `options` parameter is and the length of this instance is zero, an empty array is returned. + +Each element of `separator` defines a separate delimiter that consists of one or more characters. If the `options` parameter is , and two delimiters are adjacent or a delimiter is found at the beginning or end of this instance, the corresponding array element contains . + +If there are more than `count` substrings in this instance, the first `count` minus 1 substrings are returned in the first `count` minus 1 elements of the return value, and the remaining characters in this instance are returned in the last element of the return value. + +If `count` is greater than the number of substrings, the available substrings are returned and no exception is thrown. + +### The separator array + +If any of the elements in `separator` consists of multiple characters, the entire substring is considered a delimiter. For example, if one of the elements in `separator` is "10", attempting to split the string "This10is10a10string." returns this four-element array: { "This", "is", "a", "string." }. + +### Comparison details +The method extracts the substrings in this string that are delimited by one or more of the strings in the `separator` parameter, and returns those substrings as elements of an array. + +The method looks for delimiters by performing comparisons using case-sensitive ordinal sort rules. For more information about word, string, and ordinal sorts, see the enumeration. + +The method ignores any element of `separator` whose value is `null` or the empty string (""). + +To avoid ambiguous results when strings in `separator` have characters in common, the method proceeds from the beginning to the end of the value of the instance, and matches the first element in `separator` that is equal to a delimiter in the instance. The order in which substrings are encountered in the instance takes precedence over the order of elements in `separator`. + +For example, consider an instance whose value is "abcdef". If the first element in `separator` was "ef" and the second element was "bcde", the result of the split operation would be "a" and "f". This is because the substring in the instance, "bcde", is encountered and matches an element in `separator` before the substring "f" is encountered. + +However, if the first element of `separator` was "bcd" and the second element was "bc", the result of the split operation would be "a" and "ef". This is because "bcd" is the first delimiter in `separator` that matches a delimiter in the instance. If the order of the separators was reversed so the first element was "bc" and the second element was "bcd", the result would be "a" and "def". + +### Performance considerations +The methods allocate memory for the returned array object and a object for each array element. If your application requires optimal performance or if managing memory allocation is critical in your application, consider using the or method, and optionally the method, to locate a substring within a string. + +If you are splitting a string at a separator character, use the or method to locate a separator character in the string. If you are splitting a string at a separator string, use the or method to locate the first character of the separator string. Then use the method to determine whether the characters after that first character are equal to the remaining characters of the separator string. + +In addition, if the same set of characters is used to split strings in multiple method calls, consider creating a single array and referencing it in each method call. This significantly reduces the additional overhead of each method call. + +## Examples + +The following example uses the enumeration to include or exclude substrings generated by the method. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.split3/CPP/omit.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Split/options.cs" interactive="try-dotnet-method" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Split/options.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/system/string.split/omit.vb" id="Snippet1"::: + ]]> @@ -12837,12 +12837,12 @@ The following example uses the enumeration to i if matches the beginning of this string; otherwise, . - @@ -12900,23 +12900,23 @@ This method performs an ordinal (case-sensitive and culture-insensitive) compari if matches the beginning of this string; otherwise, . - ), must be a reference to this same instance, or must match the beginning of this instance. - -This method performs a word (case-sensitive and culture-sensitive) comparison using the current culture. - -## Examples - -The following example defines a `StripStartTags` method that uses the method to remove HTML start tags from the beginning of a string. Note that the `StripStartTags` method is called recursively to ensure that multiple HTML start tags at the beginning of the line are removed. The example does not remove HTML tags embedded in a string. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringstartswith/CPP/stringstartswith.cpp" id="Snippet1"::: -:::code language="csharp" source="~/snippets/csharp/System/String/StartsWith/stringstartswith.cs" interactive="try-dotnet" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/StartsWith/stringstartswith.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringstartswith/VB/stringstartswith.vb" id="Snippet1"::: - + ), must be a reference to this same instance, or must match the beginning of this instance. + +This method performs a word (case-sensitive and culture-sensitive) comparison using the current culture. + +## Examples + +The following example defines a `StripStartTags` method that uses the method to remove HTML start tags from the beginning of a string. Note that the `StripStartTags` method is called recursively to ensure that multiple HTML start tags at the beginning of the line are removed. The example does not remove HTML tags embedded in a string. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/stringstartswith/CPP/stringstartswith.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/StartsWith/stringstartswith.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/StartsWith/stringstartswith.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/stringstartswith/VB/stringstartswith.vb" id="Snippet1"::: + ]]> @@ -12985,26 +12985,26 @@ The following example defines a `StripStartTags` method that uses the if this instance begins with ; otherwise, . - method compares the `value` parameter to the substring at the beginning of this string and returns a value that indicates whether they are equal. To be equal, `value` must be a reference to this same string, must be the empty string (""), or must match the beginning of this string. The type of comparison performed by the method depends on the value of the `comparisonType` parameter. The comparison can use the conventions of the current culture ( and ) or the invariant culture ( and ), or it can consist of a character-by-character comparison of code points ( or ). The comparison can also be case-sensitive (, , or ), or it can ignore case (, , ). - -## Examples -The following example searches for the string "the" at the beginning of a longer string that begins with the word "The". As the output from the example shows, a call to the method that performs a culture-insensitive but case-sensitive comparison fails to match the string, while a call that performs a culture- and case-insensitive comparison matches the string. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.string.startswith/cpp/StartsWith2.cpp" id="Snippet2"::: -:::code language="csharp" source="~/snippets/csharp/System/String/StartsWith/StartsWith2.cs" interactive="try-dotnet" id="Snippet2"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/StartsWith/StartsWith2.fs" id="Snippet2"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.startswith/vb/StartsWith2.vb" id="Snippet2"::: - -The following example determines whether a string starts with a particular substring. It initializes a two-dimensional string array. The first element in the second dimension contains a string, and the second element contains the string to search for at the start of the first string. The results are affected by the choice of culture, whether case is ignored, and whether an ordinal comparison is performed. Note that when the string instance contains a ligature, culture-sensitive comparisons with its consecutive characters successfully match. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.string.startswith/cpp/startswith1.cpp" id="Snippet1"::: -:::code language="csharp" source="~/snippets/csharp/System/String/StartsWith/startswith1.cs" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/StartsWith/startswith1.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.startswith/vb/startswith1.vb" id="Snippet1"::: - + method compares the `value` parameter to the substring at the beginning of this string and returns a value that indicates whether they are equal. To be equal, `value` must be a reference to this same string, must be the empty string (""), or must match the beginning of this string. The type of comparison performed by the method depends on the value of the `comparisonType` parameter. The comparison can use the conventions of the current culture ( and ) or the invariant culture ( and ), or it can consist of a character-by-character comparison of code points ( or ). The comparison can also be case-sensitive (, , or ), or it can ignore case (, , ). + +## Examples +The following example searches for the string "the" at the beginning of a longer string that begins with the word "The". As the output from the example shows, a call to the method that performs a culture-insensitive but case-sensitive comparison fails to match the string, while a call that performs a culture- and case-insensitive comparison matches the string. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.string.startswith/cpp/StartsWith2.cpp" id="Snippet2"::: +:::code language="csharp" source="~/snippets/csharp/System/String/StartsWith/StartsWith2.cs" interactive="try-dotnet" id="Snippet2"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/StartsWith/StartsWith2.fs" id="Snippet2"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.startswith/vb/StartsWith2.vb" id="Snippet2"::: + +The following example determines whether a string starts with a particular substring. It initializes a two-dimensional string array. The first element in the second dimension contains a string, and the second element contains the string to search for at the start of the first string. The results are affected by the choice of culture, whether case is ignored, and whether an ordinal comparison is performed. Note that when the string instance contains a ligature, culture-sensitive comparisons with its consecutive characters successfully match. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.string.startswith/cpp/startswith1.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/StartsWith/startswith1.cs" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/StartsWith/startswith1.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.startswith/vb/startswith1.vb" id="Snippet1"::: + ]]> @@ -13049,9 +13049,9 @@ The following example determines whether a string starts with a particular subst System.Boolean - - - + + + [System.Runtime.CompilerServices.Nullable(2)] @@ -13069,20 +13069,20 @@ The following example determines whether a string starts with a particular subst if the parameter matches the beginning of this string; otherwise, . - ), must be a reference to this same instance, or must match the beginning of this instance. - -This method performs a comparison using the specified casing and culture. - -## Examples -The following example determines whether a string occurs at the beginning of another string. The method is called several times using case sensitivity, case insensitivity, and different cultures that influence the results of the search. - -:::code language="csharp" source="~/snippets/csharp/System/String/StartsWith/swci.cs" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/StartsWith/swci.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.StartsWithCI/vb/swci.vb" id="Snippet1"::: - + ), must be a reference to this same instance, or must match the beginning of this instance. + +This method performs a comparison using the specified casing and culture. + +## Examples +The following example determines whether a string occurs at the beginning of another string. The method is called several times using case sensitivity, case insensitivity, and different cultures that influence the results of the search. + +:::code language="csharp" source="~/snippets/csharp/System/String/StartsWith/swci.cs" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/StartsWith/swci.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.StartsWithCI/vb/swci.vb" id="Snippet1"::: + ]]> @@ -13099,8 +13099,8 @@ The following example determines whether a string occurs at the beginning of ano 4.2.0.0 - Retrieves a substring from this instance. - + Retrieves a substring from this instance. + This member is overloaded. For complete information about this member, including syntax, usage, and examples, click a name in the overload list. @@ -13156,33 +13156,33 @@ This member is overloaded. For complete information about this member, including Retrieves a substring from this instance. The substring starts at a specified character position and continues to the end of the string. A string that is equivalent to the substring that begins at in this instance, or if is equal to the length of this instance. - method to extract a substring from a string that begins at a specified character position and ends at the end of the string. The starting character position is zero-based; in other words, the first character in the string is at index 0, not index 1. To extract a substring that begins at a specified character position and ends before the end of the string, call the method. - -> [!NOTE] -> This method does not modify the value of the current instance. Instead, it returns a new string that begins at the `startIndex` position in the current string. - -To extract a substring that begins with a particular character or character sequence, call a method such as or to get the value of `startIndex`. The second example illustrates this; it extracts a key value that begins one character position after the `=` character. - -If `startIndex` is equal to zero, the method returns the original string unchanged. -## Examples -The following example demonstrates obtaining a substring from a string. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/System.String.Substring/cpp/Substring10.cpp" id="Snippet10"::: -:::code language="csharp" source="~/snippets/csharp/System/String/Substring/Substring10.cs" interactive="try-dotnet-method" id="Snippet10"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Substring/Substring10.fs" id="Snippet10"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/System.String.Substring/vb/Substring10.vb" id="Snippet10"::: - -The following example uses the method to separate key/value pairs that are delimited by an equals (`=`) character. - -:::code language="csharp" source="~/snippets/csharp/System/String/Substring/Substring1.cs" interactive="try-dotnet-method" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Substring/Substring1.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/System.String.Substring/vb/Substring1.vb" id="Snippet1"::: - -The method is used to get the position of the equals character in the string. The call to the method extracts the key name, which starts from the first character in the string and extends for the number of characters returned by the call to the method. The call to the method then extracts the value assigned to the key. It starts at one character position beyond the equals character and extends to the end of the string. - + method to extract a substring from a string that begins at a specified character position and ends at the end of the string. The starting character position is zero-based; in other words, the first character in the string is at index 0, not index 1. To extract a substring that begins at a specified character position and ends before the end of the string, call the method. + +> [!NOTE] +> This method does not modify the value of the current instance. Instead, it returns a new string that begins at the `startIndex` position in the current string. + +To extract a substring that begins with a particular character or character sequence, call a method such as or to get the value of `startIndex`. The second example illustrates this; it extracts a key value that begins one character position after the `=` character. + +If `startIndex` is equal to zero, the method returns the original string unchanged. +## Examples +The following example demonstrates obtaining a substring from a string. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/System.String.Substring/cpp/Substring10.cpp" id="Snippet10"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Substring/Substring10.cs" interactive="try-dotnet-method" id="Snippet10"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Substring/Substring10.fs" id="Snippet10"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/System.String.Substring/vb/Substring10.vb" id="Snippet10"::: + +The following example uses the method to separate key/value pairs that are delimited by an equals (`=`) character. + +:::code language="csharp" source="~/snippets/csharp/System/String/Substring/Substring1.cs" interactive="try-dotnet-method" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Substring/Substring1.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/System.String.Substring/vb/Substring1.vb" id="Snippet1"::: + +The method is used to get the position of the equals character in the string. The call to the method extracts the key name, which starts from the first character in the string and extends for the number of characters returned by the call to the method. The call to the method then extracts the value assigned to the key. It starts at one character position beyond the equals character and extends to the end of the string. + ]]> @@ -13255,70 +13255,70 @@ The method is used to get the position of the eq Retrieves a substring from this instance. The substring starts at a specified character position and has a specified length. A string that is equivalent to the substring of length that begins at in this instance, or if is equal to the length of this instance and is zero. - method to extract a substring from a string that begins at a specified character position and ends before the end of the string. The starting character position is zero-based; in other words, the first character in the string is at index 0, not index 1. To extract a substring that begins at a specified character position and continues to the end of the string, call the method. - -> [!NOTE] -> This method does not modify the value of the current instance. Instead, it returns a new string with `length` characters starting from the `startIndex` position in the current string. - -The `length` parameter represents the total number of characters to extract from the current string instance. This includes the starting character found at index `startIndex`. In other words, the method attempts to extract characters from index `startIndex` to index `startIndex` + `length` - 1. - -To extract a substring that begins with a particular character or character sequence, call a method such as or to get the value of `startIndex`. - -If the substring should extend from `startIndex` to a specified character sequence, you can call a method such as or to get the index of the ending character or character sequence. You can then convert that value to an index position in the string as follows: - -- If you've searched for a single character that is to mark the end of the substring, the `length` parameter equals `endIndex` - `startIndex` + 1, where `endIndex` is the return value of the or method. The following example extracts a continuous block of "b" characters from a string. - - :::code language="csharp" source="~/snippets/csharp/System/String/Substring/Substring2.cs" interactive="try-dotnet-method" id="Snippet2"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/Substring/Substring2.fs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/System.String.Substring/vb/Substring2.vb" id="Snippet2"::: - -- If you've searched for multiple characters that are to mark the end of the substring, the `length` parameter equals `endIndex` + `endMatchLength` - `startIndex`, where `endIndex` is the return value of the or method, and `endMatchLength` is the length of the character sequence that marks the end of the substring. The following example extracts a block of text that contains an XML `` element. - - :::code language="csharp" source="~/snippets/csharp/System/String/Substring/Substring3.cs" interactive="try-dotnet-method" id="Snippet3"::: - :::code language="fsharp" source="~/snippets/fsharp/System/String/Substring/Substring3.fs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/System.String.Substring/vb/Substring3.vb" id="Snippet3"::: - -- If the character or character sequence is not included in the end of the substring, the `length` parameter equals `endIndex` - `startIndex`, where `endIndex` is the return value of the or method. - -If `startIndex` is equal to zero and `length` equals the length of the current string, the method returns the original string unchanged. - -## Examples -The following example illustrates a simple call to the method that extracts two characters from a string starting at the sixth character position (that is, at index five). - -:::code language="csharp" source="~/snippets/csharp/System/String/Substring/Substring4.cs" interactive="try-dotnet-method" id="Snippet4"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Substring/Substring4.fs" id="Snippet4"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/System.String.Substring/vb/Substring4.vb" id="Snippet4"::: - -The following example uses the method in the following three cases to isolate substrings within a string. In two cases the substrings are used in comparisons, and in the third case an exception is thrown because invalid parameters are specified. - -- It extracts the single character at the third position in the string (at index 2) and compares it with a "c". This comparison returns `true`. - -- It extracts zero characters starting at the fourth position in the string (at index 3) and passes it to the method. This returns true because the call to the method returns . - -- It attempts to extract one character starting at the fourth position in the string. Because there is no character at that position, the method call throws an exception. - -:::code language="csharp" source="~/snippets/csharp/System/String/Substring/source.cs" interactive="try-dotnet-method" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Substring/source.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic String.Substring1 Example/VB/source.vb" id="Snippet1"::: - -The following example uses the method to separate key/value pairs that are delimited by an equals (`=`) character. - -:::code language="csharp" source="~/snippets/csharp/System/String/Substring/Substring1.cs" interactive="try-dotnet-method" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Substring/Substring1.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/System.String.Substring/vb/Substring1.vb" id="Snippet1"::: - -The method is used to get the position of the equals character in the string. The call to the method extracts the key name, which starts from the first character in the string and extends for the number of characters returned by the call to the method. The call to the method then extracts the value assigned to the key. It starts at one character position beyond the equals character and extends to the end of the string. - + method to extract a substring from a string that begins at a specified character position and ends before the end of the string. The starting character position is zero-based; in other words, the first character in the string is at index 0, not index 1. To extract a substring that begins at a specified character position and continues to the end of the string, call the method. + +> [!NOTE] +> This method does not modify the value of the current instance. Instead, it returns a new string with `length` characters starting from the `startIndex` position in the current string. + +The `length` parameter represents the total number of characters to extract from the current string instance. This includes the starting character found at index `startIndex`. In other words, the method attempts to extract characters from index `startIndex` to index `startIndex` + `length` - 1. + +To extract a substring that begins with a particular character or character sequence, call a method such as or to get the value of `startIndex`. + +If the substring should extend from `startIndex` to a specified character sequence, you can call a method such as or to get the index of the ending character or character sequence. You can then convert that value to an index position in the string as follows: + +- If you've searched for a single character that is to mark the end of the substring, the `length` parameter equals `endIndex` - `startIndex` + 1, where `endIndex` is the return value of the or method. The following example extracts a continuous block of "b" characters from a string. + + :::code language="csharp" source="~/snippets/csharp/System/String/Substring/Substring2.cs" interactive="try-dotnet-method" id="Snippet2"::: + :::code language="fsharp" source="~/snippets/fsharp/System/String/Substring/Substring2.fs" id="Snippet2"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/System.String.Substring/vb/Substring2.vb" id="Snippet2"::: + +- If you've searched for multiple characters that are to mark the end of the substring, the `length` parameter equals `endIndex` + `endMatchLength` - `startIndex`, where `endIndex` is the return value of the or method, and `endMatchLength` is the length of the character sequence that marks the end of the substring. The following example extracts a block of text that contains an XML `` element. + + :::code language="csharp" source="~/snippets/csharp/System/String/Substring/Substring3.cs" interactive="try-dotnet-method" id="Snippet3"::: + :::code language="fsharp" source="~/snippets/fsharp/System/String/Substring/Substring3.fs" id="Snippet3"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/System.String.Substring/vb/Substring3.vb" id="Snippet3"::: + +- If the character or character sequence is not included in the end of the substring, the `length` parameter equals `endIndex` - `startIndex`, where `endIndex` is the return value of the or method. + +If `startIndex` is equal to zero and `length` equals the length of the current string, the method returns the original string unchanged. + +## Examples +The following example illustrates a simple call to the method that extracts two characters from a string starting at the sixth character position (that is, at index five). + +:::code language="csharp" source="~/snippets/csharp/System/String/Substring/Substring4.cs" interactive="try-dotnet-method" id="Snippet4"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Substring/Substring4.fs" id="Snippet4"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/System.String.Substring/vb/Substring4.vb" id="Snippet4"::: + +The following example uses the method in the following three cases to isolate substrings within a string. In two cases the substrings are used in comparisons, and in the third case an exception is thrown because invalid parameters are specified. + +- It extracts the single character at the third position in the string (at index 2) and compares it with a "c". This comparison returns `true`. + +- It extracts zero characters starting at the fourth position in the string (at index 3) and passes it to the method. This returns true because the call to the method returns . + +- It attempts to extract one character starting at the fourth position in the string. Because there is no character at that position, the method call throws an exception. + +:::code language="csharp" source="~/snippets/csharp/System/String/Substring/source.cs" interactive="try-dotnet-method" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Substring/source.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_Classic/classic String.Substring1 Example/VB/source.vb" id="Snippet1"::: + +The following example uses the method to separate key/value pairs that are delimited by an equals (`=`) character. + +:::code language="csharp" source="~/snippets/csharp/System/String/Substring/Substring1.cs" interactive="try-dotnet-method" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Substring/Substring1.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/System.String.Substring/vb/Substring1.vb" id="Snippet1"::: + +The method is used to get the position of the equals character in the string. The call to the method extracts the key name, which starts from the first character in the string and extends for the number of characters returned by the call to the method. The call to the method then extracts the value assigned to the key. It starts at one character position beyond the equals character and extends to the end of the string. + ]]> - plus indicates a position not within this instance. - --or- - + plus indicates a position not within this instance. + +-or- + or is less than zero. @@ -13369,11 +13369,11 @@ The method is used to get the position of the eq Returns an enumerator that iterates through the current object. A strongly-typed enumerator that can be used to iterate through the current object. - instance is cast to an interface object. For more information, see the method. - + instance is cast to an interface object. For more information, see the method. + ]]> @@ -13424,11 +13424,11 @@ This member is an explicit interface member implementation. It can be used only Returns an enumerator that iterates through the current object. An enumerator that can be used to iterate through the current string. - instance is cast to an interface. For more information, see the method. - + instance is cast to an interface. For more information, see the method. + ]]> @@ -13466,32 +13466,32 @@ This member is an explicit interface member implementation. It can be used only An object that evaluates to a . Compares this instance with a specified and indicates whether this instance precedes, follows, or appears in the same position in the sort order as the specified . - A 32-bit signed integer that indicates whether this instance precedes, follows, or appears in the same position in the sort order as the parameter. - + A 32-bit signed integer that indicates whether this instance precedes, follows, or appears in the same position in the sort order as the parameter. + ValueConditionLess than zeroThis instance precedes .ZeroThis instance has the same position in the sort order as .Greater than zeroThis instance follows , or is . - object. - -> [!CAUTION] -> The method was designed primarily for use in sorting or alphabetizing operations. It should not be used when the primary purpose of the method call is to determine whether two strings are equivalent. To determine whether two strings are equivalent, call the method. - -This method performs a word (case-sensitive and culture-sensitive) comparison using the current culture. For more information about word, string, and ordinal sorts, see . - -For more information about the behavior of this method, see the Remarks section of the method. - -## Examples - -The following example uses the method with an . Because it attempts to compare a instance to a `TestClass` object, the method throws an . - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/ExToString/CPP/extostring.cpp" id="Snippet1"::: -:::code language="csharp" source="~/snippets/csharp/System/String/CompareTo/extostring.cs" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/CompareTo/extostring.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ExToString/VB/extostring.vb" id="Snippet1"::: - + object. + +> [!CAUTION] +> The method was designed primarily for use in sorting or alphabetizing operations. It should not be used when the primary purpose of the method call is to determine whether two strings are equivalent. To determine whether two strings are equivalent, call the method. + +This method performs a word (case-sensitive and culture-sensitive) comparison using the current culture. For more information about word, string, and ordinal sorts, see . + +For more information about the behavior of this method, see the Remarks section of the method. + +## Examples + +The following example uses the method with an . Because it attempts to compare a instance to a `TestClass` object, the method throws an . + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/ExToString/CPP/extostring.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/CompareTo/extostring.cs" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/CompareTo/extostring.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ExToString/VB/extostring.vb" id="Snippet1"::: + ]]> @@ -13528,17 +13528,17 @@ The following example uses the method with an Returns the for the class. The enumerated constant, . - enumerated constant for the type. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.gettypecode/CPP/gtc.cpp" id="Snippet1"::: -:::code language="csharp" source="~/snippets/csharp/System/String/GetTypeCode/gtc.cs" interactive="try-dotnet" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/GetTypeCode/gtc.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.gettypecode/VB/gtc.vb" id="Snippet1"::: - + enumerated constant for the type. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.gettypecode/CPP/gtc.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/GetTypeCode/gtc.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/GetTypeCode/gtc.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.gettypecode/VB/gtc.vb" id="Snippet1"::: + ]]> @@ -13591,11 +13591,11 @@ The following example displays the enumerated constant fo if the value of the current string is ; if the value of the current string is . - instance is cast to an interface. The recommended alternative is to call the method. - + instance is cast to an interface. The recommended alternative is to call the method. + ]]> The value of the current string is not or . @@ -13654,11 +13654,11 @@ This member is an explicit interface member implementation. It can be used only For a description of this member, see . The converted value of the current object. - instance is cast to an interface. The recommended alternative is to call the method. - + instance is cast to an interface. The recommended alternative is to call the method. + ]]> The value of the current object cannot be parsed. @@ -13712,11 +13712,11 @@ This member is an explicit interface member implementation. It can be used only For a description of this member, see . The character at index 0 in the current object. - instance is cast to an interface. The recommended alternative is to call the method. - + instance is cast to an interface. The recommended alternative is to call the method. + ]]> @@ -13774,11 +13774,11 @@ This member is an explicit interface member implementation. It can be used only For a description of this member, see . The converted value of the current object. - instance is cast to an interface. The recommended alternative is to call the method. - + instance is cast to an interface. The recommended alternative is to call the method. + ]]> @@ -13836,11 +13836,11 @@ This member is an explicit interface member implementation. It can be used only For a description of this member, see . The converted value of the current object. - instance is cast to an interface. The recommended alternative is to call the method. - + instance is cast to an interface. The recommended alternative is to call the method. + ]]> The value of the current object cannot be parsed. @@ -13900,11 +13900,11 @@ This member is an explicit interface member implementation. It can be used only For a description of this member, see . The converted value of the current object. - instance is cast to an interface. The recommended alternative is to call the method. - + instance is cast to an interface. The recommended alternative is to call the method. + ]]> The value of the current object cannot be parsed. @@ -13964,11 +13964,11 @@ This member is an explicit interface member implementation. It can be used only For a description of this member, see . The converted value of the current object. - instance is cast to an interface. The recommended alternative is to call the method. - + instance is cast to an interface. The recommended alternative is to call the method. + ]]> The value of the current object cannot be parsed. @@ -14028,11 +14028,11 @@ This member is an explicit interface member implementation. It can be used only For a description of this member, see . The converted value of the current object. - instance is cast to an interface. The recommended alternative is to call the method. - + instance is cast to an interface. The recommended alternative is to call the method. + ]]> @@ -14090,11 +14090,11 @@ This member is an explicit interface member implementation. It can be used only For a description of this member, see . The converted value of the current object. - instance is cast to an interface. The recommended alternative is to call the method. - + instance is cast to an interface. The recommended alternative is to call the method. + ]]> @@ -14156,11 +14156,11 @@ This member is an explicit interface member implementation. It can be used only For a description of this member, see . The converted value of the current object. - instance is cast to an interface. The recommended alternative is to call the method. - + instance is cast to an interface. The recommended alternative is to call the method. + ]]> The value of the current object cannot be parsed. @@ -14220,11 +14220,11 @@ This member is an explicit interface member implementation. It can be used only For a description of this member, see . The converted value of the current object. - instance is cast to an interface. The recommended alternative is to call the method. - + instance is cast to an interface. The recommended alternative is to call the method. + ]]> @@ -14258,20 +14258,20 @@ This member is an explicit interface member implementation. It can be used only - An object that supplies culture-specific formatting information. - --or- - + An object that supplies culture-specific formatting information. + +-or- + to use the formatting conventions of the current culture. For a description of this member, see . A instance equivalent to the value of this instance. - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -14325,11 +14325,11 @@ This member is an explicit interface member implementation. It can be used only For a description of this member, see . The converted value of the current object. - instance is cast to an interface. The recommended alternative is to call the method. - + instance is cast to an interface. The recommended alternative is to call the method. + ]]> @@ -14394,11 +14394,11 @@ This member is an explicit interface member implementation. It can be used only For a description of this member, see . The converted value of the current object. - instance is cast to an interface. The recommended alternative is to call the method. - + instance is cast to an interface. The recommended alternative is to call the method. + ]]> The value of the current object cannot be parsed. @@ -14462,11 +14462,11 @@ This member is an explicit interface member implementation. It can be used only For a description of this member, see . The converted value of the current object. - instance is cast to an interface. The recommended alternative is to call the method. - + instance is cast to an interface. The recommended alternative is to call the method. + ]]> The value of the current object cannot be parsed. @@ -14530,11 +14530,11 @@ This member is an explicit interface member implementation. It can be used only For a description of this member, see . The converted value of the current object. - instance is cast to an interface. The recommended alternative is to call the method. - + instance is cast to an interface. The recommended alternative is to call the method. + ]]> @@ -14768,32 +14768,32 @@ This member is an explicit interface member implementation. It can be used only Copies the characters in this instance to a Unicode character array. A Unicode character array whose elements are the individual characters of this instance. If this instance is an empty string, the returned array is empty and has a zero length. - object) in a string to a character array. The first character copied is at index zero of the returned character array; the last character copied is at index - 1. - -To create a string from the characters in a character array, call the constructor. - -To create a byte array that contains the encoded characters in a string, instantiate the appropriate object and call its method. Some of the standard encodings available in .NET include the following: - -|Encoding|Object| -|--------------|------------| -|ASCII|| -|UTF-7|| -|UTF-8|| -|UTF-16|| -|UTF-32|| - -For more information, see [Character Encoding in .NET](/dotnet/standard/base-types/character-encoding). - -## Examples -The following example calls the method to extract the characters in a string to a character array. It then displays the original string and the elements in the array. - -:::code language="csharp" source="~/snippets/csharp/System/String/ToCharArray/ToCharArray1.cs" interactive="try-dotnet" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/ToCharArray/ToCharArray1.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.tochararray/vb/ToCharArray1.vb" id="Snippet1"::: - + object) in a string to a character array. The first character copied is at index zero of the returned character array; the last character copied is at index - 1. + +To create a string from the characters in a character array, call the constructor. + +To create a byte array that contains the encoded characters in a string, instantiate the appropriate object and call its method. Some of the standard encodings available in .NET include the following: + +|Encoding|Object| +|--------------|------------| +|ASCII|| +|UTF-7|| +|UTF-8|| +|UTF-16|| +|UTF-32|| + +For more information, see [Character Encoding in .NET](/dotnet/standard/base-types/character-encoding). + +## Examples +The following example calls the method to extract the characters in a string to a character array. It then displays the original string and the elements in the array. + +:::code language="csharp" source="~/snippets/csharp/System/String/ToCharArray/ToCharArray1.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/ToCharArray/ToCharArray1.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.tochararray/vb/ToCharArray1.vb" id="Snippet1"::: + ]]> @@ -14854,42 +14854,42 @@ The following example calls the method to ex Copies the characters in a specified substring in this instance to a Unicode character array. A Unicode character array whose elements are the number of characters in this instance starting from character position . - constructor. - -The `startIndex` parameter is zero-based. That is, the index of the first character in the string instance is zero. - -If `length` is zero, the returned array is empty and has a zero length. If this instance is `null` or an empty string (""), the returned array is empty and has a zero length. - -To create a byte array that contains the encoded characters in a portion of a string, instantiate the appropriate object and call its method. Some of the standard encodings available in .NET include: - -|Encoding|Object| -|--------------|------------| -|ASCII|| -|UTF-7|| -|UTF-8|| -|UTF-16|| -|UTF-32|| - -For more information, see [Character Encoding in .NET](/dotnet/standard/base-types/character-encoding). - -## Examples -The following example converts a substring within a string to an array of characters, then enumerates and displays the elements of the array. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.ToCharArray1/CPP/tocharry1.cpp" id="Snippet1"::: -:::code language="csharp" source="~/snippets/csharp/System/String/ToCharArray/tocharry1.cs" interactive="try-dotnet" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/ToCharArray/tocharry1.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.ToCharArray1/VB/tocharry1.vb" id="Snippet1"::: - + constructor. + +The `startIndex` parameter is zero-based. That is, the index of the first character in the string instance is zero. + +If `length` is zero, the returned array is empty and has a zero length. If this instance is `null` or an empty string (""), the returned array is empty and has a zero length. + +To create a byte array that contains the encoded characters in a portion of a string, instantiate the appropriate object and call its method. Some of the standard encodings available in .NET include: + +|Encoding|Object| +|--------------|------------| +|ASCII|| +|UTF-7|| +|UTF-8|| +|UTF-16|| +|UTF-32|| + +For more information, see [Character Encoding in .NET](/dotnet/standard/base-types/character-encoding). + +## Examples +The following example converts a substring within a string to an array of characters, then enumerates and displays the elements of the array. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.ToCharArray1/CPP/tocharry1.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/ToCharArray/tocharry1.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/ToCharArray/tocharry1.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.ToCharArray1/VB/tocharry1.vb" id="Snippet1"::: + ]]> - or is less than zero. - --or- - + or is less than zero. + +-or- + plus is greater than the length of this instance. @@ -14952,27 +14952,27 @@ The following example converts a substring within a string to an array of charac Returns a copy of this string converted to lowercase. A string in lowercase. - [!NOTE] -> This method does not modify the value of the current instance. Instead, it returns a new string in which all characters in the current instance are converted to lowercase. - -The casing operation that results from calling the method takes the casing conventions of the current culture into account. If you need the lowercase or uppercase version of an operating system identifier, such as a file name, named pipe, or registry key, use the or methods. This produces the same result in every culture (unlike the method) and performs more efficiently. - + [!NOTE] +> This method does not modify the value of the current instance. Instead, it returns a new string in which all characters in the current instance are converted to lowercase. + +The casing operation that results from calling the method takes the casing conventions of the current culture into account. If you need the lowercase or uppercase version of an operating system identifier, such as a file name, named pipe, or registry key, use the or methods. This produces the same result in every culture (unlike the method) and performs more efficiently. + ]]> - @@ -15025,7 +15025,7 @@ The following example converts several mixed case strings to lowercase. System.String - + [System.Runtime.CompilerServices.Nullable(2)] @@ -15039,27 +15039,27 @@ The following example converts several mixed case strings to lowercase. Returns a copy of this string converted to lowercase, using the casing rules of the specified culture. The lowercase equivalent of the current string. - [!NOTE] -> This method does not modify the value of the current instance. Instead, it returns a new string in which all characters in the current instance are converted to lowercase. - -If you pass the method a object other than , the casing operation will take culture-specific rules into account. If you need the lowercase or uppercase version of an operating system identifier, such as a file name, named pipe, or registry key, use the or method. This produces the same result in every culture and performs more efficiently. - + [!NOTE] +> This method does not modify the value of the current instance. Instead, it returns a new string in which all characters in the current instance are converted to lowercase. + +If you pass the method a object other than , the casing operation will take culture-specific rules into account. If you need the lowercase or uppercase version of an operating system identifier, such as a file name, named pipe, or registry key, use the or method. This produces the same result in every culture and performs more efficiently. + ]]> - @@ -15114,25 +15114,25 @@ The following example converts two strings of uppercase characters to lowercase Returns a copy of this object converted to lowercase using the casing rules of the invariant culture. The lowercase equivalent of the current string. - property. - -If your application depends on the case of a string changing in a predictable way that is unaffected by the current culture, use the method. The method is equivalent to `ToLower(CultureInfo.InvariantCulture)`. The method is recommended when a collection of strings must appear in a predictable order in a user interface control. - -> [!NOTE] -> This method does not modify the value of the current instance. Instead, it returns a new string in which all characters in the current instance are converted to lowercase. - -If you need the lowercase or uppercase version of an operating system identifier, such as a file name, named pipe, or registry key, use the or methods. - -## Examples -The following example defines a string array that contains a single word in a number of languages. The method is used to populate the elements of a parallel array with the case-insensitive version of each word. The method is used to sort the case-sensitive array based on the order of elements in the lowercase array to ensure that elements appear in the same order regardless of language. - -:::code language="csharp" source="~/snippets/csharp/System/String/ToLowerInvariant/tolowerinvariant.cs" interactive="try-dotnet" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/ToLowerInvariant/tolowerinvariant.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.tolowerinvariant/vb/tolowerinvariant.vb" id="Snippet1"::: - + property. + +If your application depends on the case of a string changing in a predictable way that is unaffected by the current culture, use the method. The method is equivalent to `ToLower(CultureInfo.InvariantCulture)`. The method is recommended when a collection of strings must appear in a predictable order in a user interface control. + +> [!NOTE] +> This method does not modify the value of the current instance. Instead, it returns a new string in which all characters in the current instance are converted to lowercase. + +If you need the lowercase or uppercase version of an operating system identifier, such as a file name, named pipe, or registry key, use the or methods. + +## Examples +The following example defines a string array that contains a single word in a number of languages. The method is used to populate the elements of a parallel array with the case-insensitive version of each word. The method is used to sort the case-sensitive array based on the order of elements in the lowercase array to ensure that elements appear in the same order regardless of language. + +:::code language="csharp" source="~/snippets/csharp/System/String/ToLowerInvariant/tolowerinvariant.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/ToLowerInvariant/tolowerinvariant.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.tolowerinvariant/vb/tolowerinvariant.vb" id="Snippet1"::: + ]]> @@ -15203,19 +15203,19 @@ The following example defines a string array that contains a single word in a nu Returns this instance of ; no actual conversion is performed. The current string. - method.Note that the example does not explicitly call the method. Instead, the method is called implicitly by the [composite formatting](/dotnet/standard/base-types/composite-formatting) feature. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.tostring/CPP/string.tostring.cpp" id="Snippet1"::: -:::code language="csharp" source="~/snippets/csharp/System/String/ToString/string.tostring.cs" interactive="try-dotnet" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/ToString/string.tostring.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.tostring/VB/string.tostring.vb" id="Snippet1"::: - + method.Note that the example does not explicitly call the method. Instead, the method is called implicitly by the [composite formatting](/dotnet/standard/base-types/composite-formatting) feature. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/string.tostring/CPP/string.tostring.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/ToString/string.tostring.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/ToString/string.tostring.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/string.tostring/VB/string.tostring.vb" id="Snippet1"::: + ]]> @@ -15266,7 +15266,7 @@ The following example demonstrates the method.N System.String - + [System.Runtime.CompilerServices.Nullable(2)] @@ -15280,13 +15280,13 @@ The following example demonstrates the method.N Returns this instance of ; no actual conversion is performed. The current string. - @@ -15347,28 +15347,28 @@ Because this method simply returns the current string unchanged, there is no nee Returns a copy of this string converted to uppercase. The uppercase equivalent of the current string. - [!NOTE] -> This method does not modify the value of the current instance. Instead, it returns a new string in which all characters in the current instance are converted to uppercase. - -The method is often used to convert a string to uppercase so that it can be used in a case-insensitive comparison. A better method to perform case-insensitive comparison is to call a string comparison method that has a parameter whose value you set to for a culture-sensitive, case-insensitive comparison. - -The casing operation that results from calling the method takes the casing conventions of the current culture into account. If you need the lowercase or uppercase version of an operating system identifier, such as a file name, named pipe, or registry key, use the or method. This produces the same result in every culture (unlike the method) and performs more efficiently. - + [!NOTE] +> This method does not modify the value of the current instance. Instead, it returns a new string in which all characters in the current instance are converted to uppercase. + +The method is often used to convert a string to uppercase so that it can be used in a case-insensitive comparison. A better method to perform case-insensitive comparison is to call a string comparison method that has a parameter whose value you set to for a culture-sensitive, case-insensitive comparison. + +The casing operation that results from calling the method takes the casing conventions of the current culture into account. If you need the lowercase or uppercase version of an operating system identifier, such as a file name, named pipe, or registry key, use the or method. This produces the same result in every culture (unlike the method) and performs more efficiently. + ]]> - method to convert a series of one-character strings that contain each character in the Basic Latin, Latin-1 Supplement, and Latin Extended-A character sets. It then displays each string whose uppercase character is different from its lowercase character. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.ToUpper/cpp/ToUpperEx.cpp" id="Snippet1"::: -:::code language="csharp" source="~/snippets/csharp/System/String/ToUpper/ToUpperEx.cs" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/ToUpper/ToUpperEx.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.ToUpper/vb/ToUpperEx.vb" id="Snippet1"::: + method to convert a series of one-character strings that contain each character in the Basic Latin, Latin-1 Supplement, and Latin Extended-A character sets. It then displays each string whose uppercase character is different from its lowercase character. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.ToUpper/cpp/ToUpperEx.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/ToUpper/ToUpperEx.cs" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/ToUpper/ToUpperEx.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.ToUpper/vb/ToUpperEx.vb" id="Snippet1"::: ]]> @@ -15421,7 +15421,7 @@ The following example calls the method to conver System.String - + [System.Runtime.CompilerServices.Nullable(2)] @@ -15435,25 +15435,25 @@ The following example calls the method to conver Returns a copy of this string converted to uppercase, using the casing rules of the specified culture. The uppercase equivalent of the current string. - [!NOTE] -> This method does not modify the value of the current instance. Instead, it returns a new string in which all characters in the current instance are converted to uppercase. - -If you pass the method a object other than , the casing operation will take culture-specific rules into account. If you need the lowercase or uppercase version of an operating system identifier, such as a file name, named pipe, or registry key, use the or method. This produces the same result in every culture and performs more efficiently. - + [!NOTE] +> This method does not modify the value of the current instance. Instead, it returns a new string in which all characters in the current instance are converted to uppercase. + +If you pass the method a object other than , the casing operation will take culture-specific rules into account. If you need the lowercase or uppercase version of an operating system identifier, such as a file name, named pipe, or registry key, use the or method. This produces the same result in every culture and performs more efficiently. + ]]> - @@ -15509,27 +15509,27 @@ The following example converts a string of lowercase characters to two strings o Returns a copy of this object converted to uppercase using the casing rules of the invariant culture. The uppercase equivalent of the current string. - property. - -If your application depends on the case of a string changing in a predictable way that is unaffected by the current culture, use the method. The method is equivalent to `ToUpper(CultureInfo.InvariantCulture)`. The method is recommended when a collection of strings must appear in a predictable order in a user interface control. - -> [!NOTE] -> This method does not modify the value of the current instance. Instead, it returns a new string in which all characters in the current instance are converted to uppercase. - -If you need the lowercase or uppercase version of an operating system identifier, such as a file name, named pipe, or registry key, use the or methods. - + property. + +If your application depends on the case of a string changing in a predictable way that is unaffected by the current culture, use the method. The method is equivalent to `ToUpper(CultureInfo.InvariantCulture)`. The method is recommended when a collection of strings must appear in a predictable order in a user interface control. + +> [!NOTE] +> This method does not modify the value of the current instance. Instead, it returns a new string in which all characters in the current instance are converted to uppercase. + +If you need the lowercase or uppercase version of an operating system identifier, such as a file name, named pipe, or registry key, use the or methods. + ]]> - method is used to populate the elements of a parallel array with the case-insensitive version of each word. The method is used to sort the case-sensitive array based on the order of elements in the uppercase array to ensure that elements appear in the same order regardless of language. - -:::code language="csharp" source="~/snippets/csharp/System/String/ToUpperInvariant/toupperinvariant.cs" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/ToUpperInvariant/toupperinvariant.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.toupperinvariant/vb/toupperinvariant.vb" id="Snippet1"::: + method is used to populate the elements of a parallel array with the case-insensitive version of each word. The method is used to sort the case-sensitive array based on the order of elements in the uppercase array to ensure that elements appear in the same order regardless of language. + +:::code language="csharp" source="~/snippets/csharp/System/String/ToUpperInvariant/toupperinvariant.cs" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/ToUpperInvariant/toupperinvariant.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.string.toupperinvariant/vb/toupperinvariant.vb" id="Snippet1"::: ]]> @@ -15593,28 +15593,28 @@ The following example defines a string array that contains a single word in a nu Removes all leading and trailing white-space characters from the current string. The string that remains after all white-space characters are removed from the start and end of the current string. If no characters can be trimmed from the current instance, the method returns the current instance unchanged. - [!NOTE] -> If the `Trim` method removes any characters from the current instance, this method does not modify the value of the current instance. Instead, it returns a new string in which all leading and trailing white space characters found in the current instance are removed. - -If the current string equals or all the characters in the current instance consist of white-space characters, the method returns . - -White-space characters are defined by the Unicode standard. The `Trim` method removes any leading and trailing characters that produce a return value of `true` when they are passed to the method. - -## Examples - -The following example uses the method to remove any extra white space from strings entered by the user before concatenating them. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Trim/cpp/trim2.cpp" id="Snippet2"::: -:::code language="csharp" source="~/snippets/csharp/System/String/Trim/Trim2.cs" id="Snippet2"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Trim/Trim2.fs" id="Snippet2"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Trim/vb/Trim2.vb" id="Snippet2"::: - + [!NOTE] +> If the `Trim` method removes any characters from the current instance, this method does not modify the value of the current instance. Instead, it returns a new string in which all leading and trailing white space characters found in the current instance are removed. + +If the current string equals or all the characters in the current instance consist of white-space characters, the method returns . + +White-space characters are defined by the Unicode standard. The `Trim` method removes any leading and trailing characters that produce a return value of `true` when they are passed to the method. + +## Examples + +The following example uses the method to remove any extra white space from strings entered by the user before concatenating them. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Trim/cpp/trim2.cpp" id="Snippet2"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Trim/Trim2.cs" id="Snippet2"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Trim/Trim2.fs" id="Snippet2"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Trim/vb/Trim2.vb" id="Snippet2"::: + ]]> @@ -15662,17 +15662,17 @@ The following example uses the Removes all leading and trailing instances of a character from the current string. The string that remains after all instances of the character are removed from the start and end of the current string. If no characters can be trimmed from the current instance, the method returns the current instance unchanged. - [!NOTE] -> If the `Trim(System.Char)` method removes any characters from the current instance, this method does not modify the value of the current instance. Instead, it returns a new string in which all leading and trailing `trimChar` characters found in the current instance are removed. - -If the current string equals or all the characters in the current instance consist of `trimChar` characters, the method returns . - + [!NOTE] +> If the `Trim(System.Char)` method removes any characters from the current instance, this method does not modify the value of the current instance. Instead, it returns a new string in which all leading and trailing `trimChar` characters found in the current instance are removed. + +If the current string equals or all the characters in the current instance consist of `trimChar` characters, the method returns . + ]]> @@ -15741,28 +15741,28 @@ If the current string equals Removes all leading and trailing occurrences of a set of characters specified in an array from the current string. The string that remains after all occurrences of the characters in the parameter are removed from the start and end of the current string. If is or an empty array, white-space characters are removed instead. If no characters can be trimmed from the current instance, the method returns the current instance unchanged. - [!NOTE] -> If the `Trim(System.Char[])` method removes any characters from the current instance, this method does not modify the value of the current instance. Instead, it returns a new string in which all leading and trailing `trimChars` characters found in the current instance are removed. - -If the current string equals or all the characters in the current instance consist of characters in the `trimChars` array, the method returns . - -If `trimChars` is `null` or an empty array, this method removes any leading or trailing characters that result in the method returning `true` when they are passed to the method. - -## Examples - -The following example uses the `Trim(System.Char[])` method to remove space, asterisk (*), and apostrophe (') characters from a string. - -:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Trim/cpp/trim1.cpp" id="Snippet1"::: -:::code language="csharp" source="~/snippets/csharp/System/String/Trim/Trim1.cs" interactive="try-dotnet-method" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/Trim/Trim1.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Trim/vb/Trim1.vb" id="Snippet1"::: - + [!NOTE] +> If the `Trim(System.Char[])` method removes any characters from the current instance, this method does not modify the value of the current instance. Instead, it returns a new string in which all leading and trailing `trimChars` characters found in the current instance are removed. + +If the current string equals or all the characters in the current instance consist of characters in the `trimChars` array, the method returns . + +If `trimChars` is `null` or an empty array, this method removes any leading or trailing characters that result in the method returning `true` when they are passed to the method. + +## Examples + +The following example uses the `Trim(System.Char[])` method to remove space, asterisk (*), and apostrophe (') characters from a string. + +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.String.Trim/cpp/trim1.cpp" id="Snippet1"::: +:::code language="csharp" source="~/snippets/csharp/System/String/Trim/Trim1.cs" interactive="try-dotnet-method" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/Trim/Trim1.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Trim/vb/Trim1.vb" id="Snippet1"::: + ]]> @@ -15808,15 +15808,15 @@ The following example uses the `Trim(System.Char[])` method to remove space, ast Removes all the trailing white-space characters from the current string. The string that remains after all white-space characters are removed from the end of the current string. If no characters can be trimmed from the current instance, the method returns the current instance unchanged. - [!NOTE] -> If the `TrimEnd` method removes any characters from the current instance, this method does not modify the value of the current instance. Instead, it returns a new string in which all trailing white-space characters are removed from the current string. - + [!NOTE] +> If the `TrimEnd` method removes any characters from the current instance, this method does not modify the value of the current instance. Instead, it returns a new string in which all trailing white-space characters are removed from the current string. + ]]> @@ -15858,15 +15858,15 @@ The `TrimEnd` method removes from the current string all trailing white-space ch Removes all the trailing occurrences of a character from the current string. The string that remains after all occurrences of the character are removed from the end of the current string. If no characters can be trimmed from the current instance, the method returns the current instance unchanged. - [!NOTE] -> If the `TrimEnd(System.Char)` method removes any characters from the current instance, this method does not modify the value of the current instance. Instead, it returns a new string in which all trailing `trimChar` characters are removed from the current string. - + [!NOTE] +> If the `TrimEnd(System.Char)` method removes any characters from the current instance, this method does not modify the value of the current instance. Instead, it returns a new string in which all trailing `trimChar` characters are removed from the current string. + ]]> @@ -15935,23 +15935,23 @@ The `TrimEnd(System.Char)` method removes from the current string all trailing ` Removes all the trailing occurrences of a set of characters specified in an array from the current string. The string that remains after all occurrences of the characters in the parameter are removed from the end of the current string. If is or an empty array, Unicode white-space characters are removed instead. If no characters can be trimmed from the current instance, the method returns the current instance unchanged. - [!NOTE] -> If the `TrimEnd(System.Char[])` method removes any characters from the current instance, this method does not modify the value of the current instance. Instead, it returns a new string in which all trailing characters found in `trimChars` are removed from the current string. - -## Examples - -The following example demonstrates how you can use the `TrimEnd(System.Char[])` method to trim white space or punctuation marks from the end of a string. - -:::code language="csharp" source="~/snippets/csharp/System/String/TrimEnd/sample2.cs" interactive="try-dotnet-method" id="Snippet2"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/TrimEnd/sample2.fs" id="Snippet2"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.TrimEnd/vb/Sample2.vb" id="Snippet2"::: - + [!NOTE] +> If the `TrimEnd(System.Char[])` method removes any characters from the current instance, this method does not modify the value of the current instance. Instead, it returns a new string in which all trailing characters found in `trimChars` are removed from the current string. + +## Examples + +The following example demonstrates how you can use the `TrimEnd(System.Char[])` method to trim white space or punctuation marks from the end of a string. + +:::code language="csharp" source="~/snippets/csharp/System/String/TrimEnd/sample2.cs" interactive="try-dotnet-method" id="Snippet2"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/TrimEnd/sample2.fs" id="Snippet2"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.TrimEnd/vb/Sample2.vb" id="Snippet2"::: + ]]> @@ -15997,15 +15997,15 @@ The following example demonstrates how you can use the `TrimEnd(System.Char[])` Removes all the leading white-space characters from the current string. The string that remains after all white-space characters are removed from the start of the current string. If no characters can be trimmed from the current instance, the method returns the current instance unchanged. - [!NOTE] -> If the `TrimStart` method removes any characters from the current instance, this method does not modify the value of the current instance. Instead, it returns a new string in which all leading white space characters found in the current instance are removed. - + [!NOTE] +> If the `TrimStart` method removes any characters from the current instance, this method does not modify the value of the current instance. Instead, it returns a new string in which all leading white space characters found in the current instance are removed. + ]]> @@ -16047,15 +16047,15 @@ The `TrimStart` method removes from the current string all leading white-space c Removes all the leading occurrences of a specified character from the current string. The string that remains after all occurrences of the character are removed from the start of the current string. If no characters can be trimmed from the current instance, the method returns the current instance unchanged. - [!NOTE] -> If the `TrimStart(System.Char)` method removes any characters from the current instance, this method does not modify the value of the current instance. Instead, it returns a new string in which all leading `trimChar` characters found in the current instance are removed. - + [!NOTE] +> If the `TrimStart(System.Char)` method removes any characters from the current instance, this method does not modify the value of the current instance. Instead, it returns a new string in which all leading `trimChar` characters found in the current instance are removed. + ]]> @@ -16124,35 +16124,35 @@ The `TrimStart(System.Char)` method removes from the current string all leading Removes all the leading occurrences of a set of characters specified in an array from the current string. The string that remains after all occurrences of characters in the parameter are removed from the start of the current string. If is or an empty array, white-space characters are removed instead. If no characters can be trimmed from the current instance, the method returns the current instance unchanged. - [!NOTE] -> If the `TrimStart(System.Char[])` method removes any characters from the current instance, this method does not modify the value of the current instance. Instead, it returns a new string in which all leading characters that are in the `trimChars` parameter found in the current instance are removed. - -## Examples - -The following example demonstrates the basic functionality of the method: - -:::code language="csharp" source="~/snippets/csharp/System/String/TrimStart/sample.cs" interactive="try-dotnet-method" id="Snippet1"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/TrimStart/sample.fs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.TrimStart/vb/sample.vb" id="Snippet1"::: - -The following example uses the method to trim white space and comment characters from lines of source code. The `StripComments` method wraps a call to and passes it a character array that contains a space and the comment character, which is an apostrophe ( ' ) in Visual Basic and a slash ( / ) in C# or F#. The method is also called to remove leading white space when evaluating whether a string is a comment. - -:::code language="csharp" source="~/snippets/csharp/System/String/TrimStart/sample.cs" id="Snippet2"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/TrimStart/sample.fs" id="Snippet2"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.TrimStart/vb/sample.vb" id="Snippet2"::: - -The following example then illustrates a call to the `StripComments` method. - -:::code language="csharp" source="~/snippets/csharp/System/String/TrimStart/sample.cs" id="Snippet3"::: -:::code language="fsharp" source="~/snippets/fsharp/System/String/TrimStart/sample.fs" id="Snippet3"::: -:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.TrimStart/vb/sample.vb" id="Snippet3"::: - + [!NOTE] +> If the `TrimStart(System.Char[])` method removes any characters from the current instance, this method does not modify the value of the current instance. Instead, it returns a new string in which all leading characters that are in the `trimChars` parameter found in the current instance are removed. + +## Examples + +The following example demonstrates the basic functionality of the method: + +:::code language="csharp" source="~/snippets/csharp/System/String/TrimStart/sample.cs" interactive="try-dotnet-method" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/TrimStart/sample.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.TrimStart/vb/sample.vb" id="Snippet1"::: + +The following example uses the method to trim white space and comment characters from lines of source code. The `StripComments` method wraps a call to and passes it a character array that contains a space and the comment character, which is an apostrophe ( ' ) in Visual Basic and a slash ( / ) in C# or F#. The method is also called to remove leading white space when evaluating whether a string is a comment. + +:::code language="csharp" source="~/snippets/csharp/System/String/TrimStart/sample.cs" id="Snippet2"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/TrimStart/sample.fs" id="Snippet2"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.TrimStart/vb/sample.vb" id="Snippet2"::: + +The following example then illustrates a call to the `StripComments` method. + +:::code language="csharp" source="~/snippets/csharp/System/String/TrimStart/sample.cs" id="Snippet3"::: +:::code language="fsharp" source="~/snippets/fsharp/System/String/TrimStart/sample.fs" id="Snippet3"::: +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.String.TrimStart/vb/sample.vb" id="Snippet3"::: + ]]> diff --git a/xml/System/StringComparer.xml b/xml/System/StringComparer.xml index eecdd426a3c..e97f3c41e8d 100644 --- a/xml/System/StringComparer.xml +++ b/xml/System/StringComparer.xml @@ -198,8 +198,8 @@ The following example demonstrates the properties and the System.Int32 - - + + An object to compare to . @@ -358,8 +358,8 @@ The following example demonstrates the properties and the System.StringComparer - - + + A culture whose linguistic rules are used to perform a string comparison. @@ -633,8 +633,8 @@ The following example demonstrates the properties and the System.Boolean - - + + An object to compare to . @@ -816,7 +816,7 @@ The following example demonstrates the properties and the System.Int32 - + An object. diff --git a/xml/System/TimeSpan.xml b/xml/System/TimeSpan.xml index 546033de69e..04d71291ae2 100644 --- a/xml/System/TimeSpan.xml +++ b/xml/System/TimeSpan.xml @@ -684,7 +684,7 @@ The specified `days`, `hours`, `minutes`, `seconds`, `milliseconds`, and `micros System.Int32 - + An object to compare, or . diff --git a/xml/System/TimeZoneInfo.xml b/xml/System/TimeZoneInfo.xml index 383ad9af4ff..5be8e934cf1 100644 --- a/xml/System/TimeZoneInfo.xml +++ b/xml/System/TimeZoneInfo.xml @@ -598,8 +598,8 @@ System.DateTime - - + + The date and time to convert. @@ -682,8 +682,8 @@ System.DateTimeOffset - - + + The date and time to convert. @@ -753,9 +753,9 @@ System.DateTime - - - + + + The date and time to convert. @@ -858,8 +858,8 @@ System.DateTime - - + + The Coordinated Universal Time (UTC). @@ -946,7 +946,7 @@ System.DateTime - + The date and time to convert. @@ -1026,8 +1026,8 @@ System.DateTime - - + + The date and time to convert. @@ -1118,9 +1118,9 @@ System.TimeZoneInfo - - - + + + [System.Runtime.CompilerServices.Nullable(2)] @@ -1128,7 +1128,7 @@ - + [System.Runtime.CompilerServices.Nullable(2)] @@ -1232,7 +1232,7 @@ System.TimeZoneInfo - + [System.Runtime.CompilerServices.Nullable(1)] @@ -1240,11 +1240,11 @@ - - - - - + + + + + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 2, 1 })] @@ -1379,7 +1379,7 @@ System.TimeZoneInfo - + [System.Runtime.CompilerServices.Nullable(1)] @@ -1387,11 +1387,11 @@ - - - - - + + + + + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 2, 1 })] @@ -1399,7 +1399,7 @@ - + The time zone's identifier. @@ -1679,7 +1679,7 @@ System.Boolean - + [System.Diagnostics.CodeAnalysis.NotNullWhen(true)] @@ -1932,7 +1932,7 @@ The following example uses the System.TimeZoneInfo - + The string representation of the serialized object. @@ -2584,7 +2584,7 @@ The following example uses the System.Boolean - + A second object to compare with the current object. @@ -3330,7 +3330,7 @@ The following example uses the System.Void - + The object that initiated the callback. The functionality for this parameter is not currently implemented. @@ -3385,8 +3385,8 @@ The following example uses the System.Void - - + + The object to populate with data. diff --git a/xml/System/TimeoutException.xml b/xml/System/TimeoutException.xml index e0396394954..12ee69d1de2 100644 --- a/xml/System/TimeoutException.xml +++ b/xml/System/TimeoutException.xml @@ -71,25 +71,25 @@ The exception that is thrown when the time allotted for a process or operation has expired. - exception is thrown, consult the documentation for the type whose method timed out. For information about handling the time-out, see the documentation for the method that threw the exception. - - uses the HRESULT, COR_E_TIMEOUT, which has the value 0x80131505. - - For a list of initial property values for an instance of , see the constructors. - - - -## Examples - The following code example demonstrates the use of in conjunction with members of the class. - + exception is thrown, consult the documentation for the type whose method timed out. For information about handling the time-out, see the documentation for the method that threw the exception. + + uses the HRESULT, COR_E_TIMEOUT, which has the value 0x80131505. + + For a list of initial property values for an instance of , see the constructors. + + + +## Examples + The following code example demonstrates the use of in conjunction with members of the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/TimeoutException.class/cpp/to.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System/TimeoutException/Overview/to.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System/TimeoutException/Overview/to.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/TimeoutException.class/VB/to.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/TimeoutException.class/VB/to.vb" id="Snippet1"::: + ]]> @@ -146,18 +146,18 @@ Initializes a new instance of the class. - property of the new instance with a system-supplied error message. This message takes into account the current system culture. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||A null reference (`Nothing` in Visual Basic).| -||The localized error message string.| - + property of the new instance with a system-supplied error message. This message takes into account the current system culture. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||A null reference (`Nothing` in Visual Basic).| +||The localized error message string.| + ]]> @@ -204,18 +204,18 @@ The message that describes the error. Initializes a new instance of the class with the specified error message. - property of the new instance using the value of the `message` parameter. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||A null reference (`Nothing` in Visual Basic).| -||The error message string.| - + property of the new instance using the value of the `message` parameter. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||A null reference (`Nothing` in Visual Basic).| +||The error message string.| + ]]> @@ -269,19 +269,19 @@ - - + + The object that contains serialized object data about the exception being thrown. The object that contains contextual information about the source or destination. The parameter is reserved for future use, and can be specified as . Initializes a new instance of the class with serialized data. - The parameter is . @@ -335,20 +335,20 @@ The exception that is the cause of the current exception. If the parameter is not , the current exception is raised in a block that handles the inner exception. Initializes a new instance of the class with the specified error message and inner exception. - property of the new instance using the value of the `message` parameter. - - An exception that is thrown as a direct result of a previous exception should include a reference to the previous exception in the property. The property returns the same value that is passed to the constructor, or `null` if the property does not supply the inner exception value to the constructor. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||The error message string.| -||The inner exception reference.| - + property of the new instance using the value of the `message` parameter. + + An exception that is thrown as a direct result of a previous exception should include a reference to the previous exception in the property. The property returns the same value that is passed to the constructor, or `null` if the property does not supply the inner exception value to the constructor. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||The error message string.| +||The inner exception reference.| + ]]> diff --git a/xml/System/Type.xml b/xml/System/Type.xml index f55b1f0a202..801285ed041 100644 --- a/xml/System/Type.xml +++ b/xml/System/Type.xml @@ -154,11 +154,11 @@ The code example uses the to invoke the - - - - - + + + + + Constructor mscorlib @@ -1379,8 +1379,8 @@ TopNamespace.Sub\+Namespace.ContainingClass+NestedClass, MyAssembly, Version=1.3 System.Type[] - - + + [System.Runtime.CompilerServices.Nullable(2)] @@ -1481,10 +1481,10 @@ TopNamespace.Sub\+Namespace.ContainingClass+NestedClass, MyAssembly, Version=1.3 System.Reflection.MemberInfo[] - - - - + + + + A bitwise combination of the enumeration values that indicates the type of member to search for. @@ -2063,7 +2063,7 @@ The `filter` argument can be a custom delegate of type System.Reflection.ConstructorInfo - + An array of objects representing the number, order, and type of the parameters for the desired constructor. @@ -2211,9 +2211,9 @@ The `filter` argument can be a custom delegate of type System.Reflection.ConstructorInfo - - - + + + [System.Runtime.CompilerServices.Nullable(1)] @@ -2221,7 +2221,7 @@ The `filter` argument can be a custom delegate of type - + A bitwise combination of the enumeration values that specify how the search is conducted. @@ -2360,10 +2360,10 @@ The `filter` argument can be a custom delegate of type System.Reflection.ConstructorInfo - - - - + + + + [System.Runtime.CompilerServices.Nullable(1)] @@ -2371,7 +2371,7 @@ The `filter` argument can be a custom delegate of type - + A bitwise combination of the enumeration values that specify how the search is conducted. @@ -2517,10 +2517,10 @@ The `filter` argument can be a custom delegate of type System.Reflection.ConstructorInfo - - - - + + + + [System.Runtime.CompilerServices.Nullable(1)] @@ -2528,7 +2528,7 @@ The `filter` argument can be a custom delegate of type - + A bitwise combination of the enumeration values that specify how the search is conducted. @@ -2786,7 +2786,7 @@ False System.Reflection.ConstructorInfo[] - + A bitwise combination of the enumeration values that specify how the search is conducted. @@ -3037,7 +3037,7 @@ If the current represents a generic type parameter, the System.String - + The value whose name is to be retrieved. @@ -3293,7 +3293,7 @@ If the current represents a generic type parameter, the System.Reflection.EventInfo - + The string containing the name of an event that is declared or inherited by the current . @@ -3393,8 +3393,8 @@ If the current represents a generic type parameter, the System.Reflection.EventInfo - - + + The string containing the name of an event which is declared or inherited by the current . @@ -3608,7 +3608,7 @@ If the current represents a generic type parameter, the System.Reflection.EventInfo[] - + A bitwise combination of the enumeration values that specify how the search is conducted. @@ -3728,7 +3728,7 @@ If the current represents a generic type parameter, the System.Reflection.FieldInfo - + The string containing the name of the data field to get. @@ -3811,8 +3811,8 @@ If the current represents a generic type parameter, the System.Reflection.FieldInfo - - + + The string containing the name of the data field to get. @@ -4039,7 +4039,7 @@ If the current represents a generic type parameter, the System.Reflection.FieldInfo[] - + A bitwise combination of the enumeration values that specify how the search is conducted. @@ -4554,7 +4554,7 @@ In .NET 6 and earlier versions, the method does System.Type - + The string containing the name of the interface to get. For generic interfaces, this is the mangled name. @@ -4640,8 +4640,8 @@ In .NET 6 and earlier versions, the method does System.Type - - + + The string containing the name of the interface to get. For generic interfaces, this is the mangled name. @@ -4732,7 +4732,7 @@ In .NET 6 and earlier versions, the method does System.Reflection.InterfaceMapping - + [System.Diagnostics.CodeAnalysis.DynamicallyAccessedMembers(System.Diagnostics.CodeAnalysis.DynamicallyAccessedMemberTypes.NonPublicMethods | System.Diagnostics.CodeAnalysis.DynamicallyAccessedMemberTypes.PublicMethods)] @@ -4923,7 +4923,7 @@ The current instance or argument is an open ge System.Reflection.MemberInfo[] - + The string containing the name of the public members to get. @@ -5036,8 +5036,8 @@ The current instance or argument is an open ge System.Reflection.MemberInfo[] - - + + The string containing the name of the members to get. @@ -5156,9 +5156,9 @@ The current instance or argument is an open ge System.Reflection.MemberInfo[] - - - + + + The string containing the name of the members to get. @@ -5394,7 +5394,7 @@ Members include properties, methods, constructors, fields, events, and nested ty System.Reflection.MemberInfo[] - + A bitwise combination of the enumeration values that specify how the search is conducted. @@ -5567,7 +5567,7 @@ This method can be used to find a constructed generic member given a member from System.Reflection.MethodInfo - + The string containing the name of the public method to get. @@ -5668,8 +5668,8 @@ This method can be used to find a constructed generic member given a member from System.Reflection.MethodInfo - - + + The string containing the name of the method to get. @@ -5798,8 +5798,8 @@ This method can be used to find a constructed generic member given a member from System.Reflection.MethodInfo - - + + The string containing the name of the public method to get. @@ -6028,9 +6028,9 @@ One of the elements in the array is - - + + + [System.Runtime.CompilerServices.Nullable(2)] @@ -6268,7 +6268,7 @@ One of the elements in the array is + [System.Runtime.CompilerServices.Nullable(1)] @@ -6276,9 +6276,9 @@ One of the elements in the array is - - + + + [System.Runtime.CompilerServices.Nullable(1)] @@ -6286,7 +6286,7 @@ One of the elements in the array is + The string containing the name of the method to get. @@ -6534,7 +6534,7 @@ One of the elements in the array is + [System.Runtime.CompilerServices.Nullable(1)] @@ -6542,10 +6542,10 @@ One of the elements in the array is - - - + + + + [System.Runtime.CompilerServices.Nullable(1)] @@ -6553,7 +6553,7 @@ One of the elements in the array is + The string containing the name of the method to get. @@ -6816,7 +6816,7 @@ One of the elements in the array is + [System.Runtime.CompilerServices.Nullable(1)] @@ -6824,10 +6824,10 @@ One of the elements in the array is - - - + + + + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 2, 1 })] @@ -6835,7 +6835,7 @@ One of the elements in the array is + The string containing the name of the method to get. @@ -7155,7 +7155,7 @@ In .NET 6 and earlier versions, the method does System.Reflection.MethodInfo[] - + A bitwise combination of the enumeration values that specify how the search is conducted. @@ -7275,7 +7275,7 @@ If the current represents a type parameter in the definition System.Type - + The string containing the name of the nested type to get. @@ -7369,8 +7369,8 @@ If the current represents a type parameter in the definition System.Type - - + + The string containing the name of the nested type to get. @@ -7574,7 +7574,7 @@ If the current represents a type parameter in the definition System.Type[] - + A bitwise combination of the enumeration values that specify how the search is conducted. @@ -7833,7 +7833,7 @@ If the current represents a type parameter in the definition System.Reflection.PropertyInfo[] - + A bitwise combination of the enumeration values that specify how the search is conducted. @@ -7960,7 +7960,7 @@ In .NET 6 and earlier versions, the method d System.Reflection.PropertyInfo - + The string containing the name of the public property to get. @@ -8037,8 +8037,8 @@ The following example retrieves the `Type` object of a user-defined class, retri System.Reflection.PropertyInfo - - + + The string containing the name of the property to get. @@ -8125,7 +8125,7 @@ The following example retrieves the `Type` object of a user-defined class, retri System.Reflection.PropertyInfo - + [System.Runtime.CompilerServices.Nullable(1)] @@ -8133,7 +8133,7 @@ The following example retrieves the `Type` object of a user-defined class, retri - + The string containing the name of the public property to get. @@ -8220,8 +8220,8 @@ The following example retrieves the `Type` object of a user-defined class, retri System.Reflection.PropertyInfo - - + + The string containing the name of the public property to get. @@ -8319,8 +8319,8 @@ The following example retrieves the `Type` object of a user-defined class, retri System.Reflection.PropertyInfo - - + + [System.Runtime.CompilerServices.Nullable(2)] @@ -8328,7 +8328,7 @@ The following example retrieves the `Type` object of a user-defined class, retri - + The string containing the name of the public property to get. @@ -8423,7 +8423,7 @@ The following example retrieves the `Type` object of a user-defined class, retri System.Reflection.PropertyInfo - + [System.Runtime.CompilerServices.Nullable(1)] @@ -8431,8 +8431,8 @@ The following example retrieves the `Type` object of a user-defined class, retri - - + + [System.Runtime.CompilerServices.Nullable(1)] @@ -8440,7 +8440,7 @@ The following example retrieves the `Type` object of a user-defined class, retri - + The string containing the name of the public property to get. @@ -8553,7 +8553,7 @@ The following example retrieves the `Type` object of a user-defined class, retri System.Reflection.PropertyInfo - + [System.Runtime.CompilerServices.Nullable(1)] @@ -8561,10 +8561,10 @@ The following example retrieves the `Type` object of a user-defined class, retri - - - - + + + + [System.Runtime.CompilerServices.Nullable(1)] @@ -8572,7 +8572,7 @@ The following example retrieves the `Type` object of a user-defined class, retri - + The string containing the name of the property to get. @@ -8670,7 +8670,7 @@ The following example retrieves the `Type` object of a user-defined class, retri System.Reflection.PropertyInfo - + [System.Runtime.CompilerServices.Nullable(1)] @@ -8678,10 +8678,10 @@ The following example retrieves the `Type` object of a user-defined class, retri - - - - + + + + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 2, 1 })] @@ -8689,7 +8689,7 @@ The following example retrieves the `Type` object of a user-defined class, retri - + The string containing the name of the property to get. @@ -9577,8 +9577,8 @@ Type.GetType("System.Collections.Generic.Dictionary`2[System.String,[MyType,MyAs System.Type - - + + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 2, 1, 2 })] @@ -9586,7 +9586,7 @@ Type.GetType("System.Collections.Generic.Dictionary`2[System.String,[MyType,MyAs - + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 2, 2, 1, 2 })] @@ -9689,8 +9689,8 @@ Calling this method overload is the same as calling the System.Type - - + + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 2, 1, 2 })] @@ -9698,7 +9698,7 @@ Calling this method overload is the same as calling the - + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 2, 2, 1, 2 })] @@ -9706,7 +9706,7 @@ Calling this method overload is the same as calling the - + The name of the type to get. If the parameter is provided, the type name can be any string that is capable of resolving. If the parameter is provided or if standard type resolution is used, must be an assembly-qualified name (see ), unless the type is in the currently executing assembly or in mscorlib.dll/System.Private.CoreLib.dll, in which case it's sufficient to supply the type name qualified by its namespace. @@ -9822,8 +9822,8 @@ Calling this method overload is the same as calling the System.Type - - + + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 2, 1, 2 })] @@ -9831,7 +9831,7 @@ Calling this method overload is the same as calling the - + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 2, 2, 1, 2 })] @@ -9839,8 +9839,8 @@ Calling this method overload is the same as calling the - - + + The name of the type to get. If the parameter is provided, the type name can be any string that is capable of resolving. If the parameter is provided or if standard type resolution is used, must be an assembly-qualified name (see ), unless the type is in the currently executing assembly or in mscorlib.dll/System.Private.CoreLib.dll, in which case it's sufficient to supply the type name qualified by its namespace. @@ -9944,7 +9944,7 @@ Calling this method overload is the same as calling the System.Type[] - + An array of objects whose types to determine. @@ -10015,7 +10015,7 @@ Calling this method overload is the same as calling the System.TypeCode - + The type whose underlying type code to get. @@ -10151,7 +10151,7 @@ Calling this method overload is the same as calling the System.Type - + The CLSID of the type to get. @@ -10249,8 +10249,8 @@ Calling this method overload is the same as calling the System.Type - - + + The CLSID of the type to get. @@ -10354,8 +10354,8 @@ Calling this method overload is the same as calling the System.Type - - + + The CLSID of the type to get. @@ -10450,9 +10450,9 @@ Calling this method overload is the same as calling the System.Type - - - + + + The CLSID of the type to get. @@ -10641,7 +10641,7 @@ Calling this method overload is the same as calling the System.Type - + The ProgID of the type to get. @@ -10706,8 +10706,8 @@ Calling this method overload is the same as calling the System.Type - - + + The ProgID of the type to get. @@ -10793,7 +10793,7 @@ Calling this method overload is the same as calling the System.Type - + [System.Runtime.CompilerServices.Nullable(1)] @@ -10801,7 +10801,7 @@ Calling this method overload is the same as calling the - + The progID of the type to get. @@ -10881,7 +10881,7 @@ Calling this method overload is the same as calling the System.Type - + [System.Runtime.CompilerServices.Nullable(1)] @@ -10889,8 +10889,8 @@ Calling this method overload is the same as calling the - - + + The progID of the to get. @@ -10963,7 +10963,7 @@ Calling this method overload is the same as calling the System.RuntimeTypeHandle - + The object for which to get the type handle. @@ -11259,7 +11259,7 @@ Calling this method overload is the same as calling the System.Object - + [System.Runtime.CompilerServices.Nullable(1)] @@ -11267,10 +11267,10 @@ Calling this method overload is the same as calling the - - - - + + + + The string containing the name of the constructor, method, property, or field member to invoke. @@ -11488,7 +11488,7 @@ Calling this method overload is the same as calling the System.Object - + [System.Runtime.CompilerServices.Nullable(1)] @@ -11496,11 +11496,11 @@ Calling this method overload is the same as calling the - - - - - + + + + + The string containing the name of the constructor, method, property, or field member to invoke. @@ -11707,7 +11707,7 @@ Calling this method overload is the same as calling the System.Object - + [System.Runtime.CompilerServices.Nullable(1)] @@ -11715,13 +11715,13 @@ Calling this method overload is the same as calling the - - - - - - - + + + + + + + [System.Runtime.CompilerServices.Nullable(new System.Byte[] { 2, 1 })] @@ -12255,7 +12255,7 @@ GetType(Array).IsAssignableFrom(type) System.Boolean - + [System.Diagnostics.CodeAnalysis.NotNullWhen(true)] @@ -13149,7 +13149,7 @@ Byref-like structures are declared using `ref struct` keyword in C#. An instance System.Boolean - + The value to be tested. @@ -13204,7 +13204,7 @@ Byref-like structures are declared using `ref struct` keyword in C#. An instance System.Boolean - + [System.Diagnostics.CodeAnalysis.NotNullWhen(true)] @@ -13744,7 +13744,7 @@ Byref-like structures are declared using `ref struct` keyword in C#. An instance System.Boolean - + [System.Diagnostics.CodeAnalysis.NotNullWhen(true)] @@ -15387,7 +15387,7 @@ A signature type is a restricted type that can be passed to the System.Boolean - + The type to compare with the current type. @@ -16708,8 +16708,8 @@ The following example uses the method to c System.Boolean - - + + The first object to compare. @@ -16764,8 +16764,8 @@ The following example uses the method to c System.Boolean - - + + The first object to compare. @@ -16890,9 +16890,9 @@ The following example uses the method to c System.Type - - - + + + The assembly-qualified name of the to get. @@ -17066,11 +17066,11 @@ The following example uses the method to c System.Void - - - - - + + + + + Reserved for future use. Must be IID_NULL. @@ -17117,9 +17117,9 @@ The following example uses the method to c System.Void - - - + + + The type information to return. @@ -17164,7 +17164,7 @@ The following example uses the method to c System.Void - + When this method returns, points to a location that receives the number of type information interfaces provided by the object. @@ -17207,14 +17207,14 @@ The following example uses the method to c System.Void - - - - - - - - + + + + + + + + Identifies the member. diff --git a/xml/System/TypeAccessException.xml b/xml/System/TypeAccessException.xml index 228d64f1240..d1eab2de283 100644 --- a/xml/System/TypeAccessException.xml +++ b/xml/System/TypeAccessException.xml @@ -60,15 +60,15 @@ The exception that is thrown when a method attempts to use a type that it does not have access to. - is thrown when a method attempts to cast an object to a type that is not accessible from the method. For example, an anonymously hosted dynamic method cannot access a security-critical type because the method is [transparent](/dotnet/framework/misc/security-transparent-code). If the method contains a instruction that casts an object to a security-critical type, or to a generic type that has a security-critical type as one of its type parameters, is thrown by the JIT compiler. - - Similarly, is thrown for a dynamic method that uses an internal type from another assembly. A method might not have access to its containing type, its return type, or one of its parameter types. - - Apps compiled by using the .NET Native tool chain may throw a [MissingMetadataException](/windows/uwp/dotnet-native/missingmetadataexception-class-net-native) exception at run time. `MissingMetadataException` is an internal-only exception type derived from . The exception indicates that metadata needed for the successful execution of an app is not present at run time. You should not use a `try`/`catch` block to handle the exception. Instead, you should determine what metadata is missing and modify your app's runtime directives file to ensure that it is present at run time. - + is thrown when a method attempts to cast an object to a type that is not accessible from the method. For example, an anonymously hosted dynamic method cannot access a security-critical type because the method is [transparent](/dotnet/framework/misc/security-transparent-code). If the method contains a instruction that casts an object to a security-critical type, or to a generic type that has a security-critical type as one of its type parameters, is thrown by the JIT compiler. + + Similarly, is thrown for a dynamic method that uses an internal type from another assembly. A method might not have access to its containing type, its return type, or one of its parameter types. + + Apps compiled by using the .NET Native tool chain may throw a [MissingMetadataException](/windows/uwp/dotnet-native/missingmetadataexception-class-net-native) exception at run time. `MissingMetadataException` is an internal-only exception type derived from . The exception indicates that metadata needed for the successful execution of an app is not present at run time. You should not use a `try`/`catch` block to handle the exception. Instead, you should determine what metadata is missing and modify your app's runtime directives file to ensure that it is present at run time. + ]]> @@ -122,18 +122,18 @@ Initializes a new instance of the class with a system-supplied message that describes the error. - property of the new instance to a system-supplied message that describes the error, such as "Attempt to access the type failed." This message takes the current system culture into account. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||A null reference (`Nothing` in Visual Basic).| -||The localized error message string.| - + property of the new instance to a system-supplied message that describes the error, such as "Attempt to access the type failed." This message takes the current system culture into account. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||A null reference (`Nothing` in Visual Basic).| +||The localized error message string.| + ]]> Handling and Throwing Exceptions @@ -180,16 +180,16 @@ The message that describes the exception. The caller of this constructor must ensure that this string has been localized for the current system culture. Initializes a new instance of the class with a specified message that describes the error. - . - -|Property|Value| -|--------------|-----------| -||A null reference (`Nothing` in Visual Basic).| -||The error message string specified in `message`.| - + . + +|Property|Value| +|--------------|-----------| +||A null reference (`Nothing` in Visual Basic).| +||The error message string specified in `message`.| + ]]> Handling and Throwing Exceptions @@ -239,19 +239,19 @@ - - + + The object that holds the serialized data. The contextual information about the source or destination. Initializes a new instance of the class with serialized data. - XML and SOAP Serialization @@ -300,18 +300,18 @@ The exception that is the cause of the current exception. If the parameter is not , the current exception is raised in a block that handles the inner exception. Initializes a new instance of the class with a specified error message and a reference to the inner exception that is the cause of this exception. - property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||A null reference (`Nothing` in Visual Basic).| -||The error message string specified in `message`.| - + property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||A null reference (`Nothing` in Visual Basic).| +||The error message string specified in `message`.| + ]]> Handling and Throwing Exceptions diff --git a/xml/System/TypeInitializationException.xml b/xml/System/TypeInitializationException.xml index 06d214cf11c..fb914f47683 100644 --- a/xml/System/TypeInitializationException.xml +++ b/xml/System/TypeInitializationException.xml @@ -195,8 +195,8 @@ System.Void - - + + The that holds the serialized object data about the exception being thrown. diff --git a/xml/System/TypeLoadException.xml b/xml/System/TypeLoadException.xml index f449c0c0d32..e638c985f66 100644 --- a/xml/System/TypeLoadException.xml +++ b/xml/System/TypeLoadException.xml @@ -78,17 +78,17 @@ The exception that is thrown when type-loading failures occur. - is thrown when the common language runtime cannot find the assembly, the type within the assembly, or cannot load the type. The property contains more detailed information that can help you identify the cause of the exception. - - uses the HRESULT COR_E_TYPELOAD, that has the value 0x80131522. - - For a list of initial property values for an instance of , see the constructors. - + is thrown when the common language runtime cannot find the assembly, the type within the assembly, or cannot load the type. The property contains more detailed information that can help you identify the cause of the exception. + + uses the HRESULT COR_E_TYPELOAD, that has the value 0x80131522. + + For a list of initial property values for an instance of , see the constructors. + The exact timing of when statically referenced types are loaded is unspecified. This exception may be thrown before the method that references the missing type starts executing. - + ]]> @@ -146,18 +146,18 @@ The exact timing of when statically referenced types are loaded is unspecified. Initializes a new instance of the class. - property of the new instance to a system-supplied message that describes the error, such as "A failure has occurred while loading a type." This message takes into account the current system culture. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||A null reference (`Nothing` in Visual Basic).| -||The localized error message string.| - + property of the new instance to a system-supplied message that describes the error, such as "A failure has occurred while loading a type." This message takes into account the current system culture. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||A null reference (`Nothing` in Visual Basic).| +||The localized error message string.| + ]]> @@ -211,27 +211,27 @@ The exact timing of when statically referenced types are loaded is unspecified. The message that describes the error. Initializes a new instance of the class with a specified error message. - . - -|Property|Value| -|--------------|-----------| -||A null reference (`Nothing` in Visual Basic).| -||The error message string.| - - - -## Examples - The following code example demonstrates the constructor. It contains a method that generates a with a custom message, and displays the error message to the console. - + . + +|Property|Value| +|--------------|-----------| +||A null reference (`Nothing` in Visual Basic).| +||The error message string.| + + + +## Examples + The following code example demonstrates the constructor. It contains a method that generates a with a custom message, and displays the error message to the console. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/TypeLoadException_Constructor2/CPP/typeloadexception_constructor2.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System/TypeLoadException/.ctor/typeloadexception_constructor2.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/TypeLoadException_Constructor2/VB/typeloadexception_constructor2.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/TypeLoadException_Constructor2/VB/typeloadexception_constructor2.vb" id="Snippet1"::: + ]]> @@ -282,28 +282,28 @@ The exact timing of when statically referenced types are loaded is unspecified. - - + + The object that holds the serialized object data. The contextual information about the source or destination. Initializes a new instance of the class with serialized data. - The object is . @@ -361,27 +361,27 @@ The exact timing of when statically referenced types are loaded is unspecified. The exception that is the cause of the current exception. If the parameter is not , the current exception is raised in a block that handles the inner exception. Initializes a new instance of the class with a specified error message and a reference to the inner exception that is the cause of this exception. - property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||The inner exception reference.| -||The error message string.| - - - -## Examples - The following code example demonstrates the constructor. It contains a method that generates a , catches that exception, and throws a new with a custom message, including the original as the inner exception. - + property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||The inner exception reference.| +||The error message string.| + + + +## Examples + The following code example demonstrates the constructor. It contains a method that generates a , catches that exception, and throws a new with a custom message, including the original as the inner exception. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/TypeLoadException_Constructor3/CPP/typeloadexception_constructor3.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System/TypeLoadException/.ctor/typeloadexception_constructor3.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/TypeLoadException_Constructor3/VB/typeloadexception_constructor3.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/TypeLoadException_Constructor3/VB/typeloadexception_constructor3.vb" id="Snippet1"::: + ]]> @@ -440,31 +440,31 @@ The exact timing of when statically referenced types are loaded is unspecified. System.Void - - + + The object that holds the serialized object data. The contextual information about the source or destination. Sets the object with the class name, method name, resource ID, and additional exception information. - 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 [XML and SOAP Serialization](/dotnet/standard/serialization/xml-and-soap-serialization). - - - -## Examples - - The following example generates an exception, and serializes the exception data to a file, and then reconstitutes the exception. For this code example to run, you must provide the fully qualified assembly name. For information about how to obtain the fully qualified assembly name, see [Assembly Names](/dotnet/standard/assembly/names). - + 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 [XML and SOAP Serialization](/dotnet/standard/serialization/xml-and-soap-serialization). + + + +## Examples + + The following example generates an exception, and serializes the exception data to a file, and then reconstitutes the exception. For this code example to run, you must provide the fully qualified assembly name. For information about how to obtain the fully qualified assembly name, see [Assembly Names](/dotnet/standard/assembly/names). + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/TypeLoadException_GetObjectData/CPP/typeloadexception_getobjectdata.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System/TypeLoadException/.ctor/typeloadexception_getobjectdata.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/TypeLoadException_GetObjectData/VB/typeloadexception_getobjectdata.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/TypeLoadException_GetObjectData/VB/typeloadexception_getobjectdata.vb" id="Snippet1"::: + ]]> The object is . @@ -520,22 +520,22 @@ The exact timing of when statically referenced types are loaded is unspecified. Gets the error message for this exception. The error message string. - . The error message should be localized. - - This property is read-only. - - - -## Examples - The following example attempts to load a non-existent type from the mscorlib assembly. The resulting exception is caught, and the and values are displayed. For this code example to run, you must provide the fully qualified assembly name. For information about how to obtain the fully qualified assembly name, see [Assembly Names](/dotnet/standard/assembly/names). - + . The error message should be localized. + + This property is read-only. + + + +## Examples + The following example attempts to load a non-existent type from the mscorlib assembly. The resulting exception is caught, and the and values are displayed. For this code example to run, you must provide the fully qualified assembly name. For information about how to obtain the fully qualified assembly name, see [Assembly Names](/dotnet/standard/assembly/names). + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/TypeLoadException_TypeName/CPP/typeloadexception_typename.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System/TypeLoadException/Message/typeloadexception_typename.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/TypeLoadException_TypeName/VB/typeloadexception_typename.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/TypeLoadException_TypeName/VB/typeloadexception_typename.vb" id="Snippet1"::: + ]]> @@ -582,20 +582,20 @@ The exact timing of when statically referenced types are loaded is unspecified. Gets the fully qualified name of the type that causes the exception. The fully qualified type name. - and values are displayed. For this code example to run, you must provide the fully qualified assembly name. For information about how to obtain the fully qualified assembly name, see [Assembly Names](/dotnet/standard/assembly/names). - + and values are displayed. For this code example to run, you must provide the fully qualified assembly name. For information about how to obtain the fully qualified assembly name, see [Assembly Names](/dotnet/standard/assembly/names). + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/TypeLoadException_TypeName/CPP/typeloadexception_typename.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System/TypeLoadException/Message/typeloadexception_typename.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/TypeLoadException_TypeName/VB/typeloadexception_typename.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/TypeLoadException_TypeName/VB/typeloadexception_typename.vb" id="Snippet1"::: + ]]> - When overriding in a derived class, be sure to call the base class's property. - + When overriding in a derived class, be sure to call the base class's property. + This property is read-only. diff --git a/xml/System/UInt16.xml b/xml/System/UInt16.xml index efb362dacc6..6c7c4aaed18 100644 --- a/xml/System/UInt16.xml +++ b/xml/System/UInt16.xml @@ -375,7 +375,7 @@ System.Int32 - + An object to compare, or . diff --git a/xml/System/UInt32.xml b/xml/System/UInt32.xml index 7867bff5871..9bf74efa41f 100644 --- a/xml/System/UInt32.xml +++ b/xml/System/UInt32.xml @@ -375,7 +375,7 @@ System.Int32 - + An object to compare, or . diff --git a/xml/System/UInt64.xml b/xml/System/UInt64.xml index b2fd05273fa..0c07ff564fc 100644 --- a/xml/System/UInt64.xml +++ b/xml/System/UInt64.xml @@ -373,7 +373,7 @@ System.Int32 - + An object to compare, or . diff --git a/xml/System/UIntPtr.xml b/xml/System/UIntPtr.xml index 5f636552709..f2a611324c4 100644 --- a/xml/System/UIntPtr.xml +++ b/xml/System/UIntPtr.xml @@ -5412,8 +5412,8 @@ This member is an explicit interface member implementation. It can be used only System.Void - - + + The object to populate with data. diff --git a/xml/System/UnauthorizedAccessException.xml b/xml/System/UnauthorizedAccessException.xml index afc09f11df0..d9fe33d57cc 100644 --- a/xml/System/UnauthorizedAccessException.xml +++ b/xml/System/UnauthorizedAccessException.xml @@ -72,22 +72,22 @@ The exception that is thrown when the operating system denies access because of an I/O error or a specific type of security error. - exception is typically thrown by a method that wraps a Windows API call. To find the reasons for the exception, examine the text of the exception object's property. - - uses the `HRESULT` `COR_E_UNAUTHORIZEDACCESS`, which has the value 0x80070005. - - - -## Examples - The following example illustrates the exception that is thrown when attempting to write to a read-only file. - + exception is typically thrown by a method that wraps a Windows API call. To find the reasons for the exception, examine the text of the exception object's property. + + uses the `HRESULT` `COR_E_UNAUTHORIZEDACCESS`, which has the value 0x80070005. + + + +## Examples + The following example illustrates the exception that is thrown when attempting to write to a read-only file. + :::code language="csharp" source="~/snippets/csharp/System/UnauthorizedAccessException/Overview/withio.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System/UnauthorizedAccessException/Overview/withio.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.unauthorizedaccessexception/vb/withio.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.unauthorizedaccessexception/vb/withio.vb" id="Snippet1"::: + ]]> @@ -145,18 +145,18 @@ Initializes a new instance of the class. - property of the new instance to a system-supplied message that describes the error, such as "Attempted to perform an unauthorized operation." This message takes into account the current system culture. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||A null reference (`Nothing` in Visual Basic).| -||The localized error message string.| - + property of the new instance to a system-supplied message that describes the error, such as "Attempted to perform an unauthorized operation." This message takes into account the current system culture. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||A null reference (`Nothing` in Visual Basic).| +||The localized error message string.| + ]]> @@ -204,18 +204,18 @@ The message that describes the error. Initializes a new instance of the class with a specified error message. - . - -|Property|Value| -|--------------|-----------| -||A null reference (`Nothing` in Visual Basic).| -||The error message string.| - + . + +|Property|Value| +|--------------|-----------| +||A null reference (`Nothing` in Visual Basic).| +||The error message string.| + ]]> @@ -270,8 +270,8 @@ - - + + The that holds the serialized object data about the exception being thrown. @@ -325,18 +325,18 @@ The exception that is the cause of the current exception. If the parameter is not a null reference ( in Visual Basic), the current exception is raised in a block that handles the inner exception. Initializes a new instance of the class with a specified error message and a reference to the inner exception that is the cause of this exception. - property. The property returns the same value that is passed into the constructor, or a null reference (`Nothing` in Visual Basic) if the property does not supply the inner exception value to the constructor. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||The inner exception reference.| -||The error message string.| - + property. The property returns the same value that is passed into the constructor, or a null reference (`Nothing` in Visual Basic) if the property does not supply the inner exception value to the constructor. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||The inner exception reference.| +||The error message string.| + ]]> diff --git a/xml/System/Uri.xml b/xml/System/Uri.xml index 4328488b777..77427ee058a 100644 --- a/xml/System/Uri.xml +++ b/xml/System/Uri.xml @@ -299,8 +299,8 @@ The following code snippet shows example values of the various properties on the - - + + An instance of the class containing the information required to serialize the new instance. @@ -413,7 +413,7 @@ The following code snippet shows example values of the various properties on the - + [System.Diagnostics.CodeAnalysis.StringSyntax("Uri")] @@ -421,7 +421,7 @@ The following code snippet shows example values of the various properties on the - + A string that identifies the resource to be represented by the instance. Note that an IPv6 address in string form must be enclosed within brackets. For example, "http://[2607:f8b0:400d:c06::69]". @@ -972,8 +972,8 @@ The URI formed by combining and - + + [System.Runtime.CompilerServices.Nullable(2)] @@ -981,7 +981,7 @@ The URI formed by combining and + The base URI. @@ -2014,7 +2014,7 @@ If you used an escaped string to construct this instance (for example, `"http:// System.String - + [System.Runtime.CompilerServices.Nullable(2)] @@ -2215,7 +2215,7 @@ If you used an escaped string to construct this instance (for example, `"http:// System.Int32 - + The hexadecimal digit (0-9, a-f, A-F) to convert. @@ -2401,7 +2401,7 @@ If you used an escaped string to construct this instance (for example, `"http:// System.String - + One of the enumeration values that specifies the end of the URI portion to return. @@ -2480,8 +2480,8 @@ The following examples show a URI and the results of calling System.Void - - + + The information required to serialize the . @@ -2525,7 +2525,7 @@ The following examples show a URI and the results of calling System.String - + The character to convert to hexadecimal representation. @@ -2583,8 +2583,8 @@ The following examples show a URI and the results of calling System.Char - - + + The hexadecimal representation of a character. @@ -2877,7 +2877,7 @@ The following examples show a URI and the results of calling System.Boolean - + The to test. @@ -3081,7 +3081,7 @@ The following examples show a URI and the results of calling System.Boolean - + The character to test. @@ -3187,7 +3187,7 @@ The following examples show a URI and the results of calling System.Boolean - + The character to validate. @@ -3247,8 +3247,8 @@ The following examples show a URI and the results of calling System.Boolean - - + + The string to check. @@ -3384,7 +3384,7 @@ The following examples show a URI and the results of calling System.Boolean - + The character to test. @@ -3732,7 +3732,7 @@ The following examples show a URI and the results of calling System.String - + The URI to compare to the current URI. @@ -4647,8 +4647,8 @@ The following examples show a URI and the results of calling System.Void - - + + The information required to serialize the . @@ -5209,7 +5209,7 @@ The following examples show a URI and the results of calling System.String - + The string to convert. diff --git a/xml/System/UriFormatException.xml b/xml/System/UriFormatException.xml index 5666248965a..bfb8304cd87 100644 --- a/xml/System/UriFormatException.xml +++ b/xml/System/UriFormatException.xml @@ -58,16 +58,16 @@ The exception that is thrown when an invalid Uniform Resource Identifier (URI) is detected. - is thrown by the Uri class constructor if the supplied URI could not be correctly parsed. The format for a valid URI is defined in RFC 2396. - - The text of the property indicates the reason that the exception was thrown. - + is thrown by the Uri class constructor if the supplied URI could not be correctly parsed. The format for a valid URI is defined in RFC 2396. + + The text of the property indicates the reason that the exception was thrown. + > [!NOTE] -> This exception is not included in the [.NET for Windows Store apps](https://go.microsoft.com/fwlink/?LinkID=247912) or the [Portable Class Library](/dotnet/standard/cross-platform/cross-platform-development-with-the-portable-class-library), but it is thrown by some members that are. To catch the exception in that case, write a `catch` statement for instead. - +> This exception is not included in the [.NET for Windows Store apps](https://go.microsoft.com/fwlink/?LinkID=247912) or the [Portable Class Library](/dotnet/standard/cross-platform/cross-platform-development-with-the-portable-class-library), but it is thrown by some members that are. To catch the exception in that case, write a `catch` statement for instead. + ]]> @@ -125,11 +125,11 @@ Initializes a new instance of the class. - class with all fields set to `null`. - + class with all fields set to `null`. + ]]> @@ -185,11 +185,11 @@ The error message string. Initializes a new instance of the class with the specified message. - instance with the property set to the value of `textString`. - + instance with the property set to the value of `textString`. + ]]> @@ -244,19 +244,19 @@ - - + + A that contains the information that is required to serialize the new . A that contains the source of the serialized stream that is associated with the new . Initializes a new instance of the class from the specified and instances. - interface for the class. - + interface for the class. + ]]> @@ -313,18 +313,18 @@ The exception that is the cause of the current exception. If the innerException parameter is not , the current exception is raised in a block that handles the inner exception. Initializes a new instance of the class with a specified error message and a reference to the inner exception that is the cause of this exception. - property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||`null`.| -||The error message string specified in `message`.| - + property. The property returns the same value that is passed into the constructor, or `null` if the property does not supply the inner exception value to the constructor. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||`null`.| +||The error message string specified in `message`.| + ]]> Handling and Throwing Exceptions @@ -374,8 +374,8 @@ System.Void - - + + A that will hold the serialized data for the . diff --git a/xml/System/Version.xml b/xml/System/Version.xml index 393a52ae610..4de8d049dc8 100644 --- a/xml/System/Version.xml +++ b/xml/System/Version.xml @@ -618,7 +618,7 @@ The following example uses the System.Int32 - + An object to compare, or . diff --git a/xml/System/WeakReference.xml b/xml/System/WeakReference.xml index a6f4792d782..7df25ebb999 100644 --- a/xml/System/WeakReference.xml +++ b/xml/System/WeakReference.xml @@ -75,22 +75,22 @@ Represents a weak reference, which references an object while still allowing that object to be reclaimed by garbage collection. - of objects keyed by an index value. The property for the objects is an object in a byte array that represents data. - - The example randomly accesses objects in the cache. If an object is reclaimed for garbage collection, a new data object is regenerated; otherwise, the object is available to access because of the weak reference. - + of objects keyed by an index value. The property for the objects is an object in a byte array that represents data. + + The example randomly accesses objects in the cache. If an object is reclaimed for garbage collection, a new data object is regenerated; otherwise, the object is available to access because of the weak reference. + :::code language="csharp" source="~/snippets/csharp/System/WeakReference/Overview/program.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System/WeakReference/Overview/program.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/WeakReference/vb/Module1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/WeakReference/vb/Module1.vb" id="Snippet1"::: + ]]> @@ -149,11 +149,11 @@ The object to track or . Initializes a new instance of the class, referencing the specified object. - @@ -210,20 +210,20 @@ Indicates when to stop tracking the object. If , the object is tracked after finalization; if , the object is only tracked until finalization. Initializes a new instance of the class, referencing the specified object and using the specified resurrection tracking. - class. - + class. + :::code language="csharp" source="~/snippets/csharp/System/WeakReference/Overview/program.cs" id="Snippet2"::: :::code language="fsharp" source="~/snippets/fsharp/System/WeakReference/Overview/program.fs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/WeakReference/vb/Module1.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/WeakReference/vb/Module1.vb" id="Snippet2"::: + ]]> @@ -282,19 +282,19 @@ - - + + An object that holds all the data needed to serialize or deserialize the current object. (Reserved) Describes the source and destination of the serialized stream specified by . Initializes a new instance of the class, using deserialized data from the specified serialization and stream objects. - @@ -409,21 +409,21 @@ System.Void - - + + An object that holds all the data needed to serialize or deserialize the current object. (Reserved) The location where serialized data is stored and retrieved. Populates a object with all the data needed to serialize the current object. - object. - - The `context` parameter is reserved and is not currently used in the execution of this method. - + object. + + The `context` parameter is reserved and is not currently used in the execution of this method. + ]]> @@ -481,11 +481,11 @@ if the object referenced by the current object has not been garbage collected and is still accessible; otherwise, . - property returns `true`, using this property is not recommended unless you are testing only for a `false` return value. - + property returns `true`, using this property is not recommended unless you are testing only for a `false` return value. + ]]> @@ -547,20 +547,20 @@ if the object referenced by the current object has been garbage collected; otherwise, a reference to the object referenced by the current object. - class. - + class. + :::code language="csharp" source="~/snippets/csharp/System/WeakReference/Overview/program.cs" id="Snippet3"::: :::code language="fsharp" source="~/snippets/fsharp/System/WeakReference/Overview/program.fs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/WeakReference/vb/Module1.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/WeakReference/vb/Module1.vb" id="Snippet3"::: + ]]> The reference to the target object is invalid. This exception can be thrown while setting this property if the value is a null reference or if the object has been finalized during the set operation. @@ -612,11 +612,11 @@ if the object the current object refers to is tracked after finalization; or if the object is only tracked until finalization. - constructor. - + constructor. + ]]> diff --git a/xml/System/WeakReference`1.xml b/xml/System/WeakReference`1.xml index c932ab8fbc3..873d256b089 100644 --- a/xml/System/WeakReference`1.xml +++ b/xml/System/WeakReference`1.xml @@ -83,11 +83,11 @@ The type of the object referenced. Represents a typed weak reference, which references an object while still allowing that object to be reclaimed by garbage collection. - @@ -288,8 +288,8 @@ System.Void - - + + An object that holds all the data necessary to serialize or deserialize the current object. diff --git a/xml/index.xml b/xml/index.xml index d564f9a4fd8..70732df65b6 100644 --- a/xml/index.xml +++ b/xml/index.xml @@ -156307,51 +156307,15 @@ [00 24 00 00 04 80 00 00 94 00 00 00 06 02 00 00 00 24 00 00 52 53 41 31 00 04 00 00 01 00 01 00 07 d1 fa 57 c4 ae d9 f0 a3 2e 84 aa 0f ae fd 0d e9 e8 fd 6a ec 8f 87 fb 03 76 6c 83 4c 99 92 1e b2 3b e7 9a d9 d5 dc c1 dd 9a d2 36 13 21 02 90 0b 72 3c f9 80 95 7f c4 e1 77 10 8f c6 07 77 4f 29 e8 32 0e 92 ea 05 ec e4 e8 21 c0 a5 ef e8 f1 64 5c 4c 0c 93 c1 ab 99 28 5d 62 2c aa 65 2c 1d fa d6 3d 74 5d 6f 2d e5 f1 7e 5e af 0f c4 96 3d 26 1c 8a 12 43 65 18 20 6d c0 93 34 4d 5a d2 93 ] - + System.CLSCompliant(true) - + System.Diagnostics.Debuggable(System.Diagnostics.DebuggableAttribute+DebuggingModes.IgnoreSymbolStoreSequencePoints) - - System.Reflection.AssemblyCompany("Mono development team") - - - System.Reflection.AssemblyCopyright("(c) Various Mono authors") - - - System.Reflection.AssemblyDefaultAlias("System.Reflection.DispatchProxy.dll") - - - System.Reflection.AssemblyDescription("System.Reflection.DispatchProxy.dll") - - - System.Reflection.AssemblyFileVersion("4.0.50524.0") - - - System.Reflection.AssemblyInformationalVersion("4.0.50524.0") - - - System.Reflection.AssemblyProduct("Mono Common Language Infrastructure") - - - System.Reflection.AssemblyTitle("System.Reflection.DispatchProxy.dll") - - - System.Resources.NeutralResourcesLanguage("en-US") - - - System.Resources.SatelliteContractVersion("2.0.5.0") - - + System.Runtime.CompilerServices.RuntimeCompatibility(WrapNonExceptionThrows=true) - - System.Runtime.InteropServices.ComVisible(false) - - - System.Security.SecurityCritical - System.Diagnostics.Debuggable(System.Diagnostics.DebuggableAttribute+DebuggingModes.Default | System.Diagnostics.DebuggableAttribute+DebuggingModes.DisableOptimizations | System.Diagnostics.DebuggableAttribute+DebuggingModes.EnableEditAndContinue | System.Diagnostics.DebuggableAttribute+DebuggingModes.IgnoreSymbolStoreSequencePoints) @@ -156906,48 +156870,9 @@ System.CLSCompliant(true) - - System.Diagnostics.Debuggable(System.Diagnostics.DebuggableAttribute+DebuggingModes.IgnoreSymbolStoreSequencePoints) - - - System.Reflection.AssemblyCompany("Mono development team") - - - System.Reflection.AssemblyCopyright("(c) Various Mono authors") - - - System.Reflection.AssemblyDefaultAlias("System.Xml.XPath.XmlDocument.dll") - - - System.Reflection.AssemblyDescription("System.Xml.XPath.XmlDocument.dll") - - - System.Reflection.AssemblyFileVersion("4.0.50524.0") - - - System.Reflection.AssemblyInformationalVersion("4.0.50524.0") - - - System.Reflection.AssemblyProduct("Mono Common Language Infrastructure") - - - System.Reflection.AssemblyTitle("System.Xml.XPath.XmlDocument.dll") - - - System.Resources.NeutralResourcesLanguage("en-US") - - - System.Resources.SatelliteContractVersion("2.0.5.0") - System.Runtime.CompilerServices.RuntimeCompatibility(WrapNonExceptionThrows=true) - - System.Runtime.InteropServices.ComVisible(false) - - - System.Security.SecurityCritical - System.Reflection.AssemblyCompany("Microsoft Corporation") @@ -157248,51 +157173,33 @@ [00 24 00 00 04 80 00 00 94 00 00 00 06 02 00 00 00 24 00 00 52 53 41 31 00 04 00 00 01 00 01 00 07 d1 fa 57 c4 ae d9 f0 a3 2e 84 aa 0f ae fd 0d e9 e8 fd 6a ec 8f 87 fb 03 76 6c 83 4c 99 92 1e b2 3b e7 9a d9 d5 dc c1 dd 9a d2 36 13 21 02 90 0b 72 3c f9 80 95 7f c4 e1 77 10 8f c6 07 77 4f 29 e8 32 0e 92 ea 05 ec e4 e8 21 c0 a5 ef e8 f1 64 5c 4c 0c 93 c1 ab 99 28 5d 62 2c aa 65 2c 1d fa d6 3d 74 5d 6f 2d e5 f1 7e 5e af 0f c4 96 3d 26 1c 8a 12 43 65 18 20 6d c0 93 34 4d 5a d2 93 ] - + System.CLSCompliant(true) - + System.Diagnostics.Debuggable(System.Diagnostics.DebuggableAttribute+DebuggingModes.IgnoreSymbolStoreSequencePoints) - - System.Reflection.AssemblyCompany("Mono development team") - - - System.Reflection.AssemblyCopyright("(c) Various Mono authors") - - + System.Reflection.AssemblyDefaultAlias("Microsoft.CSharp.dll") - + System.Reflection.AssemblyDescription("Microsoft.CSharp.dll") - - System.Reflection.AssemblyFileVersion("4.6.57.0") - - - System.Reflection.AssemblyInformationalVersion("4.6.57.0") - - - System.Reflection.AssemblyProduct("Mono Common Language Infrastructure") - - + System.Reflection.AssemblyTitle("Microsoft.CSharp.dll") - + System.Resources.NeutralResourcesLanguage("en-US") - + System.Resources.SatelliteContractVersion("4.0.0.0") - + System.Runtime.CompilerServices.RuntimeCompatibility(WrapNonExceptionThrows=true) - + System.Runtime.InteropServices.ComVisible(false) - - System.Security.SecurityCritical - System.Diagnostics.Debuggable(System.Diagnostics.DebuggableAttribute+DebuggingModes.Default | System.Diagnostics.DebuggableAttribute+DebuggingModes.DisableOptimizations | System.Diagnostics.DebuggableAttribute+DebuggingModes.EnableEditAndContinue | System.Diagnostics.DebuggableAttribute+DebuggingModes.IgnoreSymbolStoreSequencePoints) @@ -157428,15 +157335,6 @@ System.Reflection.AssemblyInformationalVersion("4.7.3056.0") - - System.Reflection.AssemblyFileVersion("4.0.50524.0") - - - System.Reflection.AssemblyInformationalVersion("4.0.50524.0") - - - System.Resources.SatelliteContractVersion("2.0.5.0") - System.Reflection.AssemblyCopyright("© Microsoft Corporation. All rights reserved.") @@ -158560,79 +158458,43 @@ [00 00 00 00 00 00 00 00 04 00 00 00 00 00 00 00 ] - + System.CLSCompliant(true) - + System.Diagnostics.Debuggable(System.Diagnostics.DebuggableAttribute+DebuggingModes.IgnoreSymbolStoreSequencePoints) - - System.Reflection.AssemblyCompany("Mono development team") - - - System.Reflection.AssemblyCopyright("(c) Various Mono authors") - - + System.Reflection.AssemblyDefaultAlias("mscorlib.dll") - + System.Reflection.AssemblyDescription("mscorlib.dll") - - System.Reflection.AssemblyFileVersion("4.6.57.0") - - - System.Reflection.AssemblyInformationalVersion("4.6.57.0") - - - System.Reflection.AssemblyProduct("Mono Common Language Infrastructure") - - + System.Reflection.AssemblyTitle("mscorlib.dll") - + System.Resources.NeutralResourcesLanguage("en-US") - + System.Resources.SatelliteContractVersion("4.0.0.0") - - System.Runtime.CompilerServices.CompilationRelaxations(System.Runtime.CompilerServices.CompilationRelaxations.NoStringInterning) - - + System.Runtime.CompilerServices.DefaultDependency(System.Runtime.CompilerServices.LoadHint.Always) - - System.Runtime.CompilerServices.InternalsVisibleTo("XamMac, PublicKey=0024000004800000940000000602000000240000525341310004000011000000438ac2a5acfbf16cbd2b2b47a62762f273df9cb2795ceccdf77d10bf508e69e7a362ea7a45455bbf3ac955e1f2e2814f144e5d817efc4c6502cc012df310783348304e3ae38573c6d658c234025821fda87a0be8a0d504df564e2c93b2b878925f42503e9d54dfef9f9586d9e6f38a305769587b1de01f6c0410328b2c9733db") - - - System.Runtime.CompilerServices.InternalsVisibleTo("Xamarin.Mac, PublicKey=0024000004800000940000000602000000240000525341310004000011000000438ac2a5acfbf16cbd2b2b47a62762f273df9cb2795ceccdf77d10bf508e69e7a362ea7a45455bbf3ac955e1f2e2814f144e5d817efc4c6502cc012df310783348304e3ae38573c6d658c234025821fda87a0be8a0d504df564e2c93b2b878925f42503e9d54dfef9f9586d9e6f38a305769587b1de01f6c0410328b2c9733db") - - - System.Runtime.CompilerServices.InternalsVisibleTo("System.Numerics, PublicKey=00000000000000000400000000000000") - - - System.Runtime.CompilerServices.InternalsVisibleTo("System, PublicKey=00000000000000000400000000000000") - - - System.Runtime.CompilerServices.InternalsVisibleTo("System.Core, PublicKey=00000000000000000400000000000000") - - + System.Runtime.CompilerServices.RuntimeCompatibility(WrapNonExceptionThrows=true) - + System.Runtime.CompilerServices.StringFreezing - + System.Runtime.InteropServices.ComCompatibleVersion(1, 0, 3300, 0) - + System.Runtime.InteropServices.ComVisible(false) - - System.Runtime.InteropServices.Guid("BED7F4EA-1A96-11D2-8F08-00A0C9A6186D") - - + System.Security.AllowPartiallyTrustedCallers @@ -158782,27 +158644,6 @@ System.Reflection.AssemblyInformationalVersion("4.7.3056.0") - - System.Reflection.AssemblyFileVersion("4.0.50524.0") - - - System.Reflection.AssemblyInformationalVersion("4.0.50524.0") - - - System.Resources.SatelliteContractVersion("2.0.5.0") - - - System.Runtime.CompilerServices.InternalsVisibleTo("System.Core, PublicKey=00240000048000009400000006020000002400005253413100040000010001008D56C76F9E8649383049F383C44BE0EC204181822A6C31CF5EB7EF486944D032188EA1D3920763712CCB12D75FB77E9811149E6148E5D32FBAAB37611C1878DDC19E20EF135D0CB2CFF2BFEC3D115810C3D9069638FE4BE215DBF795861920E5AB6F7DB2E2CEEF136AC23D5DD2BF031700AEC232F6C6B1C785B4305C123B37AB") - - - System.Runtime.CompilerServices.InternalsVisibleTo("System, PublicKey=00240000048000009400000006020000002400005253413100040000010001008D56C76F9E8649383049F383C44BE0EC204181822A6C31CF5EB7EF486944D032188EA1D3920763712CCB12D75FB77E9811149E6148E5D32FBAAB37611C1878DDC19E20EF135D0CB2CFF2BFEC3D115810C3D9069638FE4BE215DBF795861920E5AB6F7DB2E2CEEF136AC23D5DD2BF031700AEC232F6C6B1C785B4305C123B37AB") - - - System.Runtime.CompilerServices.InternalsVisibleTo("monotouch, PublicKey=0024000004800000940000000602000000240000525341310004000011000000438ac2a5acfbf16cbd2b2b47a62762f273df9cb2795ceccdf77d10bf508e69e7a362ea7a45455bbf3ac955e1f2e2814f144e5d817efc4c6502cc012df310783348304e3ae38573c6d658c234025821fda87a0be8a0d504df564e2c93b2b878925f42503e9d54dfef9f9586d9e6f38a305769587b1de01f6c0410328b2c9733db") - - - System.Runtime.CompilerServices.InternalsVisibleTo("Xamarin.iOS, PublicKey=0024000004800000940000000602000000240000525341310004000011000000438ac2a5acfbf16cbd2b2b47a62762f273df9cb2795ceccdf77d10bf508e69e7a362ea7a45455bbf3ac955e1f2e2814f144e5d817efc4c6502cc012df310783348304e3ae38573c6d658c234025821fda87a0be8a0d504df564e2c93b2b878925f42503e9d54dfef9f9586d9e6f38a305769587b1de01f6c0410328b2c9733db") - System.Reflection.AssemblyFileVersion("4.6.27115.0") @@ -159980,54 +159821,36 @@ [00 00 00 00 00 00 00 00 04 00 00 00 00 00 00 00 ] - + System.CLSCompliant(true) - + System.Diagnostics.Debuggable(System.Diagnostics.DebuggableAttribute+DebuggingModes.IgnoreSymbolStoreSequencePoints) - - System.Reflection.AssemblyCompany("Mono development team") - - - System.Reflection.AssemblyCopyright("(c) Microsoft Corporation. All rights reserved.") - - + System.Reflection.AssemblyDefaultAlias("System.ComponentModel.Composition.dll") - + System.Reflection.AssemblyDescription("System.ComponentModel.Composition.dll") - - System.Reflection.AssemblyFileVersion("4.6.57.0") - - - System.Reflection.AssemblyInformationalVersion("4.6.57.0") - - - System.Reflection.AssemblyProduct("Mono Common Language Infrastructure") - - + System.Reflection.AssemblyTitle("System.ComponentModel.Composition.dll") - + System.Resources.NeutralResourcesLanguage("en-US") - + System.Resources.SatelliteContractVersion("4.0.0.0") - + System.Runtime.CompilerServices.RuntimeCompatibility(WrapNonExceptionThrows=true) - + System.Runtime.InteropServices.ComVisible(false) - + System.Security.AllowPartiallyTrustedCallers - - System.Security.SecurityCritical - System.Reflection.AssemblyCompany("Microsoft Corporation") @@ -160124,15 +159947,6 @@ System.Reflection.AssemblyInformationalVersion("4.7.3056.0") - - System.Reflection.AssemblyFileVersion("4.0.50524.0") - - - System.Reflection.AssemblyInformationalVersion("4.0.50524.0") - - - System.Resources.SatelliteContractVersion("2.0.5.0") - System.Reflection.AssemblyDefaultAlias("System.ComponentModel.Composition") @@ -161086,49 +160900,34 @@ [00 24 00 00 04 80 00 00 94 00 00 00 06 02 00 00 00 24 00 00 52 53 41 31 00 04 00 00 01 00 01 00 b5 fc 90 e7 02 7f 67 87 1e 77 3a 8f de 89 38 c8 1d d4 02 ba 65 b9 20 1d 60 59 3e 96 c4 92 65 1e 88 9c c1 3f 14 15 eb b5 3f ac 11 31 ae 0b d3 33 c5 ee 60 21 67 2d 97 18 ea 31 a8 ae bd 0d a0 07 2f 25 d8 7d ba 6f c9 0f fd 59 8e d4 da 35 e4 4c 39 8c 45 43 07 e8 e3 3b 84 26 14 3d ae c9 f5 96 83 6f 97 c8 f7 47 50 e5 97 5c 64 e2 18 9f 45 de f4 6b 2a 2b 12 47 ad c3 65 2b f5 c3 08 05 5d a9 ] - + System.CLSCompliant(true) - + System.Diagnostics.Debuggable(System.Diagnostics.DebuggableAttribute+DebuggingModes.IgnoreSymbolStoreSequencePoints) - - System.Reflection.AssemblyCompany("Mono development team") - - - System.Reflection.AssemblyCopyright("(c) Various Mono authors") - - + System.Reflection.AssemblyDefaultAlias("System.ComponentModel.DataAnnotations.dll") - + System.Reflection.AssemblyDescription("System.ComponentModel.DataAnnotations.dll") - - System.Reflection.AssemblyFileVersion("4.6.57.0") - - - System.Reflection.AssemblyInformationalVersion("4.6.57.0") - - - System.Reflection.AssemblyProduct("Mono Common Language Infrastructure") - - + System.Reflection.AssemblyTitle("System.ComponentModel.DataAnnotations.dll") - + System.Resources.NeutralResourcesLanguage("en-US") - + System.Resources.SatelliteContractVersion("4.0.0.0") - + System.Runtime.CompilerServices.RuntimeCompatibility(WrapNonExceptionThrows=true) - + System.Runtime.InteropServices.ComVisible(false) - + System.Security.AllowPartiallyTrustedCallers @@ -161242,15 +161041,6 @@ System.Reflection.AssemblyInformationalVersion("4.7.3056.0") - - System.Reflection.AssemblyFileVersion("4.0.50524.0") - - - System.Reflection.AssemblyInformationalVersion("4.0.50524.0") - - - System.Resources.SatelliteContractVersion("2.0.5.0") - System.Reflection.AssemblyFileVersion("4.6.27115.0") @@ -162308,55 +162098,37 @@ [00 24 00 00 04 80 00 00 94 00 00 00 06 02 00 00 00 24 00 00 52 53 41 31 00 04 00 00 01 00 01 00 07 d1 fa 57 c4 ae d9 f0 a3 2e 84 aa 0f ae fd 0d e9 e8 fd 6a ec 8f 87 fb 03 76 6c 83 4c 99 92 1e b2 3b e7 9a d9 d5 dc c1 dd 9a d2 36 13 21 02 90 0b 72 3c f9 80 95 7f c4 e1 77 10 8f c6 07 77 4f 29 e8 32 0e 92 ea 05 ec e4 e8 21 c0 a5 ef e8 f1 64 5c 4c 0c 93 c1 ab 99 28 5d 62 2c aa 65 2c 1d fa d6 3d 74 5d 6f 2d e5 f1 7e 5e af 0f c4 96 3d 26 1c 8a 12 43 65 18 20 6d c0 93 34 4d 5a d2 93 ] - + System.CLSCompliant(true) - + System.Diagnostics.Debuggable(System.Diagnostics.DebuggableAttribute+DebuggingModes.IgnoreSymbolStoreSequencePoints) - - System.Reflection.AssemblyCompany("Mono development team") - - - System.Reflection.AssemblyCopyright("(c) Various Mono authors") - - + System.Reflection.AssemblyDefaultAlias("System.Configuration.dll") - + System.Reflection.AssemblyDescription("System.Configuration.dll") - - System.Reflection.AssemblyFileVersion("4.6.57.0") - - - System.Reflection.AssemblyInformationalVersion("4.6.57.0") - - - System.Reflection.AssemblyProduct("Mono Common Language Infrastructure") - - + System.Reflection.AssemblyTitle("System.Configuration.dll") - + System.Resources.NeutralResourcesLanguage("en-US") - + System.Resources.SatelliteContractVersion("4.0.0.0") - - System.Runtime.CompilerServices.InternalsVisibleTo("System.Web, PublicKey=002400000480000094000000060200000024000052534131000400000100010007d1fa57c4aed9f0a32e84aa0faefd0de9e8fd6aec8f87fb03766c834c99921eb23be79ad9d5dcc1dd9ad236132102900b723cf980957fc4e177108fc607774f29e8320e92ea05ece4e821c0a5efe8f1645c4c0c93c1ab99285d622caa652c1dfad63d745d6f2de5f17e5eaf0fc4963d261c8a12436518206dc093344d5ad293") - - + System.Runtime.CompilerServices.RuntimeCompatibility(WrapNonExceptionThrows=true) - + System.Runtime.InteropServices.ComCompatibleVersion(1, 0, 3300, 0) - + System.Runtime.InteropServices.ComVisible(false) - + System.Security.AllowPartiallyTrustedCallers @@ -163447,49 +163219,34 @@ [00 24 00 00 04 80 00 00 94 00 00 00 06 02 00 00 00 24 00 00 52 53 41 31 00 04 00 00 01 00 01 00 07 d1 fa 57 c4 ae d9 f0 a3 2e 84 aa 0f ae fd 0d e9 e8 fd 6a ec 8f 87 fb 03 76 6c 83 4c 99 92 1e b2 3b e7 9a d9 d5 dc c1 dd 9a d2 36 13 21 02 90 0b 72 3c f9 80 95 7f c4 e1 77 10 8f c6 07 77 4f 29 e8 32 0e 92 ea 05 ec e4 e8 21 c0 a5 ef e8 f1 64 5c 4c 0c 93 c1 ab 99 28 5d 62 2c aa 65 2c 1d fa d6 3d 74 5d 6f 2d e5 f1 7e 5e af 0f c4 96 3d 26 1c 8a 12 43 65 18 20 6d c0 93 34 4d 5a d2 93 ] - + System.CLSCompliant(true) - + System.Diagnostics.Debuggable(System.Diagnostics.DebuggableAttribute+DebuggingModes.IgnoreSymbolStoreSequencePoints) - - System.Reflection.AssemblyCompany("Mono development team") - - - System.Reflection.AssemblyCopyright("(c) Various Mono authors") - - + System.Reflection.AssemblyDefaultAlias("System.Configuration.Install.dll") - + System.Reflection.AssemblyDescription("System.Configuration.Install.dll") - - System.Reflection.AssemblyFileVersion("4.6.57.0") - - - System.Reflection.AssemblyInformationalVersion("4.6.57.0") - - - System.Reflection.AssemblyProduct("Mono Common Language Infrastructure") - - + System.Reflection.AssemblyTitle("System.Configuration.Install.dll") - + System.Resources.NeutralResourcesLanguage("en-US") - + System.Resources.SatelliteContractVersion("4.0.0.0") - + System.Runtime.CompilerServices.RuntimeCompatibility(WrapNonExceptionThrows=true) - + System.Runtime.InteropServices.ComCompatibleVersion(1, 0, 3300, 0) - + System.Runtime.InteropServices.ComVisible(false) @@ -164439,58 +164196,43 @@ [00 00 00 00 00 00 00 00 04 00 00 00 00 00 00 00 ] - + System.CLSCompliant(true) - + System.Diagnostics.Debuggable(System.Diagnostics.DebuggableAttribute+DebuggingModes.IgnoreSymbolStoreSequencePoints) - - System.Reflection.AssemblyCompany("Mono development team") - - - System.Reflection.AssemblyCopyright("(c) Various Mono authors") - - + System.Reflection.AssemblyDefaultAlias("System.Core.dll") - + System.Reflection.AssemblyDescription("System.Core.dll") - - System.Reflection.AssemblyFileVersion("4.6.57.0") - - - System.Reflection.AssemblyInformationalVersion("4.6.57.0") - - - System.Reflection.AssemblyProduct("Mono Common Language Infrastructure") - - + System.Reflection.AssemblyTitle("System.Core.dll") - + System.Resources.NeutralResourcesLanguage("en-US") - + System.Resources.SatelliteContractVersion("4.0.0.0") - + System.Runtime.CompilerServices.DefaultDependency(System.Runtime.CompilerServices.LoadHint.Always) - + System.Runtime.CompilerServices.RuntimeCompatibility(WrapNonExceptionThrows=true) - + System.Runtime.CompilerServices.StringFreezing - + System.Runtime.InteropServices.ComVisible(false) - + System.Security.AllowPartiallyTrustedCallers - + System.Security.SecurityCritical @@ -164601,15 +164343,6 @@ System.Reflection.AssemblyInformationalVersion("4.7.3056.0") - - System.Reflection.AssemblyFileVersion("4.0.50524.0") - - - System.Reflection.AssemblyInformationalVersion("4.0.50524.0") - - - System.Resources.SatelliteContractVersion("2.0.5.0") - System.Reflection.AssemblyFileVersion("4.6.27115.0") @@ -165667,58 +165400,37 @@ [00 00 00 00 00 00 00 00 04 00 00 00 00 00 00 00 ] - + System.CLSCompliant(true) - + System.Diagnostics.Debuggable(System.Diagnostics.DebuggableAttribute+DebuggingModes.IgnoreSymbolStoreSequencePoints) - - System.Reflection.AssemblyCompany("Mono development team") - - - System.Reflection.AssemblyCopyright("(c) Various Mono authors") - - + System.Reflection.AssemblyDefaultAlias("System.Data.dll") - + System.Reflection.AssemblyDescription("System.Data.dll") - - System.Reflection.AssemblyFileVersion("4.6.57.0") - - - System.Reflection.AssemblyInformationalVersion("4.6.57.0") - - - System.Reflection.AssemblyProduct("Mono Common Language Infrastructure") - - + System.Reflection.AssemblyTitle("System.Data.dll") - + System.Resources.NeutralResourcesLanguage("en-US") - + System.Resources.SatelliteContractVersion("4.0.0.0") - + System.Runtime.CompilerServices.InternalsVisibleTo("System.Data.DataSetExtensions, PublicKey=00000000000000000400000000000000") - - System.Runtime.CompilerServices.InternalsVisibleTo("System.Design, PublicKey=002400000480000094000000060200000024000052534131000400000100010007d1fa57c4aed9f0a32e84aa0faefd0de9e8fd6aec8f87fb03766c834c99921eb23be79ad9d5dcc1dd9ad236132102900b723cf980957fc4e177108fc607774f29e8320e92ea05ece4e821c0a5efe8f1645c4c0c93c1ab99285d622caa652c1dfad63d745d6f2de5f17e5eaf0fc4963d261c8a12436518206dc093344d5ad293") - - - System.Runtime.CompilerServices.InternalsVisibleTo("System.Web, PublicKey=002400000480000094000000060200000024000052534131000400000100010007d1fa57c4aed9f0a32e84aa0faefd0de9e8fd6aec8f87fb03766c834c99921eb23be79ad9d5dcc1dd9ad236132102900b723cf980957fc4e177108fc607774f29e8320e92ea05ece4e821c0a5efe8f1645c4c0c93c1ab99285d622caa652c1dfad63d745d6f2de5f17e5eaf0fc4963d261c8a12436518206dc093344d5ad293") - - + System.Runtime.CompilerServices.RuntimeCompatibility(WrapNonExceptionThrows=true) - + System.Runtime.InteropServices.ComVisible(false) - + System.Security.AllowPartiallyTrustedCallers @@ -165850,18 +165562,6 @@ System.Reflection.AssemblyInformationalVersion("4.7.3056.0") - - System.Reflection.AssemblyFileVersion("4.0.50524.0") - - - System.Reflection.AssemblyInformationalVersion("4.0.50524.0") - - - System.Resources.SatelliteContractVersion("2.0.5.0") - - - System.Runtime.CompilerServices.InternalsVisibleTo("System.Data.DataSetExtensions, PublicKey=0024000004800000940000000602000000240000525341310004000001000100B5FC90E7027F67871E773A8FDE8938C81DD402BA65B9201D60593E96C492651E889CC13F1415EBB53FAC1131AE0BD333C5EE6021672D9718EA31A8AEBD0DA0072F25D87DBA6FC90FFD598ED4DA35E44C398C454307E8E33B8426143DAEC9F596836F97C8F74750E5975C64E2189F45DEF46B2A2B1247ADC3652BF5C308055DA9") - System.Reflection.AssemblyFileVersion("4.6.27115.0") @@ -167017,58 +166717,34 @@ [00 00 00 00 00 00 00 00 04 00 00 00 00 00 00 00 ] - + System.CLSCompliant(true) - + System.Diagnostics.Debuggable(System.Diagnostics.DebuggableAttribute+DebuggingModes.IgnoreSymbolStoreSequencePoints) - - System.Reflection.AssemblyCompany("Mono development team") - - - System.Reflection.AssemblyCopyright("(c) Various Mono authors") - - + System.Reflection.AssemblyDefaultAlias("System.Data.Linq.dll") - + System.Reflection.AssemblyDescription("System.Data.Linq.dll") - - System.Reflection.AssemblyFileVersion("4.6.57.0") - - - System.Reflection.AssemblyInformationalVersion("4.6.57.0") - - - System.Reflection.AssemblyProduct("Mono Common Language Infrastructure") - - + System.Reflection.AssemblyTitle("System.Data.Linq.dll") - + System.Resources.NeutralResourcesLanguage("en-US") - + System.Resources.SatelliteContractVersion("4.0.0.0") - - System.Runtime.CompilerServices.InternalsVisibleTo("sqlmetal, PublicKey=0024000004800000940000000602000000240000525341310004000001000100c5753d8c47f40083f549016a5711238ac8ec297605abccd3dc4b6d0f280b4764eb2cc58ec4e37831edad7e7a07b8fe4a9cbb059374c0cc047aa28839fed7176761813caf6a2ffa0bff9afb50ead56dd3f56186a663962a12b830c2a70eb70ec77823eb5750e5bdef9e01d097c30b5c5463c3d07d3472b58e4c02f2792309259f") - - - System.Runtime.CompilerServices.InternalsVisibleTo("sqlmetal_test_net_2_0, PublicKey=0024000004800000940000000602000000240000525341310004000001000100c5753d8c47f40083f549016a5711238ac8ec297605abccd3dc4b6d0f280b4764eb2cc58ec4e37831edad7e7a07b8fe4a9cbb059374c0cc047aa28839fed7176761813caf6a2ffa0bff9afb50ead56dd3f56186a663962a12b830c2a70eb70ec77823eb5750e5bdef9e01d097c30b5c5463c3d07d3472b58e4c02f2792309259f") - - - System.Runtime.CompilerServices.InternalsVisibleTo("sqlmetal_test_net_4_0, PublicKey=0024000004800000940000000602000000240000525341310004000001000100c5753d8c47f40083f549016a5711238ac8ec297605abccd3dc4b6d0f280b4764eb2cc58ec4e37831edad7e7a07b8fe4a9cbb059374c0cc047aa28839fed7176761813caf6a2ffa0bff9afb50ead56dd3f56186a663962a12b830c2a70eb70ec77823eb5750e5bdef9e01d097c30b5c5463c3d07d3472b58e4c02f2792309259f") - - + System.Runtime.CompilerServices.RuntimeCompatibility(WrapNonExceptionThrows=true) - + System.Runtime.InteropServices.ComVisible(false) - + System.Security.AllowPartiallyTrustedCallers @@ -167892,58 +167568,40 @@ [00 00 00 00 00 00 00 00 04 00 00 00 00 00 00 00 ] - + System.CLSCompliant(true) - + System.Diagnostics.Debuggable(System.Diagnostics.DebuggableAttribute+DebuggingModes.IgnoreSymbolStoreSequencePoints) - - System.Reflection.AssemblyCompany("Mono development team") - - - System.Reflection.AssemblyCopyright("(c) Various Mono authors") - - + System.Reflection.AssemblyDefaultAlias("System.Data.Services.Client.dll") - + System.Reflection.AssemblyDescription("System.Data.Services.Client.dll") - - System.Reflection.AssemblyFileVersion("4.6.57.0") - - - System.Reflection.AssemblyInformationalVersion("4.6.57.0") - - - System.Reflection.AssemblyProduct("Mono Common Language Infrastructure") - - + System.Reflection.AssemblyTitle("System.Data.Services.Client.dll") - + System.Resources.NeutralResourcesLanguage("en-US") - + System.Resources.SatelliteContractVersion("4.0.0.0") - - System.Runtime.CompilerServices.CompilationRelaxations(System.Runtime.CompilerServices.CompilationRelaxations.NoStringInterning) - - + System.Runtime.CompilerServices.RuntimeCompatibility(WrapNonExceptionThrows=true) - + System.Runtime.InteropServices.ComVisible(false) - + System.Security.AllowPartiallyTrustedCallers - + System.Security.SecurityCritical - + System.Security.SecurityRules(System.Security.SecurityRuleSet.Level1, SkipVerificationInFullTrust=true) @@ -168036,15 +167694,6 @@ System.Reflection.AssemblyInformationalVersion("4.7.3056.0") - - System.Reflection.AssemblyFileVersion("4.0.50524.0") - - - System.Reflection.AssemblyInformationalVersion("4.0.50524.0") - - - System.Resources.SatelliteContractVersion("2.0.5.0") - System.Reflection.AssemblyFileVersion("4.8.3761.0") @@ -168888,85 +168537,43 @@ [00 00 00 00 00 00 00 00 04 00 00 00 00 00 00 00 ] - + System.CLSCompliant(true) - + System.Diagnostics.Debuggable(System.Diagnostics.DebuggableAttribute+DebuggingModes.IgnoreSymbolStoreSequencePoints) - - System.Reflection.AssemblyCompany("Mono development team") - - - System.Reflection.AssemblyCopyright("(c) Various Mono authors") - - + System.Reflection.AssemblyDefaultAlias("System.dll") - + System.Reflection.AssemblyDescription("System.dll") - - System.Reflection.AssemblyFileVersion("4.6.57.0") - - - System.Reflection.AssemblyInformationalVersion("4.6.57.0") - - - System.Reflection.AssemblyProduct("Mono Common Language Infrastructure") - - + System.Reflection.AssemblyTitle("System.dll") - + System.Resources.NeutralResourcesLanguage("en-US") - + System.Resources.SatelliteContractVersion("4.0.0.0") - + System.Runtime.CompilerServices.DefaultDependency(System.Runtime.CompilerServices.LoadHint.Always) - - System.Runtime.CompilerServices.InternalsVisibleTo("System.ComponentModel.DataAnnotations, PublicKey=0024000004800000940000000602000000240000525341310004000001000100b5fc90e7027f67871e773a8fde8938c81dd402ba65b9201d60593e96c492651e889cc13f1415ebb53fac1131ae0bd333c5ee6021672d9718ea31a8aebd0da0072f25d87dba6fc90ffd598ed4da35e44c398c454307e8e33b8426143daec9f596836f97c8f74750e5975c64e2189f45def46b2a2b1247adc3652bf5c308055da9") - - - System.Runtime.CompilerServices.InternalsVisibleTo("System.Net.Http, PublicKey=002400000480000094000000060200000024000052534131000400000100010007d1fa57c4aed9f0a32e84aa0faefd0de9e8fd6aec8f87fb03766c834c99921eb23be79ad9d5dcc1dd9ad236132102900b723cf980957fc4e177108fc607774f29e8320e92ea05ece4e821c0a5efe8f1645c4c0c93c1ab99285d622caa652c1dfad63d745d6f2de5f17e5eaf0fc4963d261c8a12436518206dc093344d5ad293") - - - System.Runtime.CompilerServices.InternalsVisibleTo("Mono.Btls.Interface, PublicKey=002400000480000094000000060200000024000052534131000400000100010079159977d2d03a8e6bea7a2e74e8d1afcc93e8851974952bb480a12c9134474d04062447c37e0e68c080536fcf3c3fbe2ff9c979ce998475e506e8ce82dd5b0f350dc10e93bf2eeecf874b24770c5081dbea7447fddafa277b22de47d6ffea449674a4f9fccf84d15069089380284dbdd35f46cdff12a1bd78e4ef0065d016df") - - - System.Runtime.CompilerServices.InternalsVisibleTo("Mono.Security, PublicKey=002400000480000094000000060200000024000052534131000400000100010079159977d2d03a8e6bea7a2e74e8d1afcc93e8851974952bb480a12c9134474d04062447c37e0e68c080536fcf3c3fbe2ff9c979ce998475e506e8ce82dd5b0f350dc10e93bf2eeecf874b24770c5081dbea7447fddafa277b22de47d6ffea449674a4f9fccf84d15069089380284dbdd35f46cdff12a1bd78e4ef0065d016df") - - - System.Runtime.CompilerServices.InternalsVisibleTo("monotouch, PublicKey=0024000004800000940000000602000000240000525341310004000011000000438ac2a5acfbf16cbd2b2b47a62762f273df9cb2795ceccdf77d10bf508e69e7a362ea7a45455bbf3ac955e1f2e2814f144e5d817efc4c6502cc012df310783348304e3ae38573c6d658c234025821fda87a0be8a0d504df564e2c93b2b878925f42503e9d54dfef9f9586d9e6f38a305769587b1de01f6c0410328b2c9733db") - - - System.Runtime.CompilerServices.InternalsVisibleTo("Xamarin.iOS, PublicKey=0024000004800000940000000602000000240000525341310004000011000000438ac2a5acfbf16cbd2b2b47a62762f273df9cb2795ceccdf77d10bf508e69e7a362ea7a45455bbf3ac955e1f2e2814f144e5d817efc4c6502cc012df310783348304e3ae38573c6d658c234025821fda87a0be8a0d504df564e2c93b2b878925f42503e9d54dfef9f9586d9e6f38a305769587b1de01f6c0410328b2c9733db") - - - System.Runtime.CompilerServices.InternalsVisibleTo("Xamarin.Mac, PublicKey=0024000004800000940000000602000000240000525341310004000011000000438ac2a5acfbf16cbd2b2b47a62762f273df9cb2795ceccdf77d10bf508e69e7a362ea7a45455bbf3ac955e1f2e2814f144e5d817efc4c6502cc012df310783348304e3ae38573c6d658c234025821fda87a0be8a0d504df564e2c93b2b878925f42503e9d54dfef9f9586d9e6f38a305769587b1de01f6c0410328b2c9733db") - - - System.Runtime.CompilerServices.InternalsVisibleTo("Xamarin.WatchOS, PublicKey=0024000004800000940000000602000000240000525341310004000011000000438ac2a5acfbf16cbd2b2b47a62762f273df9cb2795ceccdf77d10bf508e69e7a362ea7a45455bbf3ac955e1f2e2814f144e5d817efc4c6502cc012df310783348304e3ae38573c6d658c234025821fda87a0be8a0d504df564e2c93b2b878925f42503e9d54dfef9f9586d9e6f38a305769587b1de01f6c0410328b2c9733db") - - - System.Runtime.CompilerServices.InternalsVisibleTo("Xamarin.TVOS, PublicKey=0024000004800000940000000602000000240000525341310004000011000000438ac2a5acfbf16cbd2b2b47a62762f273df9cb2795ceccdf77d10bf508e69e7a362ea7a45455bbf3ac955e1f2e2814f144e5d817efc4c6502cc012df310783348304e3ae38573c6d658c234025821fda87a0be8a0d504df564e2c93b2b878925f42503e9d54dfef9f9586d9e6f38a305769587b1de01f6c0410328b2c9733db") - - + System.Runtime.CompilerServices.RuntimeCompatibility(WrapNonExceptionThrows=true) - + System.Runtime.CompilerServices.StringFreezing - + System.Runtime.InteropServices.ComCompatibleVersion(1, 0, 3300, 0) - + System.Runtime.InteropServices.ComVisible(false) - + System.Security.AllowPartiallyTrustedCallers @@ -169104,15 +168711,6 @@ System.Reflection.AssemblyInformationalVersion("4.7.3056.0") - - System.Reflection.AssemblyFileVersion("4.0.50524.0") - - - System.Reflection.AssemblyInformationalVersion("4.0.50524.0") - - - System.Resources.SatelliteContractVersion("2.0.5.0") - System.Reflection.AssemblyFileVersion("4.6.27115.0") @@ -170290,58 +169888,43 @@ [00 00 00 00 00 00 00 00 04 00 00 00 00 00 00 00 ] - + System.CLSCompliant(true) - + System.Diagnostics.Debuggable(System.Diagnostics.DebuggableAttribute+DebuggingModes.IgnoreSymbolStoreSequencePoints) - - System.Reflection.AssemblyCompany("Mono development team") - - - System.Reflection.AssemblyCopyright("(c) Various Mono authors") - - + System.Reflection.AssemblyDefaultAlias("System.IdentityModel.dll") - + System.Reflection.AssemblyDescription("System.IdentityModel.dll") - - System.Reflection.AssemblyFileVersion("4.6.57.0") - - - System.Reflection.AssemblyInformationalVersion("4.6.57.0") - - - System.Reflection.AssemblyProduct("Mono Common Language Infrastructure") - - + System.Reflection.AssemblyTitle("System.IdentityModel.dll") - + System.Resources.NeutralResourcesLanguage("en-US") - + System.Resources.SatelliteContractVersion("4.0.0.0") - + System.Runtime.CompilerServices.InternalsVisibleTo("System.ServiceModel, PublicKey=00000000000000000400000000000000") - + System.Runtime.CompilerServices.RuntimeCompatibility(WrapNonExceptionThrows=true) - + System.Runtime.InteropServices.ComCompatibleVersion(1, 0, 3300, 0) - + System.Runtime.InteropServices.ComVisible(false) - + System.Security.AllowPartiallyTrustedCallers - + System.Security.SecurityCritical(System.Security.SecurityCriticalScope.Explicit) @@ -170452,15 +170035,6 @@ System.Reflection.AssemblyInformationalVersion("4.7.3056.0") - - System.Reflection.AssemblyFileVersion("4.0.50524.0") - - - System.Reflection.AssemblyInformationalVersion("4.0.50524.0") - - - System.Resources.SatelliteContractVersion("2.0.5.0") - System.Reflection.AssemblyFileVersion("4.8.3761.0") @@ -171344,46 +170918,31 @@ [00 00 00 00 00 00 00 00 04 00 00 00 00 00 00 00 ] - + System.CLSCompliant(true) - + System.Diagnostics.Debuggable(System.Diagnostics.DebuggableAttribute+DebuggingModes.IgnoreSymbolStoreSequencePoints) - - System.Reflection.AssemblyCompany("Mono development team") - - - System.Reflection.AssemblyCopyright("(c) Various Mono authors") - - + System.Reflection.AssemblyDefaultAlias("System.IdentityModel.Selectors.dll") - + System.Reflection.AssemblyDescription("System.IdentityModel.Selectors.dll") - - System.Reflection.AssemblyFileVersion("4.6.57.0") - - - System.Reflection.AssemblyInformationalVersion("4.6.57.0") - - - System.Reflection.AssemblyProduct("Mono Common Language Infrastructure") - - + System.Reflection.AssemblyTitle("System.IdentityModel.Selectors.dll") - + System.Resources.NeutralResourcesLanguage("en-US") - + System.Resources.SatelliteContractVersion("4.0.0.0") - + System.Runtime.CompilerServices.RuntimeCompatibility(WrapNonExceptionThrows=true) - + System.Runtime.InteropServices.ComVisible(false) @@ -172238,34 +171797,19 @@ [00 00 00 00 00 00 00 00 04 00 00 00 00 00 00 00 ] - + System.Diagnostics.Debuggable(System.Diagnostics.DebuggableAttribute+DebuggingModes.IgnoreSymbolStoreSequencePoints) - - System.Reflection.AssemblyCompany("Mono development team") - - - System.Reflection.AssemblyCopyright("(c) Various Mono authors") - - + System.Reflection.AssemblyDefaultAlias("System.IO.Compression.dll") - + System.Reflection.AssemblyDescription("System.IO.Compression.dll") - - System.Reflection.AssemblyFileVersion("4.6.57.0") - - - System.Reflection.AssemblyInformationalVersion("4.6.57.0") - - - System.Reflection.AssemblyProduct("Mono Common Language Infrastructure") - - + System.Reflection.AssemblyTitle("System.IO.Compression.dll") - + System.Runtime.CompilerServices.RuntimeCompatibility(WrapNonExceptionThrows=true) @@ -172412,12 +171956,6 @@ System.Reflection.AssemblyInformationalVersion("4.0.30319.17929") - - System.Reflection.AssemblyFileVersion("4.0.50524.0") - - - System.Reflection.AssemblyInformationalVersion("4.0.50524.0") - System.Reflection.AssemblyCopyright("© Microsoft Corporation. All rights reserved.") @@ -173805,34 +173343,19 @@ [00 00 00 00 00 00 00 00 04 00 00 00 00 00 00 00 ] - + System.Diagnostics.Debuggable(System.Diagnostics.DebuggableAttribute+DebuggingModes.IgnoreSymbolStoreSequencePoints) - - System.Reflection.AssemblyCompany("Mono development team") - - - System.Reflection.AssemblyCopyright("(c) Various Mono authors") - - + System.Reflection.AssemblyDefaultAlias("System.IO.Compression.FileSystem.dll") - + System.Reflection.AssemblyDescription("System.IO.Compression.FileSystem.dll") - - System.Reflection.AssemblyFileVersion("4.6.57.0") - - - System.Reflection.AssemblyInformationalVersion("4.6.57.0") - - - System.Reflection.AssemblyProduct("Mono Common Language Infrastructure") - - + System.Reflection.AssemblyTitle("System.IO.Compression.FileSystem.dll") - + System.Runtime.CompilerServices.RuntimeCompatibility(WrapNonExceptionThrows=true) @@ -173937,12 +173460,6 @@ System.Reflection.AssemblyInformationalVersion("4.7.3056.0") - - System.Reflection.AssemblyFileVersion("4.0.50524.0") - - - System.Reflection.AssemblyInformationalVersion("4.0.50524.0") - System.Reflection.AssemblyFileVersion("4.6.27115.0") @@ -174895,48 +174412,15 @@ [00 24 00 00 04 80 00 00 94 00 00 00 06 02 00 00 00 24 00 00 52 53 41 31 00 04 00 00 01 00 01 00 b5 fc 90 e7 02 7f 67 87 1e 77 3a 8f de 89 38 c8 1d d4 02 ba 65 b9 20 1d 60 59 3e 96 c4 92 65 1e 88 9c c1 3f 14 15 eb b5 3f ac 11 31 ae 0b d3 33 c5 ee 60 21 67 2d 97 18 ea 31 a8 ae bd 0d a0 07 2f 25 d8 7d ba 6f c9 0f fd 59 8e d4 da 35 e4 4c 39 8c 45 43 07 e8 e3 3b 84 26 14 3d ae c9 f5 96 83 6f 97 c8 f7 47 50 e5 97 5c 64 e2 18 9f 45 de f4 6b 2a 2b 12 47 ad c3 65 2b f5 c3 08 05 5d a9 ] - + System.Diagnostics.Debuggable(System.Diagnostics.DebuggableAttribute+DebuggingModes.IgnoreSymbolStoreSequencePoints) - - System.Reflection.AssemblyCompany("Mono development team") - - - System.Reflection.AssemblyCopyright("(c) Various Mono authors") - - - System.Reflection.AssemblyDefaultAlias("System.Json.dll") - - - System.Reflection.AssemblyDescription("System.Json.dll") - - - System.Reflection.AssemblyFileVersion("4.6.57.0") - - - System.Reflection.AssemblyInformationalVersion("4.6.57.0") - - - System.Reflection.AssemblyProduct("Mono Common Language Infrastructure") - - - System.Reflection.AssemblyTitle("System.Json.dll") - - + System.Resources.NeutralResourcesLanguage("en-US") - - System.Resources.SatelliteContractVersion("4.0.0.0") - - + System.Runtime.CompilerServices.RuntimeCompatibility(WrapNonExceptionThrows=true) - - System.Runtime.InteropServices.ComVisible(false) - - - System.Security.SecurityCritical - System.CLSCompliant(true) @@ -174976,15 +174460,6 @@ System.Runtime.CompilerServices.CompilationRelaxations(8) - - System.Reflection.AssemblyFileVersion("4.0.50524.0") - - - System.Reflection.AssemblyInformationalVersion("4.0.50524.0") - - - System.Resources.SatelliteContractVersion("2.0.5.0") - System.Reflection.AssemblyFileVersion("4.6.26515.06") @@ -175307,49 +174782,31 @@ [00 24 00 00 04 80 00 00 94 00 00 00 06 02 00 00 00 24 00 00 52 53 41 31 00 04 00 00 01 00 01 00 07 d1 fa 57 c4 ae d9 f0 a3 2e 84 aa 0f ae fd 0d e9 e8 fd 6a ec 8f 87 fb 03 76 6c 83 4c 99 92 1e b2 3b e7 9a d9 d5 dc c1 dd 9a d2 36 13 21 02 90 0b 72 3c f9 80 95 7f c4 e1 77 10 8f c6 07 77 4f 29 e8 32 0e 92 ea 05 ec e4 e8 21 c0 a5 ef e8 f1 64 5c 4c 0c 93 c1 ab 99 28 5d 62 2c aa 65 2c 1d fa d6 3d 74 5d 6f 2d e5 f1 7e 5e af 0f c4 96 3d 26 1c 8a 12 43 65 18 20 6d c0 93 34 4d 5a d2 93 ] - + System.CLSCompliant(true) - + System.Diagnostics.Debuggable(System.Diagnostics.DebuggableAttribute+DebuggingModes.IgnoreSymbolStoreSequencePoints) - - System.Reflection.AssemblyCompany("Mono development team") - - - System.Reflection.AssemblyCopyright("(c) Various Mono authors") - - + System.Reflection.AssemblyDefaultAlias("System.Messaging.dll") - + System.Reflection.AssemblyDescription("System.Messaging.dll") - - System.Reflection.AssemblyFileVersion("4.6.57.0") - - - System.Reflection.AssemblyInformationalVersion("4.6.57.0") - - - System.Reflection.AssemblyProduct("Mono Common Language Infrastructure") - - + System.Reflection.AssemblyTitle("System.Messaging.dll") - + System.Resources.NeutralResourcesLanguage("en-US") - + System.Resources.SatelliteContractVersion("4.0.0.0") - - System.Runtime.CompilerServices.CompilationRelaxations(System.Runtime.CompilerServices.CompilationRelaxations.NoStringInterning) - - + System.Runtime.CompilerServices.RuntimeCompatibility(WrapNonExceptionThrows=true) - + System.Runtime.InteropServices.ComVisible(false) @@ -176296,52 +175753,37 @@ [00 24 00 00 04 80 00 00 94 00 00 00 06 02 00 00 00 24 00 00 52 53 41 31 00 04 00 00 01 00 01 00 07 d1 fa 57 c4 ae d9 f0 a3 2e 84 aa 0f ae fd 0d e9 e8 fd 6a ec 8f 87 fb 03 76 6c 83 4c 99 92 1e b2 3b e7 9a d9 d5 dc c1 dd 9a d2 36 13 21 02 90 0b 72 3c f9 80 95 7f c4 e1 77 10 8f c6 07 77 4f 29 e8 32 0e 92 ea 05 ec e4 e8 21 c0 a5 ef e8 f1 64 5c 4c 0c 93 c1 ab 99 28 5d 62 2c aa 65 2c 1d fa d6 3d 74 5d 6f 2d e5 f1 7e 5e af 0f c4 96 3d 26 1c 8a 12 43 65 18 20 6d c0 93 34 4d 5a d2 93 ] - + System.CLSCompliant(true) - + System.Diagnostics.Debuggable(System.Diagnostics.DebuggableAttribute+DebuggingModes.IgnoreSymbolStoreSequencePoints) - - System.Reflection.AssemblyCompany("Mono development team") - - - System.Reflection.AssemblyCopyright("(c) Various Mono authors") - - + System.Reflection.AssemblyDefaultAlias("System.Net.dll") - + System.Reflection.AssemblyDescription("System.Net.dll") - - System.Reflection.AssemblyFileVersion("4.6.57.0") - - - System.Reflection.AssemblyInformationalVersion("4.6.57.0") - - - System.Reflection.AssemblyProduct("Mono Common Language Infrastructure") - - + System.Reflection.AssemblyTitle("System.Net.dll") - + System.Resources.NeutralResourcesLanguage("en-US") - + System.Resources.SatelliteContractVersion("4.0.0.0") - + System.Runtime.CompilerServices.RuntimeCompatibility(WrapNonExceptionThrows=true) - + System.Runtime.InteropServices.ComVisible(false) - + System.Security.AllowPartiallyTrustedCallers - + System.Security.SecurityCritical @@ -176452,24 +175894,6 @@ System.Reflection.AssemblyInformationalVersion("4.7.3056.0") - - System.Reflection.AssemblyFileVersion("4.0.50524.0") - - - System.Reflection.AssemblyInformationalVersion("4.0.50524.0") - - - System.Resources.SatelliteContractVersion("2.0.5.0") - - - System.Runtime.CompilerServices.InternalsVisibleTo("System.Windows, PublicKey=00240000048000009400000006020000002400005253413100040000010001008D56C76F9E8649383049F383C44BE0EC204181822A6C31CF5EB7EF486944D032188EA1D3920763712CCB12D75FB77E9811149E6148E5D32FBAAB37611C1878DDC19E20EF135D0CB2CFF2BFEC3D115810C3D9069638FE4BE215DBF795861920E5AB6F7DB2E2CEEF136AC23D5DD2BF031700AEC232F6C6B1C785B4305C123B37AB") - - - System.Runtime.CompilerServices.InternalsVisibleTo("System.Windows.Browser, PublicKey=00240000048000009400000006020000002400005253413100040000010001008D56C76F9E8649383049F383C44BE0EC204181822A6C31CF5EB7EF486944D032188EA1D3920763712CCB12D75FB77E9811149E6148E5D32FBAAB37611C1878DDC19E20EF135D0CB2CFF2BFEC3D115810C3D9069638FE4BE215DBF795861920E5AB6F7DB2E2CEEF136AC23D5DD2BF031700AEC232F6C6B1C785B4305C123B37AB") - - - System.Runtime.CompilerServices.InternalsVisibleTo("System.Xml, PublicKey=00240000048000009400000006020000002400005253413100040000010001008D56C76F9E8649383049F383C44BE0EC204181822A6C31CF5EB7EF486944D032188EA1D3920763712CCB12D75FB77E9811149E6148E5D32FBAAB37611C1878DDC19E20EF135D0CB2CFF2BFEC3D115810C3D9069638FE4BE215DBF795861920E5AB6F7DB2E2CEEF136AC23D5DD2BF031700AEC232F6C6B1C785B4305C123B37AB") - System.Reflection.AssemblyFileVersion("4.6.27115.0") @@ -177533,52 +176957,31 @@ [00 24 00 00 04 80 00 00 94 00 00 00 06 02 00 00 00 24 00 00 52 53 41 31 00 04 00 00 01 00 01 00 07 d1 fa 57 c4 ae d9 f0 a3 2e 84 aa 0f ae fd 0d e9 e8 fd 6a ec 8f 87 fb 03 76 6c 83 4c 99 92 1e b2 3b e7 9a d9 d5 dc c1 dd 9a d2 36 13 21 02 90 0b 72 3c f9 80 95 7f c4 e1 77 10 8f c6 07 77 4f 29 e8 32 0e 92 ea 05 ec e4 e8 21 c0 a5 ef e8 f1 64 5c 4c 0c 93 c1 ab 99 28 5d 62 2c aa 65 2c 1d fa d6 3d 74 5d 6f 2d e5 f1 7e 5e af 0f c4 96 3d 26 1c 8a 12 43 65 18 20 6d c0 93 34 4d 5a d2 93 ] - + System.CLSCompliant(true) - + System.Diagnostics.Debuggable(System.Diagnostics.DebuggableAttribute+DebuggingModes.IgnoreSymbolStoreSequencePoints) - - System.Reflection.AssemblyCompany("Mono development team") - - - System.Reflection.AssemblyCopyright("(c) Various Mono authors") - - + System.Reflection.AssemblyDefaultAlias("System.Net.Http.dll") - + System.Reflection.AssemblyDescription("System.Net.Http.dll") - - System.Reflection.AssemblyFileVersion("4.6.57.0") - - - System.Reflection.AssemblyInformationalVersion("4.6.57.0") - - - System.Reflection.AssemblyProduct("Mono Common Language Infrastructure") - - + System.Reflection.AssemblyTitle("System.Net.Http.dll") - + System.Resources.NeutralResourcesLanguage("en-US") - + System.Resources.SatelliteContractVersion("4.0.0.0") - - System.Runtime.CompilerServices.InternalsVisibleTo("System.Net.Http.WebRequest, PublicKey=002400000480000094000000060200000024000052534131000400000100010007d1fa57c4aed9f0a32e84aa0faefd0de9e8fd6aec8f87fb03766c834c99921eb23be79ad9d5dcc1dd9ad236132102900b723cf980957fc4e177108fc607774f29e8320e92ea05ece4e821c0a5efe8f1645c4c0c93c1ab99285d622caa652c1dfad63d745d6f2de5f17e5eaf0fc4963d261c8a12436518206dc093344d5ad293") - - - System.Runtime.CompilerServices.InternalsVisibleTo("Xamarin.Mac, PublicKey=0024000004800000940000000602000000240000525341310004000011000000438ac2a5acfbf16cbd2b2b47a62762f273df9cb2795ceccdf77d10bf508e69e7a362ea7a45455bbf3ac955e1f2e2814f144e5d817efc4c6502cc012df310783348304e3ae38573c6d658c234025821fda87a0be8a0d504df564e2c93b2b878925f42503e9d54dfef9f9586d9e6f38a305769587b1de01f6c0410328b2c9733db") - - + System.Runtime.CompilerServices.RuntimeCompatibility(WrapNonExceptionThrows=true) - + System.Runtime.InteropServices.ComVisible(false) @@ -177719,12 +177122,6 @@ System.Reflection.AssemblyInformationalVersion("4.6.24705.01. Commit Hash: 4d1af962ca0fede10beb01d197367c2f90e92c97") - - System.Reflection.AssemblyFileVersion("4.0.50524.0") - - - System.Reflection.AssemblyInformationalVersion("4.0.50524.0") - System.Reflection.AssemblyCopyright("© Microsoft Corporation. All rights reserved.") @@ -179112,51 +178509,15 @@ [00 24 00 00 04 80 00 00 94 00 00 00 06 02 00 00 00 24 00 00 52 53 41 31 00 04 00 00 01 00 01 00 07 d1 fa 57 c4 ae d9 f0 a3 2e 84 aa 0f ae fd 0d e9 e8 fd 6a ec 8f 87 fb 03 76 6c 83 4c 99 92 1e b2 3b e7 9a d9 d5 dc c1 dd 9a d2 36 13 21 02 90 0b 72 3c f9 80 95 7f c4 e1 77 10 8f c6 07 77 4f 29 e8 32 0e 92 ea 05 ec e4 e8 21 c0 a5 ef e8 f1 64 5c 4c 0c 93 c1 ab 99 28 5d 62 2c aa 65 2c 1d fa d6 3d 74 5d 6f 2d e5 f1 7e 5e af 0f c4 96 3d 26 1c 8a 12 43 65 18 20 6d c0 93 34 4d 5a d2 93 ] - + System.CLSCompliant(true) - + System.Diagnostics.Debuggable(System.Diagnostics.DebuggableAttribute+DebuggingModes.IgnoreSymbolStoreSequencePoints) - - System.Reflection.AssemblyCompany("Mono development team") - - - System.Reflection.AssemblyCopyright("(c) Various Mono authors") - - - System.Reflection.AssemblyDefaultAlias("System.Net.Http.WinHttpHandler.dll") - - - System.Reflection.AssemblyDescription("System.Net.Http.WinHttpHandler.dll") - - - System.Reflection.AssemblyFileVersion("4.6.57.0") - - - System.Reflection.AssemblyInformationalVersion("4.6.57.0") - - - System.Reflection.AssemblyProduct("Mono Common Language Infrastructure") - - - System.Reflection.AssemblyTitle("System.Net.Http.WinHttpHandler.dll") - - - System.Resources.NeutralResourcesLanguage("en-US") - - - System.Resources.SatelliteContractVersion("4.0.0.0") - - + System.Runtime.CompilerServices.RuntimeCompatibility(WrapNonExceptionThrows=true) - - System.Runtime.InteropServices.ComVisible(false) - - - System.Security.SecurityCritical - System.Diagnostics.Debuggable(System.Diagnostics.DebuggableAttribute+DebuggingModes.Default | System.Diagnostics.DebuggableAttribute+DebuggingModes.DisableOptimizations | System.Diagnostics.DebuggableAttribute+DebuggingModes.EnableEditAndContinue | System.Diagnostics.DebuggableAttribute+DebuggingModes.IgnoreSymbolStoreSequencePoints) @@ -179214,15 +178575,6 @@ System.Reflection.AssemblyMetadata("PreferInbox", "True") - - System.Reflection.AssemblyFileVersion("4.0.50524.0") - - - System.Reflection.AssemblyInformationalVersion("4.0.50524.0") - - - System.Resources.SatelliteContractVersion("2.0.5.0") - System.Reflection.AssemblyFileVersion("4.6.26515.06") @@ -179666,51 +179018,33 @@ [00 00 00 00 00 00 00 00 04 00 00 00 00 00 00 00 ] - + System.CLSCompliant(true) - + System.Diagnostics.Debuggable(System.Diagnostics.DebuggableAttribute+DebuggingModes.IgnoreSymbolStoreSequencePoints) - - System.Reflection.AssemblyCompany("Mono development team") - - - System.Reflection.AssemblyCopyright("(c) Various Mono authors") - - + System.Reflection.AssemblyDefaultAlias("System.Numerics.dll") - + System.Reflection.AssemblyDescription("System.Numerics.dll") - - System.Reflection.AssemblyFileVersion("4.6.57.0") - - - System.Reflection.AssemblyInformationalVersion("4.6.57.0") - - - System.Reflection.AssemblyProduct("Mono Common Language Infrastructure") - - + System.Reflection.AssemblyTitle("System.Numerics.dll") - + System.Resources.NeutralResourcesLanguage("en-US") - + System.Resources.SatelliteContractVersion("4.0.0.0") - + System.Runtime.CompilerServices.RuntimeCompatibility(WrapNonExceptionThrows=true) - + System.Runtime.InteropServices.ComVisible(false) - - System.Security.SecurityCritical - System.Reflection.AssemblyCompany("Microsoft Corporation") @@ -179810,15 +179144,6 @@ System.Reflection.AssemblyInformationalVersion("4.7.3056.0") - - System.Reflection.AssemblyFileVersion("4.0.50524.0") - - - System.Reflection.AssemblyInformationalVersion("4.0.50524.0") - - - System.Resources.SatelliteContractVersion("2.0.5.0") - System.Reflection.AssemblyFileVersion("4.6.27115.0") @@ -180836,51 +180161,33 @@ [00 24 00 00 04 80 00 00 94 00 00 00 06 02 00 00 00 24 00 00 52 53 41 31 00 04 00 00 01 00 01 00 07 d1 fa 57 c4 ae d9 f0 a3 2e 84 aa 0f ae fd 0d e9 e8 fd 6a ec 8f 87 fb 03 76 6c 83 4c 99 92 1e b2 3b e7 9a d9 d5 dc c1 dd 9a d2 36 13 21 02 90 0b 72 3c f9 80 95 7f c4 e1 77 10 8f c6 07 77 4f 29 e8 32 0e 92 ea 05 ec e4 e8 21 c0 a5 ef e8 f1 64 5c 4c 0c 93 c1 ab 99 28 5d 62 2c aa 65 2c 1d fa d6 3d 74 5d 6f 2d e5 f1 7e 5e af 0f c4 96 3d 26 1c 8a 12 43 65 18 20 6d c0 93 34 4d 5a d2 93 ] - + System.CLSCompliant(true) - + System.Diagnostics.Debuggable(System.Diagnostics.DebuggableAttribute+DebuggingModes.IgnoreSymbolStoreSequencePoints) - - System.Reflection.AssemblyCompany("Mono development team") - - - System.Reflection.AssemblyCopyright("(c) Various Mono authors") - - + System.Reflection.AssemblyDefaultAlias("System.Numerics.Vectors.dll") - + System.Reflection.AssemblyDescription("System.Numerics.Vectors.dll") - - System.Reflection.AssemblyFileVersion("4.6.57.0") - - - System.Reflection.AssemblyInformationalVersion("4.6.57.0") - - - System.Reflection.AssemblyProduct("Mono Common Language Infrastructure") - - + System.Reflection.AssemblyTitle("System.Numerics.Vectors.dll") - + System.Resources.NeutralResourcesLanguage("en-US") - + System.Resources.SatelliteContractVersion("4.0.0.0") - + System.Runtime.CompilerServices.RuntimeCompatibility(WrapNonExceptionThrows=true) - + System.Runtime.InteropServices.ComVisible(false) - - System.Security.SecurityCritical - System.Diagnostics.Debuggable(System.Diagnostics.DebuggableAttribute+DebuggingModes.Default | System.Diagnostics.DebuggableAttribute+DebuggingModes.DisableOptimizations | System.Diagnostics.DebuggableAttribute+DebuggingModes.EnableEditAndContinue | System.Diagnostics.DebuggableAttribute+DebuggingModes.IgnoreSymbolStoreSequencePoints) @@ -180959,15 +180266,6 @@ System.Reflection.AssemblyInformationalVersion("4.6.1028.0") - - System.Reflection.AssemblyFileVersion("4.0.50524.0") - - - System.Reflection.AssemblyInformationalVersion("4.0.50524.0") - - - System.Resources.SatelliteContractVersion("2.0.5.0") - System.Reflection.AssemblyCopyright("© Microsoft Corporation. All rights reserved.") @@ -181605,51 +180903,33 @@ [00 00 00 00 00 00 00 00 04 00 00 00 00 00 00 00 ] - + System.CLSCompliant(true) - + System.Diagnostics.Debuggable(System.Diagnostics.DebuggableAttribute+DebuggingModes.IgnoreSymbolStoreSequencePoints) - - System.Reflection.AssemblyCompany("Mono development team") - - - System.Reflection.AssemblyCopyright("(c) Various Mono authors") - - + System.Reflection.AssemblyDefaultAlias("System.Reflection.Context.dll") - + System.Reflection.AssemblyDescription("System.Reflection.Context.dll") - - System.Reflection.AssemblyFileVersion("4.6.57.0") - - - System.Reflection.AssemblyInformationalVersion("4.6.57.0") - - - System.Reflection.AssemblyProduct("Mono Common Language Infrastructure") - - + System.Reflection.AssemblyTitle("System.Reflection.Context.dll") - + System.Resources.NeutralResourcesLanguage("en-US") - + System.Resources.SatelliteContractVersion("4.0.0.0") - + System.Runtime.CompilerServices.RuntimeCompatibility(WrapNonExceptionThrows=true) - + System.Runtime.InteropServices.ComVisible(false) - - System.Security.SecurityCritical - System.Reflection.AssemblyCompany("Microsoft Corporation") @@ -181767,15 +181047,6 @@ System.Reflection.AssemblyInformationalVersion("4.7.3056.0") - - System.Reflection.AssemblyFileVersion("4.0.50524.0") - - - System.Reflection.AssemblyInformationalVersion("4.0.50524.0") - - - System.Resources.SatelliteContractVersion("2.0.5.0") - System.Reflection.AssemblyFileVersion("4.0.30319.17929") @@ -182753,51 +182024,15 @@ [00 24 00 00 04 80 00 00 94 00 00 00 06 02 00 00 00 24 00 00 52 53 41 31 00 04 00 00 01 00 01 00 07 d1 fa 57 c4 ae d9 f0 a3 2e 84 aa 0f ae fd 0d e9 e8 fd 6a ec 8f 87 fb 03 76 6c 83 4c 99 92 1e b2 3b e7 9a d9 d5 dc c1 dd 9a d2 36 13 21 02 90 0b 72 3c f9 80 95 7f c4 e1 77 10 8f c6 07 77 4f 29 e8 32 0e 92 ea 05 ec e4 e8 21 c0 a5 ef e8 f1 64 5c 4c 0c 93 c1 ab 99 28 5d 62 2c aa 65 2c 1d fa d6 3d 74 5d 6f 2d e5 f1 7e 5e af 0f c4 96 3d 26 1c 8a 12 43 65 18 20 6d c0 93 34 4d 5a d2 93 ] - + System.CLSCompliant(true) - + System.Diagnostics.Debuggable(System.Diagnostics.DebuggableAttribute+DebuggingModes.IgnoreSymbolStoreSequencePoints) - - System.Reflection.AssemblyCompany("Mono development team") - - - System.Reflection.AssemblyCopyright("(c) Various Mono authors") - - - System.Reflection.AssemblyDefaultAlias("System.Runtime.InteropServices.RuntimeInformation.dll") - - - System.Reflection.AssemblyDescription("System.Runtime.InteropServices.RuntimeInformation.dll") - - - System.Reflection.AssemblyFileVersion("4.6.57.0") - - - System.Reflection.AssemblyInformationalVersion("4.6.57.0") - - - System.Reflection.AssemblyProduct("Mono Common Language Infrastructure") - - - System.Reflection.AssemblyTitle("System.Runtime.InteropServices.RuntimeInformation.dll") - - - System.Resources.NeutralResourcesLanguage("en-US") - - - System.Resources.SatelliteContractVersion("4.0.0.0") - - + System.Runtime.CompilerServices.RuntimeCompatibility(WrapNonExceptionThrows=true) - - System.Runtime.InteropServices.ComVisible(false) - - - System.Security.SecurityCritical - System.Diagnostics.Debuggable(System.Diagnostics.DebuggableAttribute+DebuggingModes.Default | System.Diagnostics.DebuggableAttribute+DebuggingModes.DisableOptimizations | System.Diagnostics.DebuggableAttribute+DebuggingModes.EnableEditAndContinue | System.Diagnostics.DebuggableAttribute+DebuggingModes.IgnoreSymbolStoreSequencePoints) @@ -182867,15 +182102,6 @@ System.Reflection.AssemblyInformationalVersion("4.6.24913.01 built by: dlab-DDVSOWINAGE018. Commit Hash: 296dc18f32e718280794becd8eccc67aab50251b") - - System.Reflection.AssemblyFileVersion("4.0.50524.0") - - - System.Reflection.AssemblyInformationalVersion("4.0.50524.0") - - - System.Resources.SatelliteContractVersion("2.0.5.0") - System.Reflection.AssemblyCopyright("© Microsoft Corporation. All rights reserved.") @@ -183671,55 +182897,40 @@ [00 00 00 00 00 00 00 00 04 00 00 00 00 00 00 00 ] - + System.CLSCompliant(true) - + System.Diagnostics.Debuggable(System.Diagnostics.DebuggableAttribute+DebuggingModes.IgnoreSymbolStoreSequencePoints) - - System.Reflection.AssemblyCompany("Mono development team") - - - System.Reflection.AssemblyCopyright("(c) Various Mono authors") - - + System.Reflection.AssemblyDefaultAlias("System.Runtime.Serialization.dll") - + System.Reflection.AssemblyDescription("System.Runtime.Serialization.dll") - - System.Reflection.AssemblyFileVersion("4.6.57.0") - - - System.Reflection.AssemblyInformationalVersion("4.6.57.0") - - - System.Reflection.AssemblyProduct("Mono Common Language Infrastructure") - - + System.Reflection.AssemblyTitle("System.Runtime.Serialization.dll") - + System.Resources.NeutralResourcesLanguage("en-US") - + System.Resources.SatelliteContractVersion("4.0.0.0") - + System.Runtime.CompilerServices.RuntimeCompatibility(WrapNonExceptionThrows=true) - + System.Runtime.InteropServices.ComCompatibleVersion(1, 0, 3300, 0) - + System.Runtime.InteropServices.ComVisible(false) - + System.Security.AllowPartiallyTrustedCallers - + System.Security.SecurityCritical(System.Security.SecurityCriticalScope.Explicit) @@ -183833,15 +183044,6 @@ System.Reflection.AssemblyInformationalVersion("4.7.3056.0") - - System.Reflection.AssemblyFileVersion("4.0.50524.0") - - - System.Reflection.AssemblyInformationalVersion("4.0.50524.0") - - - System.Resources.SatelliteContractVersion("2.0.5.0") - System.Reflection.AssemblyFileVersion("4.6.27115.0") @@ -184939,52 +184141,34 @@ [00 24 00 00 04 80 00 00 94 00 00 00 06 02 00 00 00 24 00 00 52 53 41 31 00 04 00 00 01 00 01 00 07 d1 fa 57 c4 ae d9 f0 a3 2e 84 aa 0f ae fd 0d e9 e8 fd 6a ec 8f 87 fb 03 76 6c 83 4c 99 92 1e b2 3b e7 9a d9 d5 dc c1 dd 9a d2 36 13 21 02 90 0b 72 3c f9 80 95 7f c4 e1 77 10 8f c6 07 77 4f 29 e8 32 0e 92 ea 05 ec e4 e8 21 c0 a5 ef e8 f1 64 5c 4c 0c 93 c1 ab 99 28 5d 62 2c aa 65 2c 1d fa d6 3d 74 5d 6f 2d e5 f1 7e 5e af 0f c4 96 3d 26 1c 8a 12 43 65 18 20 6d c0 93 34 4d 5a d2 93 ] - + System.CLSCompliant(true) - + System.Diagnostics.Debuggable(System.Diagnostics.DebuggableAttribute+DebuggingModes.IgnoreSymbolStoreSequencePoints) - - System.Reflection.AssemblyCompany("Mono development team") - - - System.Reflection.AssemblyCopyright("(c) Various Mono authors") - - + System.Reflection.AssemblyDefaultAlias("System.Runtime.Serialization.Formatters.Soap.dll") - + System.Reflection.AssemblyDescription("System.Runtime.Serialization.Formatters.Soap.dll") - - System.Reflection.AssemblyFileVersion("4.6.57.0") - - - System.Reflection.AssemblyInformationalVersion("4.6.57.0") - - - System.Reflection.AssemblyProduct("Mono Common Language Infrastructure") - - + System.Reflection.AssemblyTitle("System.Runtime.Serialization.Formatters.Soap.dll") - + System.Resources.NeutralResourcesLanguage("en-US") - + System.Resources.SatelliteContractVersion("4.0.0.0") - - System.Runtime.CompilerServices.CompilationRelaxations(System.Runtime.CompilerServices.CompilationRelaxations.NoStringInterning) - - + System.Runtime.CompilerServices.RuntimeCompatibility(WrapNonExceptionThrows=true) - + System.Runtime.InteropServices.ComCompatibleVersion(1, 0, 3300, 0) - + System.Runtime.InteropServices.ComVisible(true) @@ -185919,49 +185103,34 @@ [00 24 00 00 04 80 00 00 94 00 00 00 06 02 00 00 00 24 00 00 52 53 41 31 00 04 00 00 01 00 01 00 07 d1 fa 57 c4 ae d9 f0 a3 2e 84 aa 0f ae fd 0d e9 e8 fd 6a ec 8f 87 fb 03 76 6c 83 4c 99 92 1e b2 3b e7 9a d9 d5 dc c1 dd 9a d2 36 13 21 02 90 0b 72 3c f9 80 95 7f c4 e1 77 10 8f c6 07 77 4f 29 e8 32 0e 92 ea 05 ec e4 e8 21 c0 a5 ef e8 f1 64 5c 4c 0c 93 c1 ab 99 28 5d 62 2c aa 65 2c 1d fa d6 3d 74 5d 6f 2d e5 f1 7e 5e af 0f c4 96 3d 26 1c 8a 12 43 65 18 20 6d c0 93 34 4d 5a d2 93 ] - + System.CLSCompliant(true) - + System.Diagnostics.Debuggable(System.Diagnostics.DebuggableAttribute+DebuggingModes.IgnoreSymbolStoreSequencePoints) - - System.Reflection.AssemblyCompany("Mono development team") - - - System.Reflection.AssemblyCopyright("(c) Various Mono authors") - - + System.Reflection.AssemblyDefaultAlias("System.Security.dll") - + System.Reflection.AssemblyDescription("System.Security.dll") - - System.Reflection.AssemblyFileVersion("4.6.57.0") - - - System.Reflection.AssemblyInformationalVersion("4.6.57.0") - - - System.Reflection.AssemblyProduct("Mono Common Language Infrastructure") - - + System.Reflection.AssemblyTitle("System.Security.dll") - + System.Resources.NeutralResourcesLanguage("en-US") - + System.Resources.SatelliteContractVersion("4.0.0.0") - + System.Runtime.CompilerServices.RuntimeCompatibility(WrapNonExceptionThrows=true) - + System.Runtime.InteropServices.ComVisible(false) - + System.Security.AllowPartiallyTrustedCallers @@ -186069,15 +185238,6 @@ System.Reflection.AssemblyInformationalVersion("4.7.3056.0") - - System.Reflection.AssemblyFileVersion("4.0.50524.0") - - - System.Reflection.AssemblyInformationalVersion("4.0.50524.0") - - - System.Resources.SatelliteContractVersion("2.0.5.0") - System.Reflection.AssemblyFileVersion("4.6.27115.0") @@ -187228,64 +186388,49 @@ [00 00 00 00 00 00 00 00 04 00 00 00 00 00 00 00 ] - + System.CLSCompliant(true) - + System.Diagnostics.Debuggable(System.Diagnostics.DebuggableAttribute+DebuggingModes.IgnoreSymbolStoreSequencePoints) - - System.Reflection.AssemblyCompany("Mono development team") - - - System.Reflection.AssemblyCopyright("(c) Various Mono authors") - - + System.Reflection.AssemblyDefaultAlias("System.ServiceModel.dll") - + System.Reflection.AssemblyDescription("System.ServiceModel.dll") - - System.Reflection.AssemblyFileVersion("4.6.57.0") - - - System.Reflection.AssemblyInformationalVersion("4.6.57.0") - - - System.Reflection.AssemblyProduct("Mono Common Language Infrastructure") - - + System.Reflection.AssemblyTitle("System.ServiceModel.dll") - + System.Resources.NeutralResourcesLanguage("en-US") - + System.Resources.SatelliteContractVersion("4.0.0.0") - + System.Runtime.CompilerServices.InternalsVisibleTo("System.ServiceModel.Web, PublicKey=0024000004800000940000000602000000240000525341310004000001000100b5fc90e7027f67871e773a8fde8938c81dd402ba65b9201d60593e96c492651e889cc13f1415ebb53fac1131ae0bd333c5ee6021672d9718ea31a8aebd0da0072f25d87dba6fc90ffd598ed4da35e44c398c454307e8e33b8426143daec9f596836f97c8f74750e5975c64e2189f45def46b2a2b1247adc3652bf5c308055da9") - + System.Runtime.CompilerServices.InternalsVisibleTo("System.ServiceModel.Routing, PublicKey=0024000004800000940000000602000000240000525341310004000001000100b5fc90e7027f67871e773a8fde8938c81dd402ba65b9201d60593e96c492651e889cc13f1415ebb53fac1131ae0bd333c5ee6021672d9718ea31a8aebd0da0072f25d87dba6fc90ffd598ed4da35e44c398c454307e8e33b8426143daec9f596836f97c8f74750e5975c64e2189f45def46b2a2b1247adc3652bf5c308055da9") - + System.Runtime.CompilerServices.InternalsVisibleTo("System.ServiceModel.Discovery, PublicKey=0024000004800000940000000602000000240000525341310004000001000100b5fc90e7027f67871e773a8fde8938c81dd402ba65b9201d60593e96c492651e889cc13f1415ebb53fac1131ae0bd333c5ee6021672d9718ea31a8aebd0da0072f25d87dba6fc90ffd598ed4da35e44c398c454307e8e33b8426143daec9f596836f97c8f74750e5975c64e2189f45def46b2a2b1247adc3652bf5c308055da9") - + System.Runtime.CompilerServices.RuntimeCompatibility(WrapNonExceptionThrows=true) - + System.Runtime.InteropServices.ComCompatibleVersion(1, 0, 3300, 0) - + System.Runtime.InteropServices.ComVisible(false) - + System.Security.AllowPartiallyTrustedCallers - + System.Security.SecurityCritical(System.Security.SecurityCriticalScope.Explicit) @@ -187468,15 +186613,6 @@ System.Reflection.AssemblyInformationalVersion("4.7.3056.0") - - System.Reflection.AssemblyFileVersion("4.0.50524.0") - - - System.Reflection.AssemblyInformationalVersion("4.0.50524.0") - - - System.Resources.SatelliteContractVersion("2.0.5.0") - System.Reflection.AssemblyFileVersion("4.6.1055.0") @@ -188481,12 +187617,6 @@ System.Reflection.AssemblyDescription("Contains share code for some System.ServiceModel libraries") - - System.Reflection.AssemblyFileVersion("4.6.57.0") - - - System.Reflection.AssemblyInformationalVersion("4.6.57.0") - System.Reflection.AssemblyTitle("System.ServiceModel.Internals.dll") @@ -188496,9 +187626,6 @@ System.Runtime.CompilerServices.InternalsVisibleTo("SMDiagnostics, PublicKey=00000000000000000400000000000000") - - System.Runtime.CompilerServices.InternalsVisibleTo("System.Runtime.DurableInstancing, PublicKey=00000000000000000400000000000000") - System.Runtime.CompilerServices.InternalsVisibleTo("System.Runtime.Serialization, PublicKey=00000000000000000400000000000000") @@ -188511,9 +187638,6 @@ System.Runtime.CompilerServices.InternalsVisibleTo("System.ServiceModel, PublicKey=00000000000000000400000000000000") - - System.Runtime.CompilerServices.InternalsVisibleTo("System.ServiceModel.Web, PublicKey=00000000000000000400000000000000") - System.Runtime.CompilerServices.InternalsVisibleTo("System.Activities, PublicKey=0024000004800000940000000602000000240000525341310004000001000100b5fc90e7027f67871e773a8fde8938c81dd402ba65b9201d60593e96c492651e889cc13f1415ebb53fac1131ae0bd333c5ee6021672d9718ea31a8aebd0da0072f25d87dba6fc90ffd598ed4da35e44c398c454307e8e33b8426143daec9f596836f97c8f74750e5975c64e2189f45def46b2a2b1247adc3652bf5c308055da9") @@ -188640,48 +187764,12 @@ System.Runtime.CompilerServices.RuntimeCompatibility(WrapNonExceptionThrows=true) - - System.Runtime.InteropServices.ComCompatibleVersion(1, 0, 3300, 0) - System.Runtime.InteropServices.ComVisible(false) System.Runtime.InteropServices.Guid("a9b8c4b5-b4a9-4800-8268-e8ec3b93d9ac") - - System.Security.AllowPartiallyTrustedCallers - - - System.Security.SecurityCritical(System.Security.SecurityCriticalScope.Explicit) - - - System.Reflection.AssemblyFileVersion("4.0.50524.0") - - - System.Reflection.AssemblyInformationalVersion("4.0.50524.0") - - - System.Runtime.CompilerServices.InternalsVisibleTo("SMDiagnostics, PublicKey=0024000004800000940000000602000000240000525341310004000001000100B5FC90E7027F67871E773A8FDE8938C81DD402BA65B9201D60593E96C492651E889CC13F1415EBB53FAC1131AE0BD333C5EE6021672D9718EA31A8AEBD0DA0072F25D87DBA6FC90FFD598ED4DA35E44C398C454307E8E33B8426143DAEC9F596836F97C8F74750E5975C64E2189F45DEF46B2A2B1247ADC3652BF5C308055DA9") - - - System.Runtime.CompilerServices.InternalsVisibleTo("System.Runtime.DurableInstancing, PublicKey=00240000048000009400000006020000002400005253413100040000010001008D56C76F9E8649383049F383C44BE0EC204181822A6C31CF5EB7EF486944D032188EA1D3920763712CCB12D75FB77E9811149E6148E5D32FBAAB37611C1878DDC19E20EF135D0CB2CFF2BFEC3D115810C3D9069638FE4BE215DBF795861920E5AB6F7DB2E2CEEF136AC23D5DD2BF031700AEC232F6C6B1C785B4305C123B37AB") - - - System.Runtime.CompilerServices.InternalsVisibleTo("System.Runtime.Serialization, PublicKey=00240000048000009400000006020000002400005253413100040000010001008D56C76F9E8649383049F383C44BE0EC204181822A6C31CF5EB7EF486944D032188EA1D3920763712CCB12D75FB77E9811149E6148E5D32FBAAB37611C1878DDC19E20EF135D0CB2CFF2BFEC3D115810C3D9069638FE4BE215DBF795861920E5AB6F7DB2E2CEEF136AC23D5DD2BF031700AEC232F6C6B1C785B4305C123B37AB") - - - System.Runtime.CompilerServices.InternalsVisibleTo("System.IdentityModel, PublicKey=00240000048000009400000006020000002400005253413100040000010001008D56C76F9E8649383049F383C44BE0EC204181822A6C31CF5EB7EF486944D032188EA1D3920763712CCB12D75FB77E9811149E6148E5D32FBAAB37611C1878DDC19E20EF135D0CB2CFF2BFEC3D115810C3D9069638FE4BE215DBF795861920E5AB6F7DB2E2CEEF136AC23D5DD2BF031700AEC232F6C6B1C785B4305C123B37AB") - - - System.Runtime.CompilerServices.InternalsVisibleTo("System.IdentityModel.Selectors, PublicKey=00240000048000009400000006020000002400005253413100040000010001008D56C76F9E8649383049F383C44BE0EC204181822A6C31CF5EB7EF486944D032188EA1D3920763712CCB12D75FB77E9811149E6148E5D32FBAAB37611C1878DDC19E20EF135D0CB2CFF2BFEC3D115810C3D9069638FE4BE215DBF795861920E5AB6F7DB2E2CEEF136AC23D5DD2BF031700AEC232F6C6B1C785B4305C123B37AB") - - - System.Runtime.CompilerServices.InternalsVisibleTo("System.ServiceModel, PublicKey=00240000048000009400000006020000002400005253413100040000010001008D56C76F9E8649383049F383C44BE0EC204181822A6C31CF5EB7EF486944D032188EA1D3920763712CCB12D75FB77E9811149E6148E5D32FBAAB37611C1878DDC19E20EF135D0CB2CFF2BFEC3D115810C3D9069638FE4BE215DBF795861920E5AB6F7DB2E2CEEF136AC23D5DD2BF031700AEC232F6C6B1C785B4305C123B37AB") - - - System.Runtime.CompilerServices.InternalsVisibleTo("System.ServiceModel.Web, PublicKey=00240000048000009400000006020000002400005253413100040000010001008D56C76F9E8649383049F383C44BE0EC204181822A6C31CF5EB7EF486944D032188EA1D3920763712CCB12D75FB77E9811149E6148E5D32FBAAB37611C1878DDC19E20EF135D0CB2CFF2BFEC3D115810C3D9069638FE4BE215DBF795861920E5AB6F7DB2E2CEEF136AC23D5DD2BF031700AEC232F6C6B1C785B4305C123B37AB") - [00 24 00 00 04 80 00 00 94 00 00 00 06 02 00 00 00 24 00 00 52 53 41 31 00 04 00 00 01 00 01 00 b5 fc 90 e7 02 7f 67 87 1e 77 3a 8f de 89 38 c8 1d d4 02 ba 65 b9 20 1d 60 59 3e 96 c4 92 65 1e 88 9c c1 3f 14 15 eb b5 3f ac 11 31 ae 0b d3 33 c5 ee 60 21 67 2d 97 18 ea 31 a8 ae bd 0d a0 07 2f 25 d8 7d ba 6f c9 0f fd 59 8e d4 da 35 e4 4c 39 8c 45 43 07 e8 e3 3b 84 26 14 3d ae c9 f5 96 83 6f 97 c8 f7 47 50 e5 97 5c 64 e2 18 9f 45 de f4 6b 2a 2b 12 47 ad c3 65 2b f5 c3 08 05 5d a9 ] [00 00 00 00 00 00 00 00 04 00 00 00 00 00 00 00 ] @@ -188872,52 +187960,31 @@ [00 24 00 00 04 80 00 00 94 00 00 00 06 02 00 00 00 24 00 00 52 53 41 31 00 04 00 00 01 00 01 00 b5 fc 90 e7 02 7f 67 87 1e 77 3a 8f de 89 38 c8 1d d4 02 ba 65 b9 20 1d 60 59 3e 96 c4 92 65 1e 88 9c c1 3f 14 15 eb b5 3f ac 11 31 ae 0b d3 33 c5 ee 60 21 67 2d 97 18 ea 31 a8 ae bd 0d a0 07 2f 25 d8 7d ba 6f c9 0f fd 59 8e d4 da 35 e4 4c 39 8c 45 43 07 e8 e3 3b 84 26 14 3d ae c9 f5 96 83 6f 97 c8 f7 47 50 e5 97 5c 64 e2 18 9f 45 de f4 6b 2a 2b 12 47 ad c3 65 2b f5 c3 08 05 5d a9 ] - + System.CLSCompliant(true) - + System.Diagnostics.Debuggable(System.Diagnostics.DebuggableAttribute+DebuggingModes.IgnoreSymbolStoreSequencePoints) - - System.Reflection.AssemblyCompany("MONO development team") - - - System.Reflection.AssemblyCopyright("(c) 2003 Various Authors") - - + System.Reflection.AssemblyDefaultAlias("System.ServiceModel.Web.dll") - + System.Reflection.AssemblyDescription("System.ServiceModel.Web.dll") - - System.Reflection.AssemblyFileVersion("4.6.57.0") - - - System.Reflection.AssemblyInformationalVersion("3.5.594.0") - - - System.Reflection.AssemblyProduct("MONO CLI") - - + System.Reflection.AssemblyTitle("System.ServiceModel.Web.dll") - + System.Resources.NeutralResourcesLanguage("en-US") - + System.Resources.SatelliteContractVersion("4.0.0.0") - - System.Runtime.CompilerServices.CompilationRelaxations(System.Runtime.CompilerServices.CompilationRelaxations.NoStringInterning) - - - System.Runtime.CompilerServices.InternalsVisibleTo("dummy-System.Json, PublicKey=00240000048000009400000006020000002400005253413100040000010001008D56C76F9E8649383049F383C44BE0EC204181822A6C31CF5EB7EF486944D032188EA1D3920763712CCB12D75FB77E9811149E6148E5D32FBAAB37611C1878DDC19E20EF135D0CB2CFF2BFEC3D115810C3D9069638FE4BE215DBF795861920E5AB6F7DB2E2CEEF136AC23D5DD2BF031700AEC232F6C6B1C785B4305C123B37AB") - - + System.Runtime.CompilerServices.RuntimeCompatibility(WrapNonExceptionThrows=true) - + System.Runtime.InteropServices.ComVisible(false) @@ -189034,24 +188101,6 @@ System.Reflection.AssemblyInformationalVersion("4.7.3056.0") - - System.Reflection.AssemblyFileVersion("4.0.50524.0") - - - System.Reflection.AssemblyInformationalVersion("4.0.50524.0") - - - System.Resources.SatelliteContractVersion("2.0.5.0") - - - System.Runtime.CompilerServices.InternalsVisibleTo("System.Json, PublicKey=0024000004800000940000000602000000240000525341310004000001000100b5fc90e7027f67871e773a8fde8938c81dd402ba65b9201d60593e96c492651e889cc13f1415ebb53fac1131ae0bd333c5ee6021672d9718ea31a8aebd0da0072f25d87dba6fc90ffd598ed4da35e44c398c454307e8e33b8426143daec9f596836f97c8f74750e5975c64e2189f45def46b2a2b1247adc3652bf5c308055da9") - - - System.Runtime.CompilerServices.InternalsVisibleTo("System.ServiceModel.Web.Extensions, PublicKey=0024000004800000940000000602000000240000525341310004000001000100b5fc90e7027f67871e773a8fde8938c81dd402ba65b9201d60593e96c492651e889cc13f1415ebb53fac1131ae0bd333c5ee6021672d9718ea31a8aebd0da0072f25d87dba6fc90ffd598ed4da35e44c398c454307e8e33b8426143daec9f596836f97c8f74750e5975c64e2189f45def46b2a2b1247adc3652bf5c308055da9") - - - System.Runtime.CompilerServices.InternalsVisibleTo("System.Windows.Browser, PublicKey=00240000048000009400000006020000002400005253413100040000010001008D56C76F9E8649383049F383C44BE0EC204181822A6C31CF5EB7EF486944D032188EA1D3920763712CCB12D75FB77E9811149E6148E5D32FBAAB37611C1878DDC19E20EF135D0CB2CFF2BFEC3D115810C3D9069638FE4BE215DBF795861920E5AB6F7DB2E2CEEF136AC23D5DD2BF031700AEC232F6C6B1C785B4305C123B37AB") - System.Reflection.AssemblyFileVersion("4.6.27115.0") @@ -190109,52 +189158,37 @@ [00 00 00 00 00 00 00 00 04 00 00 00 00 00 00 00 ] - + System.CLSCompliant(true) - + System.Diagnostics.Debuggable(System.Diagnostics.DebuggableAttribute+DebuggingModes.IgnoreSymbolStoreSequencePoints) - - System.Reflection.AssemblyCompany("Mono development team") - - - System.Reflection.AssemblyCopyright("(c) Various Mono authors") - - + System.Reflection.AssemblyDefaultAlias("System.Transactions.dll") - + System.Reflection.AssemblyDescription("System.Transactions.dll") - - System.Reflection.AssemblyFileVersion("4.6.57.0") - - - System.Reflection.AssemblyInformationalVersion("4.6.57.0") - - - System.Reflection.AssemblyProduct("Mono Common Language Infrastructure") - - + System.Reflection.AssemblyTitle("System.Transactions.dll") - + System.Resources.NeutralResourcesLanguage("en-US") - + System.Resources.SatelliteContractVersion("4.0.0.0") - + System.Runtime.CompilerServices.RuntimeCompatibility(WrapNonExceptionThrows=true) - + System.Runtime.InteropServices.BestFitMapping(false) - + System.Runtime.InteropServices.ComVisible(false) - + System.Security.AllowPartiallyTrustedCallers @@ -190259,15 +189293,6 @@ System.Reflection.AssemblyInformationalVersion("4.7.3056.0") - - System.Reflection.AssemblyFileVersion("4.0.50524.0") - - - System.Reflection.AssemblyInformationalVersion("4.0.50524.0") - - - System.Resources.SatelliteContractVersion("2.0.5.0") - System.Reflection.AssemblyFileVersion("4.6.27115.0") @@ -191383,52 +190408,34 @@ [00 24 00 00 04 80 00 00 94 00 00 00 06 02 00 00 00 24 00 00 52 53 41 31 00 04 00 00 01 00 01 00 07 d1 fa 57 c4 ae d9 f0 a3 2e 84 aa 0f ae fd 0d e9 e8 fd 6a ec 8f 87 fb 03 76 6c 83 4c 99 92 1e b2 3b e7 9a d9 d5 dc c1 dd 9a d2 36 13 21 02 90 0b 72 3c f9 80 95 7f c4 e1 77 10 8f c6 07 77 4f 29 e8 32 0e 92 ea 05 ec e4 e8 21 c0 a5 ef e8 f1 64 5c 4c 0c 93 c1 ab 99 28 5d 62 2c aa 65 2c 1d fa d6 3d 74 5d 6f 2d e5 f1 7e 5e af 0f c4 96 3d 26 1c 8a 12 43 65 18 20 6d c0 93 34 4d 5a d2 93 ] - + System.CLSCompliant(true) - + System.Diagnostics.Debuggable(System.Diagnostics.DebuggableAttribute+DebuggingModes.IgnoreSymbolStoreSequencePoints) - - System.Reflection.AssemblyCompany("Mono development team") - - - System.Reflection.AssemblyCopyright("(c) Various Mono authors") - - + System.Reflection.AssemblyDefaultAlias("System.Web.Services.dll") - + System.Reflection.AssemblyDescription("System.Web.Services.dll") - - System.Reflection.AssemblyFileVersion("4.6.57.0") - - - System.Reflection.AssemblyInformationalVersion("4.6.57.0") - - - System.Reflection.AssemblyProduct("Mono Common Language Infrastructure") - - + System.Reflection.AssemblyTitle("System.Web.Services.dll") - + System.Resources.NeutralResourcesLanguage("en-US") - + System.Resources.SatelliteContractVersion("4.0.0.0") - - System.Runtime.CompilerServices.CompilationRelaxations(System.Runtime.CompilerServices.CompilationRelaxations.NoStringInterning) - - + System.Runtime.CompilerServices.RuntimeCompatibility(WrapNonExceptionThrows=true) - + System.Runtime.InteropServices.ComVisible(false) - + System.Security.AllowPartiallyTrustedCallers @@ -191539,15 +190546,6 @@ System.Reflection.AssemblyInformationalVersion("4.7.3056.0") - - System.Reflection.AssemblyFileVersion("4.0.50524.0") - - - System.Reflection.AssemblyInformationalVersion("4.0.50524.0") - - - System.Resources.SatelliteContractVersion("2.0.5.0") - System.Reflection.AssemblyFileVersion("4.8.3761.0") @@ -192511,31 +191509,16 @@ [00 24 00 00 04 80 00 00 94 00 00 00 06 02 00 00 00 24 00 00 52 53 41 31 00 04 00 00 01 00 01 00 07 d1 fa 57 c4 ae d9 f0 a3 2e 84 aa 0f ae fd 0d e9 e8 fd 6a ec 8f 87 fb 03 76 6c 83 4c 99 92 1e b2 3b e7 9a d9 d5 dc c1 dd 9a d2 36 13 21 02 90 0b 72 3c f9 80 95 7f c4 e1 77 10 8f c6 07 77 4f 29 e8 32 0e 92 ea 05 ec e4 e8 21 c0 a5 ef e8 f1 64 5c 4c 0c 93 c1 ab 99 28 5d 62 2c aa 65 2c 1d fa d6 3d 74 5d 6f 2d e5 f1 7e 5e af 0f c4 96 3d 26 1c 8a 12 43 65 18 20 6d c0 93 34 4d 5a d2 93 ] - - System.Reflection.AssemblyCompany("Mono development team") - - - System.Reflection.AssemblyCopyright("(c) Various Mono authors") - - + System.Reflection.AssemblyDefaultAlias("System.Windows.dll") - + System.Reflection.AssemblyDescription("System.Windows.dll") - - System.Reflection.AssemblyFileVersion("4.6.57.0") - - - System.Reflection.AssemblyInformationalVersion("4.6.57.0") - - - System.Reflection.AssemblyProduct("Mono Common Language Infrastructure") - - + System.Reflection.AssemblyTitle("System.Windows.dll") - + System.Runtime.CompilerServices.RuntimeCompatibility(WrapNonExceptionThrows=true) @@ -192637,12 +191620,6 @@ System.Reflection.AssemblyInformationalVersion("4.7.3056.0") - - System.Reflection.AssemblyFileVersion("4.0.50524.0") - - - System.Reflection.AssemblyInformationalVersion("4.0.50524.0") - System.Reflection.AssemblyFileVersion("4.6.27115.0") @@ -193620,64 +192597,43 @@ [00 00 00 00 00 00 00 00 04 00 00 00 00 00 00 00 ] - + System.CLSCompliant(true) - + System.Diagnostics.Debuggable(System.Diagnostics.DebuggableAttribute+DebuggingModes.IgnoreSymbolStoreSequencePoints) - - System.Reflection.AssemblyCompany("Mono development team") - - - System.Reflection.AssemblyCopyright("(c) Various Mono authors") - - + System.Reflection.AssemblyDefaultAlias("System.Xml.dll") - + System.Reflection.AssemblyDescription("System.Xml.dll") - - System.Reflection.AssemblyFileVersion("4.6.57.0") - - - System.Reflection.AssemblyInformationalVersion("4.6.57.0") - - - System.Reflection.AssemblyProduct("Mono Common Language Infrastructure") - - + System.Reflection.AssemblyTitle("System.Xml.dll") - + System.Resources.NeutralResourcesLanguage("en-US") - + System.Resources.SatelliteContractVersion("4.0.0.0") - - System.Runtime.CompilerServices.CompilationRelaxations(System.Runtime.CompilerServices.CompilationRelaxations.NoStringInterning) - - - System.Runtime.CompilerServices.InternalsVisibleTo("System.Xml.Linq, PublicKey=00000000000000000400000000000000", AllInternalsVisible=false) - - + System.Runtime.CompilerServices.InternalsVisibleTo("System.Data.SqlXml, PublicKey=00000000000000000400000000000000") - + System.Runtime.CompilerServices.InternalsVisibleTo("System.Xml.Linq, PublicKey=00000000000000000400000000000000") - + System.Runtime.CompilerServices.InternalsVisibleTo("System.ServiceModel.Friend, PublicKey=002400000480000094000000060200000024000052534131000400000100010007d1fa57c4aed9f0a32e84aa0faefd0de9e8fd6aec8f87fb03766c834c99921eb23be79ad9d5dcc1dd9ad236132102900b723cf980957fc4e177108fc607774f29e8320e92ea05ece4e821c0a5efe8f1645c4c0c93c1ab99285d622caa652c1dfad63d745d6f2de5f17e5eaf0fc4963d261c8a12436518206dc093344d5ad293") - + System.Runtime.CompilerServices.RuntimeCompatibility(WrapNonExceptionThrows=true) - + System.Runtime.InteropServices.ComVisible(false) - + System.Security.AllowPartiallyTrustedCallers @@ -193803,21 +192759,6 @@ System.Reflection.AssemblyInformationalVersion("4.7.3056.0") - - System.Reflection.AssemblyFileVersion("4.0.50524.0") - - - System.Reflection.AssemblyInformationalVersion("4.0.50524.0") - - - System.Resources.SatelliteContractVersion("2.0.5.0") - - - System.Runtime.CompilerServices.InternalsVisibleTo("System.ServiceModel.Web, PublicKey=00240000048000009400000006020000002400005253413100040000010001008D56C76F9E8649383049F383C44BE0EC204181822A6C31CF5EB7EF486944D032188EA1D3920763712CCB12D75FB77E9811149E6148E5D32FBAAB37611C1878DDC19E20EF135D0CB2CFF2BFEC3D115810C3D9069638FE4BE215DBF795861920E5AB6F7DB2E2CEEF136AC23D5DD2BF031700AEC232F6C6B1C785B4305C123B37AB") - - - System.Runtime.CompilerServices.InternalsVisibleTo("System.Xml.Linq, PublicKey=0024000004800000940000000602000000240000525341310004000001000100B5FC90E7027F67871E773A8FDE8938C81DD402BA65B9201D60593E96C492651E889CC13F1415EBB53FAC1131AE0BD333C5EE6021672D9718EA31A8AEBD0DA0072F25D87DBA6FC90FFD598ED4DA35E44C398C454307E8E33B8426143DAEC9F596836F97C8F74750E5975C64E2189F45DEF46B2A2B1247ADC3652BF5C308055DA9", AllInternalsVisible=false) - System.Reflection.AssemblyFileVersion("4.6.27115.0") @@ -194995,52 +193936,34 @@ [00 00 00 00 00 00 00 00 04 00 00 00 00 00 00 00 ] - + System.CLSCompliant(true) - + System.Diagnostics.Debuggable(System.Diagnostics.DebuggableAttribute+DebuggingModes.IgnoreSymbolStoreSequencePoints) - - System.Reflection.AssemblyCompany("Mono development team") - - - System.Reflection.AssemblyCopyright("(c) Various Mono authors") - - + System.Reflection.AssemblyDefaultAlias("System.Xml.Linq.dll") - + System.Reflection.AssemblyDescription("System.Xml.Linq.dll") - - System.Reflection.AssemblyFileVersion("4.6.57.0") - - - System.Reflection.AssemblyInformationalVersion("4.6.57.0") - - - System.Reflection.AssemblyProduct("Mono Common Language Infrastructure") - - + System.Reflection.AssemblyTitle("System.Xml.Linq.dll") - + System.Resources.NeutralResourcesLanguage("en-US") - + System.Resources.SatelliteContractVersion("4.0.0.0") - - System.Runtime.CompilerServices.CompilationRelaxations(System.Runtime.CompilerServices.CompilationRelaxations.NoStringInterning) - - + System.Runtime.CompilerServices.RuntimeCompatibility(WrapNonExceptionThrows=true) - + System.Runtime.InteropServices.ComVisible(false) - + System.Security.AllowPartiallyTrustedCallers @@ -195148,15 +194071,6 @@ System.Reflection.AssemblyInformationalVersion("4.7.3056.0") - - System.Reflection.AssemblyFileVersion("4.0.50524.0") - - - System.Reflection.AssemblyInformationalVersion("4.0.50524.0") - - - System.Resources.SatelliteContractVersion("2.0.5.0") - System.Reflection.AssemblyFileVersion("4.6.27115.0") @@ -196214,31 +195128,16 @@ [00 00 00 00 00 00 00 00 04 00 00 00 00 00 00 00 ] - - System.Reflection.AssemblyCompany("Mono development team") - - - System.Reflection.AssemblyCopyright("(c) Various Mono authors") - - + System.Reflection.AssemblyDefaultAlias("System.Xml.Serialization.dll") - + System.Reflection.AssemblyDescription("System.Xml.Serialization.dll") - - System.Reflection.AssemblyFileVersion("4.6.57.0") - - - System.Reflection.AssemblyInformationalVersion("4.6.57.0") - - - System.Reflection.AssemblyProduct("Mono Common Language Infrastructure") - - + System.Reflection.AssemblyTitle("System.Xml.Serialization.dll") - + System.Runtime.CompilerServices.RuntimeCompatibility(WrapNonExceptionThrows=true) @@ -196340,12 +195239,6 @@ System.Reflection.AssemblyInformationalVersion("4.7.3056.0") - - System.Reflection.AssemblyFileVersion("4.0.50524.0") - - - System.Reflection.AssemblyInformationalVersion("4.0.50524.0") - System.Reflection.AssemblyFileVersion("4.6.27115.0") @@ -215084,8 +213977,8 @@ The type of element stored in the array. The sorted array to search. The object to search for. - - + + Searches the sorted immutable array for a specified element using the default comparer and returns the zero-based index of the element, if it's found. @@ -215119,8 +214012,8 @@ The sorted array to search. The object to search for. The comparer implementation to use when comparing elements, or null to use the default comparer. - - + + Searches a sorted immutable array for a specified element and returns the zero-based index of the element, if it's found. @@ -215156,8 +214049,8 @@ The starting index of the range to search. The length of the range to search. The object to search for. - - + + Searches a sorted immutable array for a specified element and returns the zero-based index of the element, if it's found. @@ -215195,8 +214088,8 @@ The length of the range to search. The object to search for. The comparer to use when comparing elements for equality or to use the default comparer. - - + + Searches a sorted immutable array for a specified element and returns the zero-based index of the element. @@ -215226,8 +214119,8 @@ The type of elements contained in . The collection of objects to copy to the immutable array. - - + + Creates an immutable array from the specified collection. @@ -226370,8 +225263,8 @@ - - + + The type of the elements of . @@ -229673,8 +228566,8 @@ - - + + The type of the elements of . @@ -231681,8 +230574,8 @@ The type of element contained by the collection. The collection to apply the function to. A function to be invoked on each element, in a cumulative way. - - + + Applies a function to a sequence of elements in a cumulative way. @@ -231718,8 +230611,8 @@ The collection to apply the function to. The initial accumulator value. A function to be invoked on each element, in a cumulative way. - - + + Applies a function to a sequence of elements in a cumulative way. @@ -231759,8 +230652,8 @@ The initial accumulator value. A function to be invoked on each element, in a cumulative way. To be added. - - + + Applies a function to a sequence of elements in a cumulative way. @@ -231792,8 +230685,8 @@ The type of element contained by the collection. The array to check for matches. The predicate. - - + + Gets a value indicating whether all elements in this array match a given condition. @@ -231823,8 +230716,8 @@ The type of element contained by the collection. The array to check for elements. - - + + Gets a value indicating whether the array contains any elements. @@ -231856,8 +230749,8 @@ The type of element contained by the collection. The array to check for elements. The delegate that defines the condition to match to an element. - - + + Gets a value indicating whether the array contains any elements that match a specified condition. @@ -231886,8 +230779,8 @@ The type of elements in the array. The builder to check for matches. - - + + Returns a value indicating whether this collection contains any elements. @@ -231919,8 +230812,8 @@ The type of element contained by the collection. The array to find an element in. The index for the element to retrieve. - - + + Returns the element at a specified index in the array. @@ -231952,8 +230845,8 @@ The type of element contained by the collection. The array to find an element in. The index for the element to retrieve. - - + + Returns the element at a specified index in a sequence or a default value if the index is out of range. @@ -231983,8 +230876,8 @@ The type of element contained by the collection. The array to get an item from. - - + + Returns the first element in an array. @@ -232016,8 +230909,8 @@ The type of element contained by the collection. The array to get an item from. The delegate that defines the conditions of the element to search for. - - + + Returns the first element in a sequence that satisfies a specified condition. @@ -232046,8 +230939,8 @@ The type of items in the array. The builder to retrieve an item from. - - + + Returns the first element in the collection. @@ -232077,8 +230970,8 @@ The type of element contained by the collection. The array to retrieve items from. - - + + Returns the first element of a sequence, or a default value if the sequence contains no elements. @@ -232107,13 +231000,13 @@ - - + + The type of element contained by the collection. The array to retrieve elements from. The delegate that defines the conditions of the element to search for. - - + + Returns the first element of the sequence that satisfies a condition or a default value if no such element is found. @@ -232142,8 +231035,8 @@ The type of item in the builder. The builder to retrieve an element from. - - + + Returns the first element in the collection, or the default value if the collection is empty. @@ -232173,8 +231066,8 @@ The type of element contained by the array. The array to retrieve items from. - - + + Returns the last element of the array. @@ -232263,8 +231156,8 @@ The type of element contained by the collection. The array to retrieve items from. - - + + Returns the last element of a sequence, or a default value if the sequence contains no elements. @@ -232296,8 +231189,8 @@ The type of element contained by the collection. The array to retrieve an element from. The delegate that defines the conditions of the element to search for. - - + + Returns the last element of a sequence that satisfies a condition or a default value if no such element is found. @@ -232326,8 +231219,8 @@ The type of item in the builder. The builder to retrieve an element from. - - + + Returns the last element in the collection, or the default value if the collection is empty. @@ -232361,8 +231254,8 @@ The type of the result element. The immutable array to select items from. A transform function to apply to each element. - - + + Projects each element of a sequence into a new form. @@ -232438,8 +231331,8 @@ The array to use for comparison. The items to use for comparison. The comparer to use to check for equality. - - + + Determines whether two sequences are equal according to an equality comparer. @@ -232478,8 +231371,8 @@ The array to use for comparison. The items to use for comparison. The comparer to use to check for equality. - - + + Determines whether two sequences are equal according to an equality comparer. @@ -232519,8 +231412,8 @@ The array to use for comparison. The items to use for comparison. The comparer to use to check for equality. - - + + Determines whether two sequences are equal according to an equality comparer. @@ -232550,8 +231443,8 @@ The type of element contained by the collection. The array to retrieve the element from. - - + + Returns the only element of a sequence, and throws an exception if there is not exactly one element in the sequence. @@ -232583,8 +231476,8 @@ The type of element contained by the collection. To be added. To be added. - - + + Returns the only element of a sequence that satisfies a specified condition, and throws an exception if more than one such element exists. @@ -232614,8 +231507,8 @@ The type of element contained by the collection. The array. - - + + Returns the only element of the array, or a default value if the sequence is empty; this method throws an exception if there is more than one element in the sequence. @@ -232647,8 +231540,8 @@ The type of element contained by the collection. The array to get the element from. The condition the element must satisfy. - - + + Returns the only element of a sequence that satisfies a specified condition or a default value if no such element exists; this method throws an exception if more than one element satisfies the condition. @@ -232678,8 +231571,8 @@ The type of element contained by the collection. To be added. - - + + Copies the contents of this array to a mutable array. @@ -232713,8 +231606,8 @@ The type of element contained by the collection. The array to create a dictionary from. The key selector. - - + + Creates a dictionary based on the contents of this array. @@ -232750,8 +231643,8 @@ The array to create a dictionary from. The key selector. The comparer to initialize the dictionary with. - - + + Creates a dictionary based on the contents of this array. @@ -232789,8 +231682,8 @@ The array to create a dictionary from. The key selector. The element selector. - - + + Creates a dictionary based on the contents of this array. @@ -232830,8 +231723,8 @@ The key selector. The element selector. The comparer to initialize the dictionary with. - - + + Creates a dictionary based on the contents of this array. @@ -232863,8 +231756,8 @@ The type of element contained by the collection. The array to filter. The condition to use for filtering the array content. - - + + Filters a sequence of values based on a predicate.