MS SQL에서 연결 Timeout을 설정할 수 있다.

설정 방법은 SQL ConnectionString을 수정하면 된다.

Data Source=DBServer;Initial Catalog=DBName;User ID=userid;Password=Password;Connect Timeout=30

대부분의 경우 위의 Connect Timeout의 값이 설정되지 않으면 기본값으로 15(초)로 설정된다.

그런데, 최소 값은 반드시 4을 초과해야 한다.

만일 1, 2, 3, 4 중의 숫자로 입력하는 경우에는 약 28초 이상을 Timeout으로 갖게 된다.

Connection이 되는지 여부를 판단 하기 위해서 Connection을 수행하는데, 이 Timeout을 3이하로 하니까 원하는 결과를 제대로 얻지를 못했다. 그래서 확인해보니 5 보다 작은 숫자를 넣으면 최소값으로 인정받지 못하고 무시되는 형태로 보인다. ( Connection Pool의 상황에 따라 1~2초 차이는 있다. 간혹 3초에서 되기도 하고 4초에서 되기도 한다.)

그러므로 최소값으로 설정하고 싶으면 5 이상의 값을 넣어야 된다.

Data Source=DBServer;Initial Catalog=DBName;User ID=userid;Password=Password;Connect Timeout=5

Windows 기반에 SVN 서버가 동작할 때, Hook 설정이다.

특히 SVN에서 Commit Action에 Jenkins를 연결할 때 사용하는 방법이다.

1. hook 폴더로 이동.

2. post-commit.bat 파일 작성

3. post-commit.bat 파일 내에 아래와 같이 작성

