Skip to content

Commit 32cc70a

Browse files
gewarrengewarren
committed
add back file that wasn't supposed to be deleted
1 parent 3d9bd4c commit 32cc70a

File tree

1 file changed

+284
-0
lines changed

1 file changed

+284
-0
lines changed

‎docs/test/how-to-create-a-diagnostic-data-adapter.md

Lines changed: 284 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,284 @@
1+
---
2+
title: "How to: Create a Diagnostic Data Adapter in Visual Studio"
3+
ms.date: 10/19/2016
4+
ms.topic: conceptual
5+
helpviewer_keywords:
6+
- "Diagnostic Data Adapter, creating"
7+
ms.assetid: bd7ad36c-54cb-4d2a-9aea-9d10ad98d7ba
8+
author: gewarren
9+
ms.author: gewarren
10+
manager: douge
11+
ms.prod: visual-studio-dev15
12+
ms.technology: vs-ide-test
13+
---
14+
# How to: Create a diagnostic data adapter
15+
16+
To create a *diagnostic data adapter*, you create a class library using Visual Studio, and then add the Diagnostic Data Adapter APIs provided by Visual Studio Enterprise to your class library. Send any information that you want as a stream or a file to the <xref:Microsoft.VisualStudio.TestTools.Execution.DataCollectionSink> provided by the framework, when handling the events that are raised during the test run. The streams or files sent to the <xref:Microsoft.VisualStudio.TestTools.Execution.DataCollectionSink> are stored as attachments to the test results when your test finishes. If you create a bug from these test results or when you use [!INCLUDE[mtrlong](../test/includes/mtrlong_md.md)], the files are also linked to the bug.
17+
18+
You can create a diagnostic data adapter that affects the machine where your tests are run, or a machine that is part of the environment you are using to run your application under test. For example, collecting files on your test machine where the tests are run, or collecting files on the machine serving in the web server role for your application.
19+
20+
You can give your diagnostic data adapter a friendly name that displays when you create your test settings using Microsoft Test Manager or using Visual Studio. Test settings enable you to define which machine role will run specific diagnostic data adapters in your environment when you run your tests. You can also configure your diagnostic data adapters when you create your test settings. For example, you may create a diagnostic data adapter that collects custom logs from your web server. When you create your test settings, you can select to run this diagnostic data adapter on the machine or machines that are performing this web server role and you can modify the configuration for your test settings to collect only the last three logs that were created. For more information about test settings, see [Collect diagnostic information using test settings](../test/collect-diagnostic-information-using-test-settings.md).
21+
22+
Events are raised when you run your tests so that your diagnostic data adapter can perform tasks at that point in the test.
23+
24+
> [!IMPORTANT]
25+
> These events may be raised on different threads, especially when you have tests running on multiple machines. Therefore, you must be aware of possible threading issues and not inadvertently corrupt the internal data of the custom adapter. Make sure your diagnostic data adapter is thread safe.
26+
27+
The following is a partial list of key events that you can use when you create your diagnostic data adapter. For a complete list of diagnostic data adapter events, see the abstract <xref:Microsoft.VisualStudio.TestTools.Execution.DataCollectionEvents> class.
28+
29+
|Event|Description|
30+
|-|-----------------|
31+
|<xref:Microsoft.VisualStudio.TestTools.Execution.DataCollectionEvents.SessionStart>|Start of your test run|
32+
|<xref:Microsoft.VisualStudio.TestTools.Execution.DataCollectionEvents.SessionEnd>|End of your test run|
33+
|<xref:Microsoft.VisualStudio.TestTools.Execution.DataCollectionEvents.TestCaseStart>|Start of each test in the test run|
34+
|<xref:Microsoft.VisualStudio.TestTools.Execution.DataCollectionEvents.TestCaseEnd>|End of each test in the test run|
35+
|<xref:Microsoft.VisualStudio.TestTools.Execution.DataCollectionEvents.TestStepStart>|Start of each test step in a test|
36+
|<xref:Microsoft.VisualStudio.TestTools.Execution.DataCollectionEvents.TestStepEnd>|End of each test step in a test|
37+
38+
> [!NOTE]
39+
> When a manual test is completed, no more data collection events are sent to the diagnostic data adapter. When a test is rerun, it will have a new test case identifier. If a user resets a test during a test (which raises the <xref:Microsoft.VisualStudio.TestTools.Execution.DataCollectionEvents.TestCaseReset> event), or changes a test step outcome, no data collection event is sent to the diagnostic data adapter, but the test case identifier remains the same. To determine whether a test case has been reset, you must track the test case identifier in your diagnostic data adapter.
40+
41+
Use the following procedure to create diagnostic data adapter that collects a data file that is based on information that you configure when you create your test settings.
42+
43+
For a complete example diagnostic data adapter project, including a custom configuration editor, see [Sample project for creating a diagnostic data adapter](../test/sample-project-for-creating-a-diagnostic-data-adapter.md).
44+
45+
## Create and install a diagnostic data adapter
46+
47+
### To create and install a diagnostic data adapter
48+
49+
1. Create a new class library.
50+
51+
1. On the **File** menu, choose **New**, and then point to **New Project**.
52+
53+
2. From **Project types**, select the language to use.
54+
55+
3. From **Visual Studio installed templates**, select **Class Library**.
56+
57+
4. Type a name for your Diagnostic Data Adapter.
58+
59+
5. Choose **OK**.
60+
61+
2. Add the assembly **Microsoft.VisualStudio.QualityTools.ExecutionCommon**.
62+
63+
1. In **Solution Explorer**, right-click **References** and choose the **Add Reference** command.
64+
65+
2. Choose **.NET** and locate **Microsoft.VisualStudio.QualityTools.ExecutionCommon.dll**.
66+
67+
3. Choose **OK**.
68+
69+
3. Add the assembly **Microsoft.VisualStudio.QualityTools.Common**.
70+
71+
1. In **Solution Explorer**, right-click **References** and select the **Add Reference** command.
72+
73+
2. Choose **/.NET**, locate **Microsoft.VisualStudio.QualityTools.Common.dll**.
74+
75+
3. Choose **OK**.
76+
77+
4. Add the following `using` statements to your class file:
78+
79+
```csharp
80+
using Microsoft.VisualStudio.TestTools.Common;
81+
using Microsoft.VisualStudio.TestTools.Execution;
82+
using System.Linq;
83+
using System.Text;
84+
using System.Xml;
85+
using System;
86+
```
87+
88+
5. Add the <xref:Microsoft.VisualStudio.TestTools.Execution.DataCollectorTypeUriAttribute> to the class for your diagnostic data adapter to identify it as a diagnostic data adapter, replacing **Company**, **Product**, and **Version** with the appropriate information for your Diagnostic Data Adapter:
89+
90+
```csharp
91+
[DataCollectorTypeUri("datacollector://Company/Product/Version")]
92+
```
93+
94+
6. Add the <xref:Microsoft.VisualStudio.TestTools.Execution.DataCollectorFriendlyNameAttribute> attribute to the class, replacing the parameters with the appropriate information for your Diagnostic Data Adapter:
95+
96+
```csharp
97+
[DataCollectorFriendlyName("Collect Log Files", false)]
98+
```
99+
100+
This friendly name is displayed in the test settings activity.
101+
102+
> [!NOTE]
103+
> You can also add the <xref:Microsoft.VisualStudio.TestTools.Execution.DataCollectorConfigurationEditorAttribute> to specify the `Type` of your custom configuration editor for this data adapter, and to optionally specify the help file to use for the editor.
104+
>
105+
> You can also apply the <xref:Microsoft.VisualStudio.TestTools.Execution.DataCollectorEnabledByDefaultAttribute> to specify that it should always be enabled.
106+
107+
7. Your diagnostic data adapter class must inherit from the <xref:Microsoft.VisualStudio.TestTools.Execution.DataCollector> class as follows:
108+
109+
```csharp
110+
public class MyDiagnosticDataAdapter : DataCollector
111+
```
112+
113+
8. Add the local variables as follows:
114+
115+
```csharp
116+
private DataCollectionEvents dataEvents;
117+
private DataCollectionLogger dataLogger;
118+
private DataCollectionSink dataSink;
119+
private XmlElement configurationSettings;
120+
```
121+
122+
9. Add the <xref:Microsoft.VisualStudio.TestTools.Execution.DataCollector.Initialize*> method and a **Dispose** method. In the `Initialize` method, you initialize the data sink, any configuration data from test settings, and register the event handlers you want to use as follows:
123+
124+
```csharp
125+
public override void Initialize(
126+
XmlElement configurationElement,
127+
DataCollectionEvents events,
128+
DataCollectionSink sink,
129+
DataCollectionLogger logger,
130+
DataCollectionEnvironmentContext environmentContext)
131+
{
132+
dataEvents = events; // The test events
133+
dataLogger = logger; // The error and warning log
134+
dataSink = sink; // Saves collected data
135+
// Configuration from the test settings
136+
configurationSettings = configurationElement;
137+
138+
// Register common events for the data collector
139+
// Not all of the events are used in this class
140+
dataEvents.SessionStart +=
141+
new EventHandler<SessionStartEventArgs>(OnSessionStart);
142+
dataEvents.SessionEnd +=
143+
new EventHandler<SessionEndEventArgs>(OnSessionEnd);
144+
dataEvents.TestCaseStart +=
145+
new EventHandler<TestCaseStartEventArgs>(OnTestCaseStart);
146+
dataEvents.TestCaseEnd +=
147+
new EventHandler<TestCaseEndEventArgs>(OnTestCaseEnd);
148+
}
149+
150+
public override void Dispose(bool disposing)
151+
{
152+
if (disposing)
153+
{
154+
// Unregister the registered events
155+
dataEvents.SessionStart -=
156+
new EventHandler<SessionStartEventArgs>(OnSessionStart);
157+
dataEvents.SessionEnd -=
158+
new EventHandler<SessionEndEventArgs>(OnSessionEnd);
159+
dataEvents.TestCaseStart -=
160+
new EventHandler<TestCaseStartEventArgs>(OnTestCaseStart);
161+
dataEvents.TestCaseEnd -=
162+
new EventHandler<TestCaseEndEventArgs>(OnTestCaseEnd);
163+
}
164+
}
165+
```
166+
167+
10. Use the following event handler code and private method to collect the log file generated during the test:
168+
169+
```csharp
170+
public void OnTestCaseEnd(sender, TestCaseEndEventArgs e)
171+
{
172+
// Get any files to be collected that are
173+
// configured in your test settings
174+
List<string> files = getFilesToCollect();
175+
176+
// For each of the files, send the file to the data sink
177+
// which will attach it to the test results or to a bug
178+
foreach (string file in files)
179+
{
180+
dataSink.SendFileAsync(e.Context, file, false);
181+
}
182+
}
183+
184+
// A private method that returns the file names
185+
private List<string> getFilesToCollect()
186+
{
187+
// Get a namespace manager with our namespace
188+
XmlNamespaceManager nsmgr =
189+
new XmlNamespaceManager(
190+
configurationSettings.OwnerDocument.NameTable);
191+
nsmgr.AddNamespace("ns",
192+
"http://MyCompany/schemas/MyDataCollector/1.0");
193+
194+
// Find all of the "File" elements under our configuration
195+
XmlNodeList files =
196+
configurationSettings.SelectNodes(
197+
"//ns:MyDataCollector/ns:File");
198+
199+
// Build the list of files to collect from the
200+
// "FullPath" attributes of the "File" nodes.
201+
List<string> result = new List<string>();
202+
foreach (XmlNode fileNode in files)
203+
{
204+
XmlAttribute pathAttribute =
205+
fileNode.Attributes["FullPath"];
206+
if (pathAttribute != null &&
207+
!String.IsNullOrEmpty(pathAttribute.Value))
208+
{
209+
result.Add(pathAttribute.Value);
210+
}
211+
}
212+
213+
return result;
214+
}
215+
```
216+
217+
These files are attached to the test results. If you create a bug from these test results or when you use [!INCLUDE[mtrlong](../test/includes/mtrlong_md.md)], the files are also attached to the bug.
218+
219+
If you want to use your own editor to collect data to use in your test settings, see [How to: Create a custom editor for data for your diagnostic data adapter](../test/how-to-create-a-custom-editor-for-data-for-your-diagnostic-data-adapter.md).
220+
221+
11. To collect a log file when a test finishes based on what the user configured in test settings, you must create an *App.config* file and add it to your solution. This file has the following format and must contain the URI for your diagnostic data adapter to identify it. Substitute real values for the "Company/ProductName/Version".
222+
223+
> [!NOTE]
224+
> If you do not need to configure any information for your diagnostic data adapter, then you do not need to create a configuration file.
225+
226+
```xml
227+
<?xml version="1.0" encoding="utf-8"?>
228+
<configuration>
229+
<configSections>
230+
<section name="DataCollectorConfiguration" type="Microsoft.VisualStudio.TestTools.Execution.DataCollectorConfigurationSection, Microsoft.VisualStudio.QualityTools.ExecutionCommon, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a "/>
231+
</configSections>
232+
<DataCollectorConfiguration xmlns="http://microsoft.com/schemas/VisualStudio/TeamTest/2010">
233+
<DataCollector typeUri="datacollector://MyCompany/MyProduct/1.0">
234+
<DefaultConfiguration>
235+
<!-- Your default config settings -->
236+
<Binaries>
237+
<Binary FullPath="C:\Example\Example.dll"/>
238+
<Binary FullPath="\\Server2\Example2.dll"/>
239+
</Binaries>
240+
<Symbols>
241+
<Symbol FullPath="\\ExampleServer\ExampleSymbol.pdb"/>
242+
</Symbols>
243+
</DefaultConfiguration>
244+
</DataCollector>
245+
</DataCollectorConfiguration>
246+
</configuration>
247+
```
248+
249+
> [!NOTE]
250+
> The default configuration element can contain any data that you require. If the user does not configure the diagnostic data adapter in test settings, then the default data will be passed to your diagnostic data adapter when it is executed. Because the XML you add to the `<DefaultConfigurations>` section is not likely to be part of the declared schema, you can ignore any XML errors it generates.
251+
>
252+
> There are other examples of configuration files in the following path based on your installation directory: *Program Files\Microsoft Visual Studio 10.0\Common7\IDE\PrivateAssemblies\DataCollectors*.
253+
254+
For more information about how to configure your test settings to use an environment when you run your tests, see [Collect diagnostic data in manual tests (Azure Test Plans)](/azure/devops/test/mtm/collect-more-diagnostic-data-in-manual-tests?view=vsts).
255+
256+
For more information about installing the configuration file, see [How to: Install a custom diagnostic data adapter](../test/how-to-install-a-custom-diagnostic-data-adapter.md)
257+
258+
12. Build your solution to create your diagnostic data adapter assembly.
259+
260+
13. For information about installing your custom editor, see [How to: Install a custom diagnostic data adapter](../test/how-to-install-a-custom-diagnostic-data-adapter.md).
261+
262+
14. For more information about how to configure your test settings to use an environment when you run your tests, see [Collect diagnostic data in manual tests (Azure Test Plans)](/azure/devops/test/mtm/collect-more-diagnostic-data-in-manual-tests?view=vsts).
263+
264+
15. To select your diagnostic data adapter, you must first select an existing test settings or create a new one from Microsoft Test Manager or Visual Studio. The adapter is displayed on the **Data and Diagnostics** tab of your test settings with the friendly name that you assigned to the class.
265+
266+
16. Set these test settings to be active. For more information about test settings, see [Collect diagnostic information using test settings](../test/collect-diagnostic-information-using-test-settings.md).
267+
268+
17. Run your tests using the test settings with your diagnostic data adapter selected.
269+
270+
The data file that you specified is attached to your test results.
271+
272+
## See also
273+
274+
- <xref:Microsoft.VisualStudio.TestTools.Execution.DataCollectorConfigurationEditorAttribute>
275+
- <xref:Microsoft.VisualStudio.TestTools.Execution.DataCollectionEvents>
276+
- <xref:Microsoft.VisualStudio.TestTools.Execution.DataCollector>
277+
- <xref:Microsoft.VisualStudio.TestTools.Execution.DataCollectionSink>
278+
- <xref:Microsoft.VisualStudio.TestTools.Execution.DataCollectorTypeUriAttribute>
279+
- <xref:Microsoft.VisualStudio.TestTools.Execution.DataCollectorFriendlyNameAttribute>
280+
- <xref:Microsoft.VisualStudio.TestTools.Execution.DataCollectorEnabledByDefaultAttribute>
281+
- [Collect diagnostic information using test settings](../test/collect-diagnostic-information-using-test-settings.md)
282+
- [Collect diagnostic data in manual tests (Azure Test Plans)](/azure/devops/test/mtm/collect-more-diagnostic-data-in-manual-tests?view=vsts)
283+
- [Collect diagnostic data while testing (Azure Test Plans)](/azure/devops/test/collect-diagnostic-data?view=vsts)
284+
- [How to: Create a custom editor for data for your diagnostic data adapter](../test/how-to-create-a-custom-editor-for-data-for-your-diagnostic-data-adapter.md)

0 commit comments

Comments
 (0)