Korzystanie z autonomicznego modułu zbierającego IntelliTrace (C#, Visual Basic)

Artykuł
10/14/2023

Autonomiczny moduł zbierający IntelliTrace umożliwia zbieranie danych diagnostycznych IntelliTrace dla aplikacji na serwerach produkcyjnych lub innych środowiskach bez instalowania programu Visual Studio na maszynie docelowej i bez zmieniania środowiska systemu docelowego. Autonomiczny moduł zbierający IntelliTrace działa w aplikacjach internetowych, SharePoint, WPF i Windows Forms. Po zakończeniu zbierania danych wystarczy usunąć moduł zbierający, aby go odinstalować.

Uwaga

Aby uzyskać zalecane podejścia do diagnozowania problemów na serwerach produkcyjnych, zobacz Diagnozowanie problemów po wdrożeniu.

Wymagania

.NET Framework 3.5 lub nowszy
Program Visual Studio Enterprise (ale nie wersje Professional lub Community) na komputerze programistycznym lub innym komputerze w celu otwarcia plików iTrace

Uwaga

Pamiętaj, aby zapisać pliki symbolu (pdb). Aby debugować za pomocą funkcji IntelliTrace i przejść przez kod, musisz mieć pasujące pliki źródłowe i pliki symboli. Zobacz Diagnozowanie problemów po wdrożeniu.

Często zadawane pytania
Jakie aplikacje działają z modułem zbierającym?
Jak mogę rozpocząć?
Jak mogę uzyskać najwięcej danych bez spowalniania aplikacji?
Gdzie jeszcze mogę uzyskać dane IntelliTrace?

Jakie aplikacje działają z modułem zbierającym?

ASP.NET aplikacje internetowe hostowane w usługach Internet Information Services (IIS) w wersji 7.0, 7.5, 8.0, 12.0 i 16.0
Aplikacje sharePoint 2010 i SharePoint 2013
Aplikacje Windows Presentation Foundation (WPF) i Windows Forms.

Jak mogę zacząć?

Instalowanie modułu zbierającego
Konfigurowanie uprawnień dla katalogu modułu zbierającego
Instalowanie poleceń cmdlet programu PowerShell IntelliTrace w celu zbierania danych dla aplikacji internetowych lub aplikacji programu SharePoint
Konfigurowanie uprawnień dla katalogu plików iTrace
Zbieranie danych z aplikacji internetowej lub aplikacji programu SharePoint

— lub —

Zbieranie danych z aplikacji zarządzanej
Otwórz plik iTrace w programie Visual Studio Enterprise

Instalowanie modułu zbierającego

Na serwerze aplikacji utwórz katalog modułu zbierającego, na przykład: C:\IntelliTraceCollector
Pobierz moduł zbierający z folderu instalacyjnego programu Visual Studio.
1. Skopiuj plik IntelliTraceCollection.cab z folderu, w którym zainstalowano moduł zbierający, na przykład:
  
  .. \Microsoft Visual Studio\2022\Enterprise\Common7\IDE\CommonExtensions\Microsoft\IntelliTrace
  
  lub w przypadku poprzednich wersji programu Visual Studio:
  
  .. \Microsoft Visual Studio 12.0\Common7\IDE\CommonExtensions\Microsoft\IntelliTrace\12.0.0
2. Umieść plik IntelliTraceCollection.cab w katalogu modułu zbierającego, na przykład: C:\IntelliTraceCollector
Rozwiń węzeł IntelliTraceCollection.cab:
1. Na serwerze aplikacji otwórz okno wiersza polecenia jako administrator.
2. Przejdź do katalogu modułu zbierającego, na przykład: C:\IntelliTraceCollector
3. Użyj polecenia expand, w tym kropki (.) na końcu, aby rozwinąć plik IntelliTraceCollection.cab:
  
  expand /f:* IntelliTraceCollection.cab .
  
  Uwaga
  
  Okres (.) zachowuje podfoldery zawierające zlokalizowane plany kolekcji.

Konfigurowanie uprawnień dla katalogu modułu zbierającego

Na serwerze aplikacji otwórz okno wiersza polecenia jako administrator.
Użyj polecenia icacls systemu Windows, aby przyznać administratorowi serwera pełne uprawnienia do katalogu modułu zbierającego. Na przykład:

icacls "C:\IntelliTraceCollector" /grant "<Domain\Administracja istratorID>":F
Aby zbierać dane dla aplikacji internetowej lub aplikacji programu SharePoint:
1. Nadaj osobie, która uruchomi polecenia cmdlet programu PowerShell IntelliTrace pełne uprawnienia do katalogu modułu zbierającego.
  
  Na przykład:
  
  icacls "C:\IntelliTraceCollector" /grant "<Domain\UserID>":F
2. Nadaj puli aplikacji dla aplikacji internetowej lub aplikacji programu SharePoint uprawnienia do odczytu i wykonywania w katalogu modułu zbierającego.
  
  Na przykład:
  - W przypadku aplikacji internetowej w puli aplikacji DefaultAppPool :
    
    icacls "C:\IntelliTraceCollector" /grant "IIS APPPOOL\DefaultAppPool":RX
  - W przypadku aplikacji programu SharePoint w puli aplikacji SharePoint — 80 :
    
    icacls "C:\IntelliTraceCollector" /grant "IIS APPPOOL\SharePoint - 80":RX

Instalowanie poleceń cmdlet programu PowerShell IntelliTrace w celu zbierania danych dla aplikacji internetowych lub aplikacji programu SharePoint

Na serwerze aplikacji upewnij się, że program PowerShell jest włączony. W większości wersji systemu Windows Server można dodać tę funkcję w narzędziu administracyjnym Menedżer serwera.
Zainstaluj polecenia cmdlet programu PowerShell IntelliTrace.
1. Otwórz okno polecenia programu PowerShell jako administrator.
  1. Wybierz pozycję Start, Wszystkie programy, Akcesoria, Windows PowerShell.
  2. Wybierz jedną z następujących czynności:
    - W 64-bitowych systemach operacyjnych otwórz menu skrótów dla programu Windows PowerShell. Wybierz pozycję Uruchom jako administrator.
    - W 32-bitowych systemach operacyjnych otwórz menu skrótów dla programu Windows PowerShell (x86). Wybierz pozycję Uruchom jako administrator.
2. W oknie polecenia programu PowerShell użyj polecenia Import-Module , aby zaimportować plik Microsoft.VisualStudio.IntelliTrace.PowerShell.dll.
  
  Na przykład:
  
  Import-Module "C:\IntelliTraceCollector\Microsoft.VisualStudio.IntelliTrace.PowerShell.dll"

Konfigurowanie uprawnień dla katalogu plików iTrace

Na serwerze aplikacji utwórz katalog plików iTrace, na przykład: C:\IntelliTraceLogFiles
Uwaga
- Aby uniknąć spowolnienia aplikacji, wybierz lokalizację na lokalnym dysku o dużej szybkości, który nie jest bardzo aktywny.
  - Możesz umieścić pliki iTrace i pliki modułu zbierającego w tym samym miejscu. Jeśli jednak masz aplikację internetową lub aplikację programu SharePoint, upewnij się, że to miejsce znajduje się poza katalogiem hostujący aplikację.
Ważne
- Ogranicz katalog plików iTrace tylko do tych tożsamości, które muszą współpracować z modułem zbierającym. Plik iTrace może zawierać poufne informacje, takie jak dane użytkowników, bazy danych, inne lokalizacje źródłowe i parametry połączenia, ponieważ funkcja IntelliTrace może rejestrować dowolne dane przekazywane do parametrów metody lub jako wartości zwracane.
  - Upewnij się, że osoby, które mogą otwierać pliki iTrace, mają uprawnienia do wyświetlania poufnych danych. Zachowaj ostrożność podczas udostępniania plików iTrace. Jeśli inne osoby muszą mieć dostęp, skopiuj pliki do bezpiecznej lokalizacji udostępnionej.
W przypadku aplikacji internetowej lub aplikacji programu SharePoint nadaj jej puli aplikacji pełne uprawnienia do katalogu plików iTrace. Możesz użyć polecenia icacls systemu Windows lub użyć Eksploratora Windows (lub Eksplorator plików).

Na przykład:
- Aby skonfigurować uprawnienia za pomocą polecenia icacls systemu Windows:
  - W przypadku aplikacji internetowej w puli aplikacji DefaultAppPool :
    
    icacls "C:\IntelliTraceLogFiles" /grant "IIS APPPOOL\DefaultAppPool":F
  - W przypadku aplikacji programu SharePoint w puli aplikacji SharePoint — 80 :
    
    icacls "C:\IntelliTraceLogFiles" /grant "IIS APPPOOL\SharePoint - 80":F
    
    — lub —
- Aby skonfigurować uprawnienia za pomocą Eksploratora Windows (lub Eksplorator plików):
  1. Otwórz polecenie Właściwości dla katalogu plików iTrace.
  2. Na karcie Zabezpieczenia wybierz pozycję Edytuj, Dodaj.
  3. Upewnij się, że wbudowane podmioty zabezpieczeń są wyświetlane w polu Wybierz ten typ obiektu. Jeśli nie ma go, wybierz pozycję Typy obiektów, aby je dodać.
  4. Upewnij się, że komputer lokalny jest wyświetlany w polu Z tej lokalizacji . Jeśli tak nie jest, wybierz pozycję Lokalizacje , aby ją zmienić.
  5. W polu Wprowadź nazwy obiektów do wybrania dodaj pulę aplikacji dla aplikacji internetowej lub aplikacji programu SharePoint.
  6. Wybierz pozycję Sprawdź nazwy , aby rozpoznać nazwę. Wybierz pozycję OK.
  7. Upewnij się, że pula aplikacji ma pełną kontrolę.

Zbieranie danych z aplikacji internetowej lub aplikacji programu SharePoint

Aby rozpocząć zbieranie danych, otwórz okno polecenia programu PowerShell jako administrator, a następnie uruchom następujące polecenie:

Start-IntelliTraceCollection"<ApplicationPool><"PathToCollectionPlan><FullPathToITraceFileDirectory>

Ważne

Po uruchomieniu tego polecenia wpisz Y , aby potwierdzić, że chcesz rozpocząć zbieranie danych.

Na przykład w celu zbierania danych z aplikacji programu SharePoint w puli aplikacji SharePoint — 80 :

Start-IntelliTraceCollection "SharePoint - 80" "C:\IntelliTraceCollector\collection_plan.ASP.NET.default.xml" "C:\IntelliTraceLogFiles"

Nazwa/nazwisko	opis
Pula aplikacji	Nazwa puli aplikacji, w której działa aplikacja
PathToCollectionPlan	Ścieżka do planu kolekcji , pliku XML, który konfiguruje ustawienia modułu zbierającego. Możesz określić plan dostarczany z modułem zbierającym. Następujące plany działają w przypadku aplikacji internetowych i aplikacji programu SharePoint: - collection_plan. ASP. NET.default.xml Zbiera tylko zdarzenia IntelliTrace i zdarzenia programu SharePoint, w tym wyjątki, wywołania bazy danych i żądania serwera sieci Web. - collection_plan. ASP. NET.trace.xml Zbiera wywołania funkcji i wszystkie dane w collection_plan. ASP. NET.default.xml. Ten plan jest odpowiedni do szczegółowej analizy, ale może spowolnić działanie aplikacji więcej niż collection_plan. ASP. NET.default.xml. Aby uniknąć spowolnienia aplikacji, dostosuj te plany lub utwórz własny plan. W przypadku zabezpieczeń należy umieścić wszystkie plany niestandardowe w tej samej bezpiecznej lokalizacji co pliki modułu zbierającego. Zobacz Tworzenie i dostosowywanie planów kolekcji IntelliTrace i Jak mogę uzyskać najwięcej danych bez spowalniania aplikacji?Uwaga: domyślnie maksymalny rozmiar pliku iTrace wynosi 100 MB. Gdy plik iTrace osiągnie ten limit, moduł zbierający usunie najwcześniejsze wpisy pliku, aby zwolnić miejsce dla nowszych wpisów. Aby zmienić ten limit, edytuj atrybut planu `MaximumLogFileSize` kolekcji. Gdzie można znaleźć zlokalizowane wersje tych planów kolekcji? Zlokalizowane plany można znaleźć w podfolderach modułu zbierającego.
FullPathToITraceFileDirectory	Pełna ścieżka do katalogu plików iTrace. Uwaga dotycząca zabezpieczeń: podaj pełną ścieżkę, a nie ścieżkę względną.

Moduł zbierający dołącza do puli aplikacji i rozpoczyna zbieranie danych.

Czy mogę otworzyć plik iTrace w tej chwili? Nie, plik jest zablokowany podczas zbierania danych.

Odtwórz problem.
Aby utworzyć punkt kontrolny pliku iTrace, użyj następującej składni:

Checkpoint-IntelliTraceCollection"<Pula aplikacji>"
Aby sprawdzić stan kolekcji, użyj następującej składni:

Get-IntelliTraceCollectionStatus
Aby zatrzymać zbieranie danych, użyj następującej składni:

Stop-IntelliTraceCollection"<Pula aplikacji>"

Ważne

Po uruchomieniu tego polecenia wpisz Y , aby potwierdzić, że chcesz zatrzymać zbieranie danych. W przeciwnym razie moduł zbierający może kontynuować zbieranie danych, plik iTrace pozostanie zablokowany lub plik może nie zawierać żadnych przydatnych danych.
Otwórz plik iTrace w programie Visual Studio Enterprise

Zbieranie danych z aplikacji zarządzanej

Aby uruchomić aplikację i zebrać dane w tym samym czasie, użyj następującej składni:

<FullPathToIntelliTraceCollectorExecutable><\IntelliTraceSC.exe launch /cp:PathToCollectionPlan></f:FullPathToITraceFileDirectoryAndFileName><PathToAppExecutableFileAndFileName>

Aby na przykład zbierać dane z aplikacji o nazwie MyApp:

C:IntelliTraceCollectorIntelliTraceSC.exe launch /cp:"C:IntelliTraceCollectorcollection_plan.ASP.NET.default.xml" /f:"C:IntelliTraceLogFilesMyApp.itrace" "C:MyAppMyApp.exe"

Nazwa/nazwisko	opis
FullPathToIntelliTraceCollectorExecutable	Pełna ścieżka do pliku wykonywalnego modułu zbierającego IntelliTraceSC.exe
PathToCollectionPlan	Ścieżka do planu kolekcji , pliku XML, który konfiguruje ustawienia modułu zbierającego. Możesz określić plan dostarczany z modułem zbierającym. Następujące plany działają w przypadku aplikacji zarządzanych: - collection_plan. ASP. NET.default.xml Zbiera tylko zdarzenia IntelliTrace, w tym wyjątki, wywołania bazy danych i żądania serwera sieci Web. - collection_plan. ASP. NET.trace.xml Zbiera wywołania funkcji i wszystkie dane w collection_plan. ASP. NET.default.xml. Ten plan jest odpowiedni do szczegółowej analizy, ale może spowolnić działanie aplikacji więcej niż collection_plan. ASP. NET.default.xml. Aby uniknąć spowolnienia aplikacji, dostosuj te plany lub utwórz własny plan. W przypadku zabezpieczeń należy umieścić wszystkie plany niestandardowe w tej samej bezpiecznej lokalizacji co pliki modułu zbierającego. Zobacz Tworzenie i dostosowywanie planów kolekcji IntelliTrace i Jak mogę uzyskać najwięcej danych bez spowalniania aplikacji?Uwaga: domyślnie maksymalny rozmiar pliku iTrace wynosi 100 MB. Gdy plik iTrace osiągnie ten limit, moduł zbierający usunie najwcześniejsze wpisy pliku, aby zwolnić miejsce dla nowszych wpisów. Aby zmienić ten limit, edytuj atrybut planu `MaximumLogFileSize` kolekcji. Gdzie można znaleźć zlokalizowane wersje tych planów kolekcji? Zlokalizowane plany można znaleźć w podfolderach modułu zbierającego.
FullPathToITraceFileDirectoryAndFileName	Pełna ścieżka do katalogu plików iTrace i nazwy pliku iTrace z rozszerzeniem itrace . Uwaga dotycząca zabezpieczeń: podaj pełną ścieżkę, a nie ścieżkę względną.
PathToAppExecutableFileAndFileName	Ścieżka i nazwa pliku aplikacji zarządzanej

Zatrzymaj zbieranie danych, zamykając aplikację.
Otwórz plik iTrace w programie Visual Studio Enterprise

Otwórz plik iTrace w programie Visual Studio Enterprise

Uwaga

Aby debugować za pomocą funkcji IntelliTrace i przejść przez kod, musisz mieć pasujące pliki źródłowe i pliki symboli. Zobacz Diagnozowanie problemów po wdrożeniu.

Przenieś plik iTrace lub skopiuj go na komputer za pomocą programu Visual Studio Enterprise (ale nie wersji Professional lub Community).
Kliknij dwukrotnie plik iTrace poza programem Visual Studio lub otwórz plik z poziomu programu Visual Studio.

Program Visual Studio wyświetla stronę Podsumowanie funkcji IntelliTrace. W większości sekcji można przeglądać zdarzenia lub inne elementy, wybierać element i rozpoczynać debugowanie za pomocą funkcji IntelliTrace w momencie, w którym i kiedy wystąpiło zdarzenie. Zobacz Using saved IntelliTrace data (Używanie zapisanych danych IntelliTrace).

Uwaga

Aby debugować za pomocą funkcji IntelliTrace i przejść przez kod, musisz mieć pasujące pliki źródłowe i pliki symboli na komputerze deweloperskim. Zobacz Diagnozowanie problemów po wdrożeniu.

Jak mogę uzyskać najwięcej danych bez spowalniania mojej aplikacji?

Funkcja IntelliTrace może zbierać dużo danych, więc wpływ na wydajność aplikacji zależy od danych zbieranych przez narzędzie IntelliTrace i rodzaju kodu, który analizuje. Zobacz Optymalizowanie kolekcji IntelliTrace na serwerach produkcyjnych.

Poniżej przedstawiono kilka sposobów uzyskiwania większości danych bez spowalniania aplikacji:

Uruchom moduł zbierający tylko wtedy, gdy uważasz, że występuje problem lub kiedy można odtworzyć problem.

Rozpocznij zbieranie, odtwórz problem, a następnie zatrzymaj zbieranie. Otwórz plik iTrace w programie Visual Studio Enterprise i sprawdź dane. Zobacz Otwieranie pliku iTrace w programie Visual Studio Enterprise.
W przypadku aplikacji internetowych i aplikacji programu SharePoint moduł zbierający rejestruje dane dla każdej aplikacji, która współużytkuje określoną pulę aplikacji. Może to spowolnić wszystkie aplikacje, które współudzielą tę samą pulę aplikacji, mimo że można określić tylko moduły dla jednej aplikacji w planie kolekcji.

Aby zapobiec spowolnieniu działania innych aplikacji przez moduł zbierający, hostuj każdą aplikację we własnej puli aplikacji.
Przejrzyj zdarzenia w planie kolekcji, dla którego intelliTrace zbiera dane. Edytuj plan kolekcji, aby wyłączyć zdarzenia, które nie są istotne lub cię nie interesują.

Aby wyłączyć zdarzenie, ustaw enabled atrybut dla <DiagnosticEventSpecification> elementu na false:

<DiagnosticEventSpecification enabled="false">

enabled Jeśli atrybut nie istnieje, zdarzenie jest włączone.

Jak to poprawi wydajność?
- Możesz skrócić czas uruchamiania, wyłączając zdarzenia, które nie są istotne dla aplikacji. Na przykład wyłącz zdarzenia przepływu pracy systemu Windows dla aplikacji, które nie korzystają z przepływu pracy systemu Windows.
- Wydajność uruchamiania i czasu wykonywania można poprawić, wyłączając zdarzenia rejestru dla aplikacji, które uzyskują dostęp do rejestru, ale nie pokazują problemów z ustawieniami rejestru.
Przejrzyj moduły w planie kolekcji, dla których intelliTrace zbiera dane. Edytuj plan kolekcji, aby uwzględnić tylko interesujące Cię moduły:
1. Otwórz plan kolekcji. <ModuleList> Znajdź element .
2. W <ModuleList>pliku isExclusionList ustaw atrybut na false.
3. <Name> Użyj elementu , aby określić każdy moduł z jedną z następujących wartości: nazwa pliku, wartość ciągu w celu uwzględnienia dowolnego modułu, którego nazwa zawiera ten ciąg lub klucz publiczny.
  
  Aby na przykład zbierać dane z głównego modułu sieci Web aplikacji internetowej Fabrikam Fiber, utwórz listę podobną do następującej:
```
<ModuleList isExclusionList="false">
   <Name>FabrikamFiber.Web.dll</Name>
</ModuleList>
```
Aby zebrać dane z dowolnego modułu, którego nazwa zawiera nazwę "Fabrikam", utwórz listę podobną do następującej:
```
<ModuleList isExclusionList="false">
   <Name>Fabrikam</Name>
</ModuleList>
```
Aby zbierać dane z modułów, określając ich tokeny klucza publicznego, utwórz listę podobną do następującej:
```
<ModuleList isExclusionList="false">
   <Name>PublicKeyToken:B77A5C561934E089</Name>
   <Name>PublicKeyToken:B03F5F7F11D50A3A</Name>
   <Name>PublicKeyToken:31BF3856AD364E35</Name>
   <Name>PublicKeyToken:89845DCD8080CC91</Name>
   <Name>PublicKeyToken:71E9BCE111E9429C</Name>
</ModuleList>
```
Jak to poprawi wydajność?

Zmniejsza to ilość informacji o wywołaniu metody i innych danych instrumentacji, które intelliTrace zbiera podczas uruchamiania i uruchamiania aplikacji. Te dane umożliwiają:
- Wykonaj kroki kodu po zebraniu danych.
- Sprawdź wartości przekazane i zwrócone z wywołań funkcji.
  
  Dlaczego zamiast tego nie wykluczać modułów?
  
  Domyślnie plany kolekcji wykluczają moduły, ustawiając isExclusionList atrybut na true. Jednak wykluczenie modułów może spowodować zbieranie danych z modułów, które nie spełniają kryteriów listy i może cię nie zainteresować, takich jak moduły innych firm lub open source.
Czy istnieją jakieś dane, które nie są zbierane przez funkcję IntelliTrace?

Tak, aby zmniejszyć wpływ na wydajność, funkcja IntelliTrace ogranicza zbieranie danych do wartości typów danych pierwotnych przekazywanych do metod i zwracanych z metod oraz do wartości pierwotnych typów danych w polach na obiektach najwyższego poziomu przekazywanych do metod i zwracanych z metod.

Załóżmy na przykład, że masz sygnaturę AlterEmployee metody, która akceptuje liczbę całkowitą id i Employee obiekt oldemployee:

public Employee AlterEmployee(int id, Employee oldemployee)

Typ Employee ma następujące atrybuty: Id, Namei HomeAddress. Istnieje relacja skojarzenia między Employee i typem Address .

Moduł zbierający rejestruje wartości , Employee.IdidEmployee.Name i Employee obiekt zwrócony z AlterEmployee metody . Jednak moduł zbierający nie rejestruje informacji o Address obiekcie innym niż to, czy ma wartość null, czy nie. Moduł zbierający nie rejestruje również danych dotyczących zmiennych lokalnych w AlterEmployee metodzie, chyba że inne metody używają tych zmiennych lokalnych jako parametrów, w którym momencie są rejestrowane jako parametry metody.