powershell -Command (New-Object System.Net.WebClient).DownloadString(\"http:///job//build?delay=0sec\");

4. 저장 후 Commit.

만일 인증 토큰을 이용하는 경우에는 URL 부분을 좀 손을 봐야 한다.

powershell -Command (New-Object System.Net.WebClient).DownloadString(\"http://:@/job//build?token=&delay=0sec\");

Linux인 경우에는 CUrl 이라는 명령으로 처리한다.

대략적으로 만들어야 하는 제품을 기준으로 각 구성요소들을 단순 무식하게 계산하여 약 400 M/M 사이즈 프로젝트가 있다고 하자.

1인당 1달 유지비를 1천만원(유지비에는 월급, 행정 처리, 프로젝트 진행 잡비 등등)으로 잡는다고 했을 때, 이 프로젝트는 최소한 40억은 있어야 한다. 그 외에는 별개로 이익 5% 까지 계산하면, 42억 정도 잡힌다.

24개월 기준으로 보면 최소 16명이 있어야 되며, 16명이 24개월 정도 업무를 수행해야 한다. 그런데, 이 M/M에는 함정이 있다. 바로 인력의 개개별의 능력이나 속도 그 외 업무에 대한 이해도 따위는 전혀 없다.

다행히 1~2명은 사업에 대한 이해나, 관련 기술의 이해가 있다고 치다.

문제는 주변인이다. 많게 쳐서 4명이 잘 안다고 해도, 16 명 중 4명 빼면 12명이 있는데, 이 사람들은 이 사업에 대한 이해에서 부터 기술이 전무하다고 하면 아주 진행이 웃기게 된다.

자.. 이것이 한국형 계산법이다.

그런데 한국에서는 저 40억이라고 하면 무척 많은 금액이라고 한다. 그러니 자연스럽게 400 M/M이 걸리는 작업을 마구 후려쳐서 200 M/M으로 계산한다. 즉 40억을 20억으로 줄인다. 상도덕 적으로 40억을 20억으로 줄였으니 전체적인 업무를 줄여야 하는데, 또 그렇지가 않다. 즉 400 M/M짜리를 금액만 200M/M 으로 줄이게 된다.

이와 같은 형태가 되면 어떻게 될까? 그나마 16명으로 어떻게든 유지해보려는 프로젝트는 8명이 해야 되고, 일은 2배가 된다. 인력이 마구 투입된다고 자연스럽게 흘러가지도 않겠지만, 그렇다고 무턱대고 줄이면, 그 나머지 업무를 결국 개개인에게 쏠리게 된다.

이게 야근의 원리다.

결국 전체적인 프로젝트의 퀄리티는 저하될 수 밖에 없고, 개발자는 자연스럽게 허덕이고 야근하고 개발을 하게 된다.

그런데 저 사이즈의 프로젝트가 되게 되면 자연스럽게 개발과는 상관 없는 사업관리 조직이 생긴다. 줄어든 금액에서 또 쪼개 쪼개서 사업관리를 하게 된다. 금액의 절약은 다시 개발자에게 얹어지게 되고, 개발자는 더 많은 일을 할 수 밖에 없는 구조가 계속 진행되게 된다.

이렇게 만들어 놓고 많은 금액을 투입했으니, 넉넉한 기간을 주었으니 잘 만들어 달라고 한다.

?

SVN 기능 중 Svnsync 라는 기능이 있어, 원격에서 서로 다른 레파지토리를 동기화 시킬 수 있다.
물론 양 측의 리비전을 맞추기 위해서는 저장 대상이 되는 위치는 빈 데이터이여야 한다.

그런데 복사해야할 레파지토리가 오래된 경우 데이터가 매우 커서 한번 Sync를 시도하면 세월아 내월하가 될 수 있다. 더욱이 특정 버전에서 파일크기가 크면, http 기반의 svn 서버 중 일부는 에러를 내고 이야기를 진행하지 못하는 경우도 있다.

이 경우에 처리하는 방법은 다음과 같다.

1. svnadmin dump를 이용해서 원본 데이터를 뜬다.

2. 복제 대상에 원본 데이터를 svnadmin load를 이용해서 붇는다.

3. svnsync init 할 때, --allow-non-empty를 넣어 처리한다.

즉 svnsync 초기화 할 때, --allow-non-empty를 하면된다.

그리고 그 뒤는 sync로 연속.

만일 sync 중 오류가 나면, 해당 revision만 dump를 뜨고 다시 대상에서 붇고 sync를 다시해준다.

중요한 것은 쌍방의 버전이 동일하게 진행되어야 한다.

참조글 : https://www.linuxquestions.org/questions/linux-software-2/rtorrent-how-to-make-it-run-in-the-background-596041

보통 리눅스 작업을 하면 SSH와 같은 원격 접속 쉘을 사용한다.

여러가지 명령들을 사용해서 백그라운드로 실행하는데, 만일 백그라운드로 실행시키지 않았을 때, 해당 SSH를 닫으면 프로그램이 같이 종료된다. 그래서 보통 nohup 과 같은 유틸을 이용해서 백그라운드로 실행을 한다.

그런데 Console 기반의 프로그램 중에는 ANSI를 이용해서 예전 도스 프로그램 처럼 사용자와 In/Out 하는 프로그램들이 있다. 그냥 단순하게 백그라운드 실행을 하게 되면, 해당 화면을 다시 불러오지 못하는 경우가 발생하는데, 이 때 사요하는 유틸이 있었다.

screen "실행할 프로그램"

을 하면 프로그램이 실행이 된다.

여기서 키보드로 Ctrl 과 A를 누른뒤 D를 치면 프로그램을 백그라운드로 돌리고 보통 쉘 창으로 빠져나올 수 있다.

만일 다시 화면으로 돌아가고 싶으면..

screen -r 

을 하면 된다.

Ctrl-A + D를 한 뒤에 SSH를 닫고 나중에 다시 로그린 한 뒤, screen -r을 하면 원래대로 복귀.

리눅스는 역시 무궁 무진 한듯.

Windows 10을 쓰다가 보면, 미묘하게 화면이 틀어져 보일 때가 있다.

특히 고해상도의 작은 노트북에 모니터를 확장해서 연결했을 때가 좀 골때린다. 13인치에 QHD(3200 X 1800) 일 때, 글자가 매우 작아 보이기 때문에, 전체 화면을 200% 정도 확대해서 보곤 한다. 하지만, 모니터는 Full-HD 밖에 지원하지 않기 때문에, 그냥 100%로 맞춰서 사용한다.

그랬을 때 느낄 수 있다. 

아래의 사진은 고해상도의 13인치 노트북에서 찍은 이미지다.

아래의 사진은 24인치 Full-HD 화면에서 찍은 사진이다.

딱 봐도 각 픽셀 사이즈 때문에, 전체적인 그림이 뿌옇게 나타난다. (물론 카메라를 한번 거친거라, 실제 보는 화면 보다는 좀 그럴싸하게 나온건 함정...)노트북에서는 세밀하게 잘 나오는게 이상하게 모니터로만 넘어가면 프로그램이 전체적으로 흐릿드릿 나온다. 또 노트북에서 그럴싸하게 나오는 것들 중에는 아예 크기가 커진 상태로 나오기도 한다.(물론 qHD에 대한 대응이 되는 프로그램들은 잘 나온다.)

한가지 덧붙이자면, WinForm 프로그램(Windows UI 제작)을 하다가 보면, 이쁘게 컨트롤을 배치해서 개발했는데, 실제 일반 환경(확대 150%나 200%하지 않고, 순수하게 100%로 쓰는..)에서 갑자기 화면이 엉망진창으로 나올 때가 있다.

가끔은 이럴때 한숨이 나오게 된다. 특히나 노안이 오고 있는데, 노트북의 세밀 조밀한 화면에서 100%는 쓸 수도 없거니와 보고 있으면 피로하기까지 한다. 그렇다고 노트북을 바꿀 수도 없고..

만약 모니터 확장을 쓰고 있는 것이라면, 그리고 화면 확대 100%를 기준으로 WinForm을 개발하거나, 지금같이 자신이 주로 쓰는 프로그램들을 모니터에서 주로 사용하는데 메뉴나 기타 윈도우 화면이 뿌옇게 나온다면 다음과 같은 대응 방법은 있다.

화면 설정 화면에서 자신의 모니터를 Main으로 바꾸면 된다. 
(보통 고해상도 노트북 화면과 Full-HD의 일반 모니터를 보면 설정화면에서 작은 쪽이 모니터임.)

반드시 이 디스플레이를 주 모니터로 만들기로 체크해주어야 한다.

그리고 로그 오프를 한 뒤 다시 로그인을 하면 된다.

그러면 모든 해상도는 모니터를 기준으로 보여주게 된다.

(당연히 단점이 있다. HDPI를 지원하지 않는 프로그램들은 노트북으로 넘어가면 매우 작은 글자로 보여준다 -_-;;;;)

여튼 상황에 맞게 설정하고 구성하면 개발하는데, 이용하는데 나름 도움이 되는 것 같다.

원문 : symhttp.doc

HTTP Symbol Stores and the Symbol Server Proxy

Configuring an HTTP Symbol Store

Requirements:  A computer running Windows Server.  Internet Information Services 6.0 is required, so in the examples below we use Windows Server 2003. 

Configuring the Directories

You need to create or select a directory on the computer to act as the symbol store.  For the sake of example, we will call this c:\symstore. We will also presume that the server computer is named \SymMachineName on the network.  Permissions must be set so that users can access the site.  Add the security groups that will need to access the symbol content over the network.  The amount of security to enable will vary from environment to environment.  For some installations, this group will be “Everyone”.

Setup the permissions for the directory

1. Open the “Windows Explorer”
2. Expand “My Computer”
3. Expand the “C” drive
4. Right-click “c:\symstore” and choose “Sharing and Security”
5. Check the “Share this folder” button
6. Click the “Permissions” button
7. Make sure that the desired security groups have “read” access by adding them under “Group or user names” and checking the appropriate box
8. Click “OK” to exit “Permissions”
9. Click “OK” to exit “Symstore Properties”
   

Normally files are placed in a symbol store with a single tier directory structure in which a single subdirectory exists to store all versions of a certain filename.  Such a tree may look like this 

      c:\symstore\ntdll.dll\

      c:\symstore\ntdll.pdb\

      c:\symstore\kernel32.dll\

      c:\symstore\kernel32.pdb\

However if you are going to store a massive amount of filenames, you may prefer to use the two-tier structure.  To do this, place a file called index2.txt in the root of c:\symstore.  The contents of the file are of no importance.  This would result in a tree that looks like this

      c:\symstore\nt\ntdll.dll\

      c:\symstore\nt\ntdll.pdb\

      c:\symstore\ke\kernel32.dll\

      c:\symstore\ke\kernel32.pdb\

The added layer of directories allows you to use DFS or directory junctions to manage and split up your files.  

Make certain you can view the contents of this directory from other computers on your network.

If you are going to use the Symbol Server Proxy, you can skip the following steps and go to the Configuring IIS section.

1. Use symstore.exe to populate the contents of c:\symstore.  Instructions for this are available in the debugger documentation.  
   

2. Make sure the store works by attempting to debug with it.  Do this by debugging from another computer with a symbol path of srv*\\SymMachineName\symstore.

Configuring IIS

Now you need to configure IIS to serve out the symbols.

Create a Virtual Directory

1. From “Administrative Tools” open “Internet Information Services (IIS) Manager”.
2. Expand “Web Sites”
3. Right-click “Default Web Site” (or other desired site)
4. Select “New Virtual Directory…”
5. Click “Next” on the “Welcome” screen.
6. For the “Alias” enter “Symbols” and click “Next”
7. For the “Path” enter “c:\SymStore” and click “Next”
8. Uncheck “Run scripts” (recommended)
9. Put a check in “Browse” (optional)
10. Click “Next” then “Finish” to complete the wizard.

Configure MIME Types

1. Right-click the “Symbols” virtual directory and choose “Properties”
2. Click the “HTTP Headers” tab.
3. Click the “MIME Types” button.
4. Click “New”
5. For “Extension” enter “*”
6. For “Mime type” enter “application/octet-stream”
7. Click “OK” to exit the “MIME Types” dialog.
8. Click “OK” to exit the “Symbols Properties”

If you want to use Anonymous authentication, then IIS is now ready to serve up files from http://SymMachineName/Symbols.  Test it by restarting the IISAdmin service.  You can do this by running “iisreset.exe” from a command prompt.  Then configure a debugger to get files with the symbol path set to srv**http://SymMachineName/Symbols.  Otherwise, complete the rest of these steps.

It is possible to configure IIS to use “Integrated Windows Authentication” so that clients (windbg.exe for example) can automatically authenticate against IIS without prompting the end-user for credentials. SymSrv.dll on the client, however, does not currently work correctly using Kerberos authentication when connecting to IIS. For this reason it is necessary to remove Kerberos as an option.

Configure the Authentication method

1. From “Administrative Tools” open “Internet Information Services (IIS) Manager”.
2. Right-click the “Symbols” virtual directory that was added in the previous steps then choose “Properties”.
3. Click the “Directory Security” tab.
4. Under “Authentication and access control” click “Edit”
5. Ensure that only “Integrated Windows Authentication” is checked.
6. Make sure “Enable anonymous access” is unchecked
7. Click “OK” to exit the “Authentication Methods” dialog.
8. Click “OK” to exit “Symbols Properties”

The following command includes the web site “Identifier”. If you are not using the “Default Web Site” (which is site “1”), you will need to determine the correct identifier by highlighting the “Web Sites” folder and looking at the identifier listed in the right-hand pane for the applicable web site. Replace “1” in the following command with the correct identifier number.

Force NTLM authentication (remove Kerberos authentication)

1. Open a Command Prompt window.
2. Change directory to c:\inetpub\AdminScripts
3. Type the following including the quotes:
   cscript adsutil.vbs set W3SVC/1/root/Symbols/NtAuthenticationProviders "NTLM"

IIS is now ready to serve up files from http://SymMachineName/Symbols.  Test it out by restarting the IISAdmin service and configuring a debugger to get files with the symbol path set to srv**http://SymMachineName/Symbols.

Configuring an HTTP Symbol Server Proxy

You can configure your HTTP-based symbol store to act as a proxy between client computers and other symbol stores.  The implementation is through an ISAPI filter called SymProxy.dll.  The SymProxy server can be used as a gateway computer to the Internet or other sources within your company network. 

The Symbol Server Proxy can be a valuable setup for many situations. The following are some examples. 

• You are debugging many systems within a lab environment in which the computers are not attached to the company network, but the symbols are stored in the network and must be accessed using Integrated Windows Authentication. 

• Your corporate computing environment includes a firewall that prevents access to the internet from computers that are debugging and you need to get symbols from an internet web site such as http://msdl.microsoft.com/download/symbols. 

• You wish to present a single symbol path for all users in your company so that they don’t need to be aware of where symbols come from and so that you can add new symbol stores without user-intervention. 

• You have a remote site that is physically far from the rest of your company resources and network access is slow.  This system can be used to acquire symbols and cache them to the remote site. 

Installation of SymProxy requires the manual location of files, a way to authenticate your SymProxy to remote symbol stores, and reconfiguration of IIS.  You are also required to go through the “Configuring an HTTP Symbol Store” section of this document.

Installing the Filter 

Begin by installing the filter on the server.  Copy symproxy.dll and symsrv.dll to %WINDIR%\system32\inetsrv.   

Create a file called %WINDIR%\system32\inetsrv\symsrv.yes.  The contents of this file are of no consequence.  This prevents problems accessing the Microsoft Symbol Store at http://msdl.microsoft.com/downloads/symbols.

Configuring the Registry 

SymProxy stores its settings in the following registry key 

HKLM/Software/Microsoft/Symbol Server Proxy 

From this location, SymProxy learns what logging level to use as well the location from which to grab symbols for storage in the web site. 

You can create this key by running the symproxy.reg tool.  This tool is provided with the product.  Type “symproxy.reg” on the command line or simply double-click it from “Windows Explorer”.

Web Directories 

Within this key, a subkey named “Web Directories” exists.  It is in this key that the source paths from obtaining symbols is stored.  You need to create a separate key below here that matches the name of every virtual directory you generated in IIS to run a symbol store from.  For example, if you named this directory “symbols”, then create a registry key under “Web Directories” with that name. 

Then in each of the keys you have created, create a new “String Value” (REG_SZ) or “Expandable String Value” (REG_EXPAND_SZ) called “SymbolPath”.  Edit the contents of this value to contain all the symbol stores that will be used to feed the SymProxy symbol store.  If there is more than one, then separate them with semicolons.  A maximum of 10 stores is supported.  HTTP paths need to include the “http://” prefix and UNC paths need to include the “\\” prefix.

For example:

                \\symbols\symbols;http://msdl.microsoft.com/download/symbols

In this example, symbols will first be looked for in \\symbols\symbols.  If the files are not found there, then the Microsoft Symbol Store will be used. 

If the “SymbolPath” value is not properly set, the filter will not know where to obtain symbols from and it will not work.

It is also possible to define a global source for all symbol files by generating a “SymbolPath” value directly in the “Web Directories” key.  However this is highly discouraged, because it will cause malformed symbol requests from debugging clients to generate bogus directories and files in the root of your web site.

Logging

SymProxy reports its activity to the Application Event Viewer.  The level of reporting is set by the value stored in “LogLevel”.  This is a REG_DWORD located in the “Symbol Server Proxy” key.  Normally it is set to zero.  You can change this to any of the following values

0 - quiet 

1 - error

2 - success

3 – info

4 – warning

5 - debug

If you are having trouble moving files into the symbol store, you can adjust these values to see what is happening.  Set the “LogLevel” to 5 and all activity will be put in the Event Viewer.  If you want to see which files come from where and be able to examine the initialization, set the “LogLevel” to 3.

In order to complete the configuration of the logging, you need to register SymProxy with the Application Event Viewer.  Do this by adding the following key to the registry…

                HKLM\SYSTEM\CurrentControlSet\Services\EventLog\Application\SymProxy

Within this key, create a new “Expandable String Value” (REG_EXPAND_SZ) called “EventMessageFile”.  Set the contents of this to read as so…

“%WINDIR%\system32\inetsrv\symproxy.dll”. 

This will add symproxy.dll as a message source to the registry and cause application logging to work. 

HTTP Proxies

You may also need to set up HTTP proxy settings so that the service can access outside network resources.  You can do this using the proxycfg program.  Type “proxycfg.exe -?” for instructions.  The default behavior of SymProxy is to use whatever HTTP proxy is designated by this program.  If no HTTP proxy is configured, then SymProxy will use a dummy proxy.  The reason for this is to allow for access to secure HTTP sites within your intranet.  As a side effect, this prevents SymProxy from working with direct connections to the external internet.  You can disable this through the registry.  Create a REG_DWORD called “NoInternetProxy” located in the “Symbol Server Proxy” key.  If this value is set to 1 and there is no HTTP proxy indicated by proxycfg.exe, then SymProxy will operate with a direct connection to the internet.

Choosing Network Security Credentials

The web service needs to run from a security context that has the appropriate privileges to access the symbol stores that you intend to grab symbols from.  If you will be sourcing from an external web store such as http://msdl.microsoft.com/download/symbols, then this account will need to be able to access the web from outside any firewalls.  If you will be picking up any files from other computers on your network, then the account will need to have appropriate privileges to read files from those shares.  Some options available are to set the SymProxy to authenticate as the “Network Service” account, or to create a user account that is managed within Active Directory along with other user accounts, such as your own.

Authenticate as “Network Service”

The “Network Service” account is built-in to Windows, so there is no extra step of creating a new account.  For this example, we will presume the machine where the Symbol Proxy is being configured is SymMachineName on a domain called corp.

Note that external symbol stores (or internet proxy) will have to be configured to allow this machine’s “Network Service” account (Machine Account) to authenticate successfully.   There are 2 general methods of ensuring access:

1. Allow access to the “Authenticated Users” group on the external store (or internet proxy).
2. Allow access to the Machine Account, “corp\SymMachineName$”  This option is more secure because it limits access to just the Symbol Proxy machine’s “Network Service” account.

Authenticate as a Domain User

For this example, we will presume the user account is named SymProxyUser on a domain called corp. 

It is good practice that this account should only have privileges necessary to read files and copy them to c:\symstore.  This is to prevent the system from being corrupted in some manner by clients accessing your HTTP store.  

Add user account to the IIS_WPG group

1. From “Administrative Tools” open “Computer Management”
2. Expand “Local Users and Groups”
3. Click “Groups”
4. Double-click “IIS_WPG” in the right pane
5. Click the “Add” button
6. Enter “corp\SymProxyUser” in the pane labeled “Enter the object name to select”
7. Click “OK” to exit “Select Users, Computers, or Groups”
8. Click “OK” to exit “IIS_WPG Properties”
9. Close the “Computer Management” console
   

Note that external symbol stores (or internet proxy) will have to be configured to allow this user to authenticate successfully.  

Configuring IIS for SymProxy

IIS needs to be configured to use the symproxy.dll as an ISAPI filter.  Furthermore, permissions need to be set so that IIS can grab symbols.

Configure the Application Pool

1. From “Administrative Tools” open “Internet Information Services (IIS) Manager”
2. Right-click “Application Pools” and choose “New” à “Application Pool”
3. For the “Application ID” enter “SymSrv Pool”
4. Click “OK” to exit “Add New Application Pool”
5. Right-click the “SymSrv Pool” application pool and choose “Properties”
6. Click the “Identity” tab.
1. If you chose to authenticate as “Network Service”
   

                                                               i.      Choose “Predefined” for the “Application pool Identity”

                                                             ii.      Select “Network Service”

2. If you chose to authenticate as a Domain User
   

                                                               i.      Choose “Configurable” for the “Application pool identity”

                                                             ii.      Enter the credentials of the account that has permissions to access the remote symbol server store(s) (“corp\SymProxyUser”) , then click “OK”.

7. Click “OK” to exit “SymSrv Pool Properties” 

Set up the Virtual Directory

1. Expand “Web Sites”
2.  Expand “Default Web Site”
3. Right-click the “Symbols” virtual directory and choose “Properties”
4. While on the “Virtual Directory” tab click the “Create” button.
5. For the “Application Pool” drop-down choose “SymSrv” Pool”
6. Click “OK” to exit the “Symbols Properties”.

Configure the ISAPI Filter

1. Right-click the “Default Web Site” and choose “Properties” (or properties of applicable web site).
2. Click the “ISAPI Filters” tab.
3. Click “Add”
4. For “Filter Name” type “SymProxy” or some other meaningful name.
5. For “Executable” enter “c:\windows\system32\inetsrv\symproxy.dll”
6. Click “OK” to exit the “Filter Properties” dialog.
7. Click “OK” to exit the “Default Web Site Properties” 

Exclusions

In some environments, you may find yourself debugging systems for which there is a large quantity of modules loaded for which you cannot obtain symbols.  This is often the case if you have code that is called by another third-party vendor.  This can result in a lot of failed attempts to grab symbols.  This can be time-consuming and clog up network resources.  To alleviate this situation, you can use an Exclusion List to specify symbols that you don’t want to search for.  This feature exists in the client debugger. 

Alternately, you can configure the SymProxy filter to utilize its own the Exclusion List and prevent such network activity where it is most likely to take up resources.

The list is made up of the names of the files for which you want to prevent processing.  The file names can contain wildcards.  For example

      dbghelp.pdb

      symsrv.*

      mso*

The list can be implemented in two ways.  The first is an ini file, %WINDIR%\system32\inetsrv\symsrv.ini.  A section called “exclusions” should contain the list.

      [exclusions]

      dbghelp.pdb

      symsrv.*

      mso*

Alternately you can store the exclusions in the registry.  Create a key called HKLM\ Software\Microsoft\Symbol Server\Exclusions.  Store the file name list as string values (REG_SZ) within this key.  The name of the string value acts as the file name to exclude.  The contents of the string value can be used as a comment describing why the file is being excluded.

SymProxy reads from the Exclusion List every half-hour so that you don’t need to restart the web service to see changes take effect.  If the ini file exists, it will be used.  Otherwise the registry is checked.  SymProxy does not support the use of both symsrv.ini and the registry.  Simply add files to the list in the registry or ini file and wait a short period for the exclusions to be used.

Timeouts

If one of the symbol server stores that Symbol Server is configured to grab files from is down or otherwise unavailable, the result can be long waits from the client for every file request.  You can avoid most of these waits by setting up Symbol Server to stop trying to access the store in question.  When this feature is engaged, Symbol Server will stop trying to use the store for a set period of time after it experiences a specified number timeouts from the same store in another set period of time.  All three of these values can be controlled by an ini file or from the registry.

• trigger indicates the amount of minutes to look for the indicated amount of timeouts.
• count is the amount of timeouts to look for within the trigger period.
• blackout is the amount of minutes to disable the store once the threshold is reached.
  

In %WINDIR%\system32\inetsrv\symsrv.ini, create a section called “timeouts” and add the following values…

      [timeouts]

      trigger=10

      count=5

      blackout=15

You can set the “trigger” and blackout values to any amount of minutes you think is appropriate.  In this recommended example configuration, the store access will be turned off if 5 timeouts are experienced in a 10 minute period.  At the completion of a 15 minute blackout, the store will be reactivated. 

You can also use the registry in the same way.  Create a key called HKLM\ Software\Microsoft\Symbol Server\Timeouts.  Then add a REG_DWORD values called trigger, count, and blackout within this key.  Set the values as described previously.

Whether using the registry or an ini file, if the any of the trigger, count, or blackout values are set to 0 or if all such keys and values do not exist, this functionality will be disabled. 

This feature of Symbol Servers is currently only available when running as a service.  This means that the only practical application of this feature is when it is called from SymProxy.

Status

It is possible to see where symproxy is configured to acquire symbols from by using any browser software.  Just bring up status to get the information.  So if the symbols web site is http://server/symbols, then go to http://server/symbols/status.  You can also use this to cause symproxy to re-read its configuration information after making a change to the registry.  This is handy for changing the paths without having to restart the IIS service.

File Pointers

A UNC symbol store supports placing the actual files to be served in a separate location, with the client code learning of their whereabouts through file pointers.  These pointers are generated in the symbol store using symstore.exe with the “/p” option.  This scenario is supported with vanilla HTTP-based symbol stores only if the file pointers point to a UNC location that is directly accessible by the client.  When SymProxy is loaded into the web server, this functionality is enhanced.  The client no longer needs to be able to directly access the target files, because SymProxy will serve them through the HTTP interface.  This feature runs exclusive from the main proxy component discussed earlier and requires no preparation of the “Symbol Server Proxy” key in the registry.

Since this feature is automatically applied, an option exists to turn it off.  This is in case you want to use the proxy for serving some files and regular file pointer implementation for others.  To do this, create a REG_DWORD called NoFilePointerHandler in HKLM\Software\Microsoft\Symbol Server.  Set this value to 1 (or anything other than 0) to turn off the internal file pointer handler in symproxy. 

Double vs. Single File Caching

Normally, SymProxy caches the files it acquires into the directory designated within IIS as the virtual root for the associated web site.  Then IIS makes the file available to the client debugger.  Since the debugger cannot open a file directly from HTTP, it copies the file to a local cache, specified by the symbol path.

                srv*c:\localcache*http://server/symbols

In this example, the client debugger copies the file to c:\localcache.  In a situation such as this, the file is copied twice – once by SymProxy to the virtual root of the web site, and again by the debugger to its local cache.

It is possible to avoid the second copy operation and speed up processing.  To do this, you first need to share the virtual root of the web site as a UNC path that can be accessed by the debuggers.  For sake of example, we will call this \\server\symbols.

Then, remove the IIS configuration for mime types…

1. From “Administrative Tools” open “Internet Information Services (IIS) Manager”.
2. Expand “Web Sites”
3. Right-click “Default Web Site” (or other desired site)
4. Right-click the “Symbols” virtual directory and choose “Properties”
5. Click the “HTTP Headers” tab.
6. Click the “MIME Types” button.
7. Select all types in the list box labeled “Registered Mime Types”.
8. Click the “Remove” button.
9. Click “OK” to exit the “MIME Types” dialog.
10. Click “OK” to exit the “Symbols Properties”

 This will cause IIS to return “file not found” to the debugging client for all transactions on the web site.  However it will not prevent SymProxy from populating the virtual root with the file.

Lastly configure the debugger clients to look for symbols first in the HTTP store, and then in the share that maps to the virtual root of the store.

                srv**http://server/symbols;srv*\\server\symbols

In the above example, the first element of the symbol path (srv**http://server/symbols) says to get files from the HTTP store and copy them to the default symbol store as a local cache.  The specified cache is of no importance because no file will ever be received from the HTTP store.  After this failure, it will attempt to grab the file from the actual location of the virtual root of the store (srv*\\server\symbols).  This attempt should succeed because the file was copied to that location as a side effect of the previous path processing.

Try it out

The system should now be ready to acquire and serve up files.  Test it out by restarting the IISAdmin service and configuring a debugger to get files with the symbol path set to srv**http://server/symbols.

원문 : srcsrv.doc

General Concepts and Usage

Usage and Source Indexing

The source server enables a client to retrieve the exact version of the source files that were used to build an application. Because the source code for a module can change between versions and over the course of years, it is important to look at the source code as it existed when the version of the module in question was built.

The source server retrieves the appropriate files from source control. To use the source server, the application must have been source indexed.

Using Source Server with a Debugger

To use the source server with WinDbg, KD, NTSD, or CDB, ensure that you have installed a recent version of the Debugging Tools for Windows package (version 6.3 or later). Then, include srv* in the .srcpath command as follows:

.srcpath srv*;c:\mysource

Note that this example also includes a traditional source path. If the debugger cannot retrieve the file from the source server, it will search the specified path.

If a source file is retrieved by the source server, it will remain on your hard drive after the debugging session is over. Source files are stored locally in the src subdirectory of the Debugging Tools for Windows installation directory.

If you experience any trouble extracting the source files from the debugger, start the debugger with the –n command line parameter to view the actual source extraction commands along with the output of those commands.  !sym noisy will do the same thing, but you may have already missed important information from previous extraction attempts.  This is because the debugger will give up trying to access source from version control repositories that appear to be unreachable.

Retrieving the Source File

To facilitate the use of Source Server from tools other than the debuggers listed above, the DbgHelp API provides access to source server functionality through the SymGetSourceFile function. To retrieve the name of the source file to be retrieved, call the SymEnumSourceFiles or SymGetLineFromAddr64 function.

Source Indexing

The source indexing system is a collection of executable files and Perl scripts. The Perl scripts require Perl 5.6 or greater (not included). They are installed with the debugger package in a subdirectory sdk\srcsrv.  To work with these tools, they should all be installed in the path.

Generally, binaries are source indexed during the build process after the application has been built. The information needed by Source Server is stored in the PDB files. Source Server currently supports the following source-control systems…

Perforce
Microsoft Visual SourceSafe
Microsoft Team Foundation Server
CVS (Concurrent Versions System)

You can also create a custom script to index your code for a different source-control system.  One such module for Subversion is included in this package. 

While every attempt has been made to make these above-mentioned modules as bulletproof and robust as possible, the simple fact is, there is no way to account for all of the variance found in version control enlistments found throughout the world.  It is quite possible that you will not see success on the first attempt to use these tools and it is also possible that you will have to do a little debugging and even a little Perl coding to customize the scripts to your needs.  Here are a couple of hints.

Get familiar with srctool.exe and all of its command line options.  It is a valuable tool to see what is going on.

If it comes down to Perl debugging and programming, focus on the module that corresponds with your specific version control system.  These files end with an extension of .pm.  It is somewhat unlikely that your problem is in the master script, (ssindex.cmd).

Feel free to ask questions on our newsgroup, microsoft.public.windbg.

The following table lists the Source Server tools.

To prepare for source indexing, edit srcsrv.ini so that it contains an entry for your version control server.  This is an operation that you will do only once.  Details are listed in the sample version of this file.  You can use an environment variable or switch to the indexing script to denote the location of this file.   However, it is best to put it in the same directory as the script, because the contents of this file are intended to be global across all projects in your business or development system.  This file serves to uniquely identify different version control servers.  Note that you can provide a different version of this file to debuggers so that they look at a replicated copy of the version control server.  This can be useful if you want to reduce traffic on the server.

To source index a particular build, make certain that no source files are checked out on the build computer.  If any files are checked out and edited, then those changes will not be reflected in the final source indexed PDB files.  Furthermore, if your build process includes a pre-compilation pass that generates source files from other files, then you need to check those generated files into version control as part of the pre-compilation.

Upon completion of the build, set the current working directory to be the root of all source and generated PDB files.  Then run the indexing script ssindex.cmd.  You will need to specify what version control system you are using as a parameter.  For example:

ssindex.cmd –server=vss

Ssindex.cmd accepts parameters that allow you to run the script from anywhere and to specify the location of the source files and pdb separately.  This is most useful if the source is kept in another location from the output pdb files.  Example:

ssindex.cmd –server=vss –source=c:\source –symbols=c:\outputdir

These directories can also be specified with environment variables.  Use the -? or -?? command line options for more information...

C:\ >ssindex.cmd -system=vss -?
--------------------------------------------------------------------------------
SSIndex.cmd [/option=<value> [...]] [ModuleOptions] [/Debug]

General source server settings:

     NAME              SWITCH      ENV. VAR        Default
  -----------------------------------------------------------------------------
  1) srcsrv.ini        Ini         SRCSRV_INI      .\srcsrv.ini
  2) Source root       Source      SRCSRV_SOURCE   .
  3) Symbols root      Symbols     SRCSRV_SYMBOLS  .
  4) Control system    System      SRCSRV_SYSTEM   <N/A>
  5) Save File (opt.)  Save        SRCSRV_SAVE     <N/A>
  6) Load File (opt.)  Load        SRCSRV_LOAD     <N/A>

Visual Source Safe specific settings:

     NAME            SWITCH      ENV. VAR        Default
  -----------------------------------------------------------------------------
  A) VSS Server      Server      SSDIR            <N/A>
  B) VSS Client      Client      SSROOT           <Current directory>
  C) VSS Project     Project     SSPROJECT        <N/A>
  D) VSS Label       Label       SSLABEL          <N/A>

Precedence is: Default, environment, cmdline switch. (ie. env overrides default,
switch overrides env).

Using '/debug' will turn on verbose output.

Use "SSIndex.cmd -??" for verbose help information.

See the Source Server documentation for more information.
--------------------------------------------------------------------------------

You can also use one of the provided wrapper scripts (vssindex.cmd) to avoid specifying the version control system.  The script will source index all PDB files found in the current directory and below, with version control information to locate all source files found in the current directory and below.  You can specify different locations for these files by using environment variables and command line switches.

Upon completion of the source indexing, you can test the output by running srctool.exe on the PDB files.  This program will display whether the PDB is source indexed or not.  It will also display the specific information for every source file.  Lastly, it displays the number of indexed sources and the number of sources that no indexing information was found for.  It sets an %ERRORLEVEL% of -1 if the file is not source indexed.  Otherwise it sets %ERRORLEVEL% to the number of indexed source files.

Creating a Source Control Provider Module

The source server includes provider modules for Perforce (p4.pm) and Visual Source Safe (vss.pm).   It is possible to generate your own modules to support other version control systems.  Included in this package is svn.pm, which was written by Shahar Talmi of Safeend, Ltd.  This shows how you can modify one of the existing scripts to support the Subversion Version Control system.

To create your own provider module, you must implement the following set of interfaces.

$module::SimpleUsage()

Purpose: Displays simple module usage information to STDOUT.

Parameters: None

Return value: None

$module::VerboseUsage()

Purpose: Displays in-depth module usage information to STDOUT.

Parameters: None

Return value: None

$objref = $module::new(@CommandArguments)

Purpose: Initializes an instance of the provider module.

Parameters: All @ARGV arguments that weren’t recognized by ssIndex.cmd as being general arguments.

Return value: A reference that can be used in later operations.

$objref->GatherFileInformation($SourcePath, $ServerHashReference)

Purpose: Enables the module to gather the required source indexing information for the directory specified by the $SourcePath parameter. The module should not assume that this entry will be called only once for each object instance, as ssIndex.cmd may call it multiple times for different paths.

Parameters:  (1) The local directory containing the source to be indexed.  (2)  A reference to a hash containing all of the entries from the specified srcsrv.ini file.

Return value: None

($VariableHashReference, $FileEntry) = $objref->GetFileInfo($LocalFile)

Purpose: Provides the necessary information to extract a single, specific file from the source control system.

Parameters: A fully-qualified file name

Return value:  (1)  A hash reference of the variables necessary to interpret the returned $FileEntry.  SSIndex.cmd caches these variables for every source file used by a single debug file to reduce the amount of information written to the source index stream.  (2)  The file entry to be written to the source index stream to allow SrcSrv.dll to extract this file from source control. The exact format of this line is specific to the source control system.

$TextString = $objref->LongName()

Purpose: Provides a descriptive string to identify the source control provider to the end user.

Parameters: None

Return value: The descriptive name of the source control system.

@StreamVariableLines = $objref->SourceStreamVariables()

Purpose: Enables the source control provider to add source control specific variables to the source stream for each debug file. The sample modules use this method for writing the required EXTRACT_CMD and EXTRACT_TARGET variables.

Parameters: None

Return value: The list of entries for the source stream variables.

Language Specification Version 1

Source Server Data Blocks

Source server relies on two blocks of data within the PDB file.

• Source file list.  Building a module automatically creates a list of fully-qualified paths to the source files used to build the module.
• Data block.  Indexing the source as described previously adds an alternate stream to the PDB file named “srcsrv”. The script that inserts this data is dependent on the specific build process and source control system in use.

The data block is divided into three sections: ini, variables, and source files. It has the following syntax.

SRCSRV: ini ------------------------------------------------
VERSION=1
VERCTRL=<source_control_str>
DATETIME=<date_time_str>
SRCSRV: variables ------------------------------------------
SRCSRVTRG=%sdtrg%
SRCSRVCMD=%sdcmd%
SRCSRVENV=var1=string1\bvar2=string2
DEPOT=//depot
SDCMD=sd.exe -p %fnvar%(%var2%) print -o %srcsrvtrg% -q %depot%/%var3%#%var4%
SDTRG=%targ%\%var2%\%fnbksl%(%var3%)\%var4%\%fnfile%(%var1%)
WIN_SDKTOOLS= sserver.microsoft.com:4444
SRCSRV: source files ---------------------------------------
<path1>*<var2>*<var3>*<var4>
<path2>*<var2>*<var3>*<var4>
<path3>*<var2>*<var3>*<var4>
<path4>*<var2>*<var3>*<var4>
SRCSRV: end ------------------------------------------------

All text is interpreted literally, except for text enclosed in percent signs (%). Text enclosed in percent signs is treated as a variable name to be resolved recursively, unless it is one of the following functions:

%fnvar%()

The parameter text should be enclosed in percent signs and treated as a variable to be expanded.

%fnbksl%()

All forward slashes (/) in the parameter text should be replaced with backward slashes (\).

%fnfile%()

All path information in the parameter text should be stripped out, leaving only the file name.

The ini section contains variables that describe the requirements. The indexing script can add any number of variables to this section. The following are examples:

VERSION

The language specification version. This variable is required.   Someone developing a script based on this language specification should set this value to 1.  The Source Server client code will not attempt to execute any script that has a value greater than it.  Current versions of srcsrv.dll use the value of 2. 

VERCTL

A string that describes the source control product. This variable is optional.

DATETIME

A string that indicates the date and time the PDB file was processed. This variable is optional.

The variables section contains variables that describe how to extract a file from source control. It can also be used to define commonly used text as variables to reduce the size of the data block.

SRCSRVTRG

Describes how to build the target path for the extracted file. This is a required variable.

SRCSRVCMD

Describes how to build the command to extract the file from source control. This includes the name of the executable file and its command-line parameters. This is required if any extraction command needs to be executed.

SRCSRVENV

A string that lists environment variables to be created during the file extraction. Separate multiple entries with a backspace character (\b). This is an optional variable.

SRCSRVVERCTRL

Specifies the version control system in use.  For Perforce, this is “perforce”.  For Visual SourceSafe, this is “vss”.  For Team Foundation Server, this is “tfs”.  This variable is used to persist server errors. This is an optional variable.

SRCSRVERRDESC

This is a text snippet that matches what is emitted by the version control client when it is unable to contact the server that contains the source files to extract.  Source Server uses this value to check for connection problems. This is an optional variable.

SRCSRVERRVAR

This indicates which variable in a file entry corresponds to a version control server.  It is used by Source Server to identify commands that won’t work, based on previous failures.  The format of the text is “varX” where X is the number of the variable being indicated.  This is an optional variable.

The source files section contains an entry for each source file that has been indexed. The contents of each line are interpreted as variables with the names VAR1, VAR2, VAR3, and so on until VAR10. The variables are separated by asterisks. VAR1 must specify the fully-qualified path to the source file as listed elsewhere in the PDB file. For example, the following line:

c:\proj\src\file.cpp*TOOLS_PRJ*tools/mytool/src/file.cpp*3

is interpreted as follows:

VAR1=c:\proj\src\file.cpp
VAR2=TOOLS_PRJ
VAR3=tools/mytool/src/file.cpp
VAR4=3

In this example, VAR4 is a revision number. However, most source control systems support labeling files in such a way that the source state for a given build can be restored. Therefore, you could alternately use the label for the build. The sample data block could be modified to contain a variable such as the following:

LABEL=BUILD47

Then, presuming the source control system uses the at sign (@) to indicate a label, you could modify the SRCSRVCMD variable as follows:

sd.exe -p %fnvar%(%var2%) print -o %srcsrvtrg% -q %depot%/%var3%@%label%

How Source Server Works

The source server client is implemented in symsrv.dll. The client does not extract information directly from the PDB file; it uses a symbol handler such as the one implemented in dbghelp.dll. It is essentially a recursive variable substitution engine that creates a command line that can be used to extract the proper source file from the source control system. Your code should not call Symsrv.dll directly. To integrate its functionality into your application, use the SymGetSourceFile function.

The first version of source server works as follows.  (This behavior may change in future versions.)

First, the client calls SrcSrvInit with the target path to be used as a base for all source file extractions.  This path is stored in the special variable TARG.

When dbghelp loads a module’s PDB file, it extracts the SrcSrv stream from the PDB and passes this data block to SrcSrv by calling SrcSrvLoadModule.

Then when dbghelp needs to grab a source file, it calls SrcSrvGetFile to retrieve a specified source file from version control.

Srcsrv looks through all the source file entries in the data block for an entry that matches exactly the requested source spec.  This match is to be found in VAR1.

Once srcsrv finds the entry, it fills in the special variables (VAR1, VAR2, etc.) with the contents of this source file entry.

Now the SRCSRVTRG variable is resolved using these special variables.  Beginning with the source line used in the previous example, the following shows how these variables are resolved.  Each line shows the resolution of one more special variable.  The resolved variables are shown in red.

SRCSRVTRG=%sdtrg%

SDTRG=%targ%\%var2%\%fnbksl%(%var3%)\%var4%\%fnfile%(%var1%)

c:\src\%var2%\%fnbksl%(%var3%)\%var4%\%fnfile%(%var1%)

c:\src\WIN_SDKTOOLS\%fnbksl%(%var3%)\%var4%\%fnfile%(%var1%)

c:\src\WIN_SDKTOOLS\%fnbksl%(sdktools/debuggers/srcsrv/shell.cpp)\%var4%\%fnfile%(%var1%)

c:\src\WIN_SDKTOOLS\sdktools\debuggers\srcsrv\shell.cpp\%var4%\%fnfile%(%var1%)

c:\src\WIN_SDKTOOLS\sdktools\debuggers\srcsrv\shell.cpp\3\%fnfile%(%var1%)

c:\src\WIN_SDKTOOLS\sdktools\debuggers\srcsrv\shell.cpp\3\%fnfile%(c:\db\srcsrv\shell.cpp)

c:\src\WIN_SDKTOOLS\sdktools\debuggers\srcsrv\shell.cpp\3\shell.cpp

Notice how this generated target path is unique and will not allow two versions of the same file to be extracted to the same location.

Srcsrv now looks to see if the file is already there.  If it is, srcsrv returns the location to the caller.  Otherwise, srcsrv builds the execution command to extract the file by resolving SRCSRVCMD.

In the following example, each line shows the resolution of one more special variable.  The resolved variables are shown in red.

DEPOT=//depot

WIN_SDKTOOLS= sserver.microsoft.com:4444

SRCSRVCMD=%sdcmd%

SDCMD=sd.exe -p %fnvar%(%var2%) print -o %srcsrvtrg% -q %depot%/%var3%#%var4%

sd.exe -p %fnvar%(WIN_SDKTOOLS) print -o %srcsrvtrg% -q %depot%/%var3%#%var4%

sd.exe -p sserver.microsoft.com:4444  print -o %srcsrvtrg% -q %depot%/%var3%#%var4%

sd.exe -p sserver.microsoft.com:4444  print -o c:\src\WIN_SDKTOOLS\sdktools\debuggers\srcsrv\shell.cpp\3\shell.cpp -q %depot%/%var3%#%var4%

sd.exe -p sserver.microsoft.com:4444  print -o c:\src\WIN_SDKTOOLS\sdktools\debuggers\srcsrv\shell.cpp\3\shell.cpp -q //depot/%var3%#%var4%

sd.exe -p sserver.microsoft.com:4444  print -o c:\src\WIN_SDKTOOLS\sdktools\debuggers\srcsrv\shell.cpp\3\shell.cpp -q //depot/ sdktools/debuggers/srcsrv/shell.cpp#%var4%

sd.exe -p sserver.microsoft.com:4444  print -o c:\src\WIN_SDKTOOLS\sdktools\debuggers\srcsrv\shell.cpp\3\shell.cpp -q //depot/ sdktools/debuggers/srcsrv/shell.cpp#3

Now srcsrv executes this command line.  If the result of this command line is a file in the expected location, then this path is returned to the caller.

Note that if a variable cannot be resolved, an attempt is made to look it up as an OS environment variable.  If that fails, the variable name is deleted from the text being processed.

Two consecutive percent sign characters are interpreted as a single percent sign.

Handling Server Errors

Sometimes a client will be unable to extract any files at all from a single version control server.  This can be because the server is down and off the network or because the user does not have appropriate privileges to access the source.  However the time consumed attempting to get this source can slow things down significantly.  In this situation, it is desirable to disable any attempt to extract from a source that has been proven to be unavailable.

Whenever Source Server fails to extract a file, it examines the output text produced by the command.  If any part of this command contains an exact match for the contents of the SRCSRVERRDESC, then all future commands to the same version control server will be skipped.  Note that you can define multiple error strings by adding numbers or arbitrary text to the end of the SRCSRVERRDESC variable name.  Examples:

SRCSRVERRDESC=foo: server not found
SRCSRVERRDESC_2=bar: network error

The identity of the server is acquired from SRCSRVERRVAR. So if SRCSRVERRVAR contains “var2” and the file entry in the pdb looks like this…

c:\proj\src\file.cpp*TOOLS_PRJ*tools/mytool/src/file.cpp*3

Then all future attempts to grab source using a file entry that contains “TOOLS_PRJ” in variable 2 will be bypassed.               

You can also add error indicators on the debugger client by editing srcsrv.ini.  Instructions are provided in the sample file provided.

API and Usage

This document allows you to understand how to prepare instrumentation scripts so that this source server technology can be integrated into your build or version control system.

This document exposes many of the specifics of how srcsrv.dll is called by symbol handler code.  However this information is not static and will not become so in the future.  No one should attempt to write code that calls srcsrv.dll directly.  This is reserved for dbghelp.dll or the Visual Studio products.  Third party vendors wishing to integrate such functionality in their products should use the SymGetSourceFile function.  This function, along with others in the DbgHelp API, is described in the dbghelp.chm documentation.

Language Specification Version 2

SRCSRVCMD

This package ships with a srcsrv.dll that is able to operate without SRCSRVCMD being defined in the srcsrv data stream of a PDB.  While such capability is of no use for normal file extraction from source control systems, it is useful for direct access of files from a UNC share or HTTP site.  Such usage is described later in this document.

Notes on Visual SourceSafe

The Database

The default Visual SourceSafe database can be set with the SSDIR environment variable.  If it is not set there, the Source Server indexing script can usually determine this from the registry.  If it can’t, the script will prompt you to set SSDIR.  Regardless, this database value must be listed in your srcsrv.ini file along with a simple alias to identify the database.  More instructions can be found in the comments in srcsrv.ini.  You should add the entry in the [variables] section of the file as so…

   MYDATABASE=\\server\VssShare

Current Project

Visual SourceSafe works with the concept of a “current project”.  The Source Server indexing script respects this value and limits itself to process only source files that are part of the current project.  You can see what the current project is with the “ss.exe project” command.  If you want to change the current project, you can do so with the “ss.exe cp” command.  For example, if you want all projects to be processed you would do so by setting the current project to the root, as so…

   ss.exe cp $/

Working Folder

Visual SourceSafe projects are associated with “working folders”.  A working folder is the location on the client computer which corresponds to the root of a project.  However it is possible for such a computer to obtain and build source without a working folder being specified, normally through “ss.exe get –R” or when creating projects through the Visual Studio interface.  This mode of operation is incompatible with Source Server indexing.  Source Server requires that a working folder be specified.  If you have not set a working folder, you can do so with the following command…

   ss.exe workfold <project> <folder>

Labels

Visual SourceSafe is not able to determine what version of a file exists within the working directory of a build machine.  Consequently, you must use labels to stamp the project with an identifier that will be used to extract source files on the debugger client.  So before indexing, you need to make sure that all changes are checked into the database and then apply a label to it with the “ss.exe label” command.  In the following example, the label “VERSION_3” is applied to a project called “$/sdktools”…

E:\nt\user>ss.exe label $/sdktools
Label for $/sdktools: VERSION_3
Comment for $/sdktools:
This is a comment.

After the label is applied, you can specify this label to the Source Server indexing script by setting the environment variable, SSLABEL, or by passing it as a command line parameter…

   vssindex.cmd –label=VERSION_3

Again, this label is required for Source Server indexing to work.  Note that if you pass a label that doesn’t exist in the project, it might take a long time for the script to complete and the results will be of no use.

Credentials

If your Visual SourceSafe database requires a user and optional password in order to access it, then these values must be set through the SSUSER and SSPWD environment variables.  This applies not only at the time the build is indexed, but also on the debugger client. 

Platform

Visual SourceSafe is an X86 application and the source indexing scripts and tools for it are installed only with the X86 package of Debugging Tools for Windows.

Debugging

As described previously, SSUSER and SSPWD may need to be set in your debugging environment.  Furthermore, please note that the version of srcsrv.dll that ships with Visual Studio 2005 is not able to detect if Visual SourceSafe (ss.exe) is prompting for credentials.  This will result in a hang in the application.  You can upgrade with the srcsrv.dll that ships with “Debugging Tools for Windows” to prevent this.  Regardless, the credentials must be set for source extraction to work, if your Visual SourceSafe database requires them.

If Visual SourceSafe is not set in the path of your debugging computer, you can get around this by adding an entry to the srcsrv.ini file that works with your debugger.  When using a standard installation of Visual Studio, this file should be located in the following location…

%PROGRAMFILES%\Microsoft Visual Studio 8\Common7\IDE\srcsrv.ini

In the [trusted commands] section described previously, add an entry like the following, making sure that the path points to the correct location of ss.exe.

ss.exe=”C:\Program Files\Microsoft Visual SourceSafe\ss.exe”

VSSDump

VSSDump.exe is a program that is used by the indexing scripts to locate and resolve source files to the database.  You can also use this program standalone so as to diagnose issues when source indexing.  Calling the program with “-?” will list the command line parameters…

vssdump: enumerates files in the current VSS project.
      -a                ignores the current project and lists all projects.
      -p:<projectname>  specifies a VSS project to use.
                        not to be used -with '-a'
      -d:<directory>    specifies a root directory
                        otherwise the current directory is used.
      -l:<label>        specifies a version label
      -t                don't test version to match a passed label
      -v:<sharepath>    specifies location of the VSS database - overrides SSDIR
      -r                recurse subdirectories
      -f                don't list files - just directories
      -i                ignore current directory and list entire project
                        not to be used with '-r'
      -s                format output for scripting
      -c                display only the VSS configuration info

Notes on CVS (Concurrent Versions System)

Disclaimer

The cvs module for Source Server was developed using Concurrent Versions System (CVS) 1.11.17 (client).  It has not been tested with any other versions of cvs.  Furthermore it has not been tested extensively.  We have noticed that the great variance in user installations has exposed a lot of opportunities for the scripts to fail.  So anyone using this script should consider that there is a chance he or she will have to do a little Perl debugging of the scripts to make they work out.  Those finding they need to do this should please let us know by posting to the microsoft.public.windbg newsgroup so that we can help you and enhance the scripts.

CVSROOT

On the machine that you source index the build, CVSROOT cannot contain password and user information.  You should use cvs.exe to set your credentialing information.

To prepare srcsrv.ini for cvs indexing you need to enter an alias for your repository that will uniquely identify it from any others in your network.  This repository needs to match the value of CVSROOT in your environment.  There is no need to set this value in the srcsrv.ini that you keep with your debugger clients since the alias will be defined in the source indexed pdb.

 Client Computer

The client computer that will be extracting files during debugging does not need a cvs sandbox or CVSROOT set.  It does need cvs binaries in the path and if the repository is locked, you will need to set the username and password with cvs.exe.

Revision Tags

Cvs is unable to extract a file by its version number.  Instead it must be done using what is known as a “tag”.  So when indexing a cvs-based system you need to make sure that all changes are checked into the repository and then apply a tag with the “cvs tag” command.  Then when indexing the file, make certain you use the “label” command line parameter to specify the tag that you want to associate with the build you are indexing.   You can achieve the same result by setting CVS_LABEL in the environment.  Other values can be set from the environment or the command line.  Don’t forget to use the -? command line parameter to examine your choices and to make sure that all was configured correctly.

ssindex.cmd –system=cvs -??

Notes on Team Foundation Server

The script provided for processing using TFS is incapable of working with labels that have spaces in them.  Code as been added to the script to handle spaces in the labels, however it is commented out for stability.  If you wish to source index with TFS using labels and you want to allow spaces in the labels, please examine the code at line 453 of tfs.pm.

HTTP Sites and UNC Shares

It is possible to set up a web site that provides version-specific source to the windbg.exe debugger through the srcsrv module.  Such a mechanism does not provide dynamic extraction of the source files from version control; however it is a valuable feature because it allows you to set the source path of windbg.exe to a single unified path that will provide source from many versions of many modules, instead of having to set separate paths for each debugging scenario.  This is not of interest to debugging clients that have direct access to the actual version control systems, but can be of assistance to those wanting to provide secure http-based access to source from remote locations.  The web sites in question can be secured through HTTPS and smartcards, if desired.  This same technique can be used to provide source files through a simple UNC share. 

Set up the web site

Set up a web site to share the source files from and note the root directory of the site.  You will probably also want to make the pdbs available on the web site, using Symbol Server technology.  So you might have symbols and source made available from locations such as this…

   https://diehelkthidoeodlby.com/symbols
   https://diehelkthidoeodlby.com/source

While it is outside the scope of this document to describe how to set up a web site, there are some step-by-step instructions for doing this in symhttp.doc that ships with the “Debugging Tools For Windows” package.  Please note that much of these instructions apply specifically to symbol servers.

Extract and locate the source files

Use srctool.exe –x to extract all the source files from all the modules that you want to provide source for.  You need to run this tool on pdb files that have already been source indexed for your version control system and you will need to run the tool on a computer that has version control access.  This will put all the source files into a common directory tree.  Copy the contents of this tree to the root of the web site.  You can do this as often as you wish on any new products or modules that you wish to add.  There is no worry about files overwriting each other, since the directory tree structure keep dissimilar files separated and uniquely accessible.

A script file called walk.cmd is provided in this package to make it easier to run srctool.exe and other scripts on all matching files within a directory tree.  walk.cmd walks recursively through a directory tree and executes any specified command on any file that matches a passed file mask.  You can pass a simple file mask if you want it to start in the current working directory, or you can pass the starting directory with the file mask.  Here is an example…

   walk.cmd c:\symbols\*.pdb srctool.exe -x

This will run the srctool file extraction on all pdb files in c:\symbols or directories below it.

Modify the pdb source indexing streams

pdb:       specifies the name of the pdb to modify. For the debugger clients to use the Source Server web site, the pdbs must be modified to point to it.  Normally you would make a copy of all the pdbs, change them, and make them available from a separate location, usually the web site, itself. 

Three files are provided to assist you in reconfiguring the pdbs.  cv2http.cmd and cv2http.pl extract the Source Server stream, modify it through a perl script, and put the altered stream back in the pdb.

   cv2http.cmd: pdb  alias  url
                you must specify a pdb file,
                a logical http site alias
                and the URL of the site

The script takes three required parameters…

pdb:             specifies the name of the pdb to modify.
alias:            specifies the logical name to apply to your web site.
url:                specifies the full URL of the site.

The alias parameter is especially interesting; as it will be stored in the pdb as a variable name that can be overridden on the debugger client in srcsrv.ini should you ever move the location of the web site.

This script requires that all the standard Source Server tools be available in the path, since it calls both srctool.exe and pdbstr.exe.  Don’t forget that cv2http.pl is a Perl script and can be modified as you see fit to meet your needs.

You can use walk.cmd to modify an entire set of pdb files.

   walk.cmd *.pdb cv2http.cmd HTTP_ALIAS https://diehelkthidoeodlby.com/source

The above command will call cv2http.cmd on every pdb file in a tree, passing the following parameters…

the name of each pdb
HTTP_ALIAS for the alias
https://diehelkthidoeodlby.com/source for the url.

After running this command on a tree of pdb files, they will be ready for installation into the web site (or whatever location you want to put them.  You may want to refer to the Symbol Server documentation for more details on this.  Remember that you can use srctool.exe and pdbstr.exe to examine the changes to the pdbs.

UNC Shares

There is nothing preventing you from using these same scripts to provide source files from a simple UNC share.  To do this, just eliminate all the previously described steps for setting up a web site.  When calling cv2http.cmd, replace the url parameter with the root of the UNC share that you extracted the source files to with srctool.exe, like so…

walk.cmd *.pdb cv2http.cmd MY_SOURCE_ROOT \\server\share

Supporting HTTP/UNC along with regular version control with the same pdb

Imagine the scenario in which you want to support your developers using the standard Source Server functionality that extracts files from version control, however you also want to make source files available through a web site or UNC share.  This may make sense if you have set up a test lab that does not have access to version control.  It is possible to support both users using the same set of pdbs.

First, extract the source files using srctool.exe as described previously and make the share available as either a web site or UNC share.  Then ignore all the steps that convert the pdbs using cv2http.cmd. 

Now on the computers that will use the HTTP/UNC shares, edit the srcsrv.ini that is in the debugger directory.  In the [variables] section of the file, add the following three statements…

MY_SOURCE_ROOT=\\server\share
SRCSRVCMD=
SRCSRVTRG=%MY_SOURCE_ROOT%\%var2%\%var3%\%var4%\%fnfile%(%var1%)

You should replace “\\server\share” with the root of  the UNC share you are providing or the URL of the web site that contains the source files.  You can also change “MY_SOURCE_ROOT” to be any alias you want that describes this location.  With these exceptions, everything else should be entered exactly as described.

All debuggers set up in this fashion will ignore the standard version control extraction instructions, and will, instead, access the source files from the location specified.  Meanwhile, all debuggers without these items included in srcsrv.ini will use the normal version control mechanism to extract source files